企业官网建设流程全解析

1. 为什么需要一份“三层架构重构项目文档”

先讲个背景。这几年做后端开发的同行应该都有同感，很多老项目的代码不是设计出来的，而是“长”出来的。业务迭代一快，Controller 里塞满业务逻辑，SQL 散落在各个页面调用的 Service 里，工具类像公用电话亭一样被谁都能用。我手头这个模拟项目 X 就是这种情况——一个运行了将近五年的业务系统，核心模块的代码量已经膨胀到难以维护。每次加需求，光梳理调用关系就要花掉半天，改一个字段要动七八个文件，回归测试一轮下来，人先崩溃了。

当时我们面临的选项，其实不是“要不要重构”，而是“怎么重构才不至于翻车”。在对比了微服务拆分、领域驱动设计、整洁架构等几种路线之后，最终选择了三层架构作为重构的目标形态。原因很朴素，团队规模不大，业务场景属于典型的 CRUD 密集型系统，没有复杂的分布式诉求。三层架构——表现层、业务逻辑层、数据访问层——刚好能把关注点分开，又不至于引入过高的认知负担和运维成本。

这份文档就是在那个背景下产出的。它不是一份“流程说明”，而是把整个重构从动因、方案选型、分层约定、接口规范、异常处理、数据访问策略，到迁移计划、回归验证、团队协作规则全部沉淀下来的完整记录。如果你正在准备对老项目做结构治理，或者你只是想知道一份架构文档到底该写什么、写到什么深度，这篇内容应该能给你一个比较具体的参考。

需要说明的是，我分享的不是什么理论推演，而是整套方案在某公司内部系统上实际落地过的做法。有些选择在纯技术视角下不是最优的，但在当时的人力、进度、风险约束下，是最合适的。这一块后面会专门展开讲，因为架构设计最怕的就是脱离约束谈理想。

2. 项目背景与重构动因拆解

2.1 系统现状：代码腐化从哪开始

这个系统最初的开发方式，说实话，是典型的“快跑快上线”。数据库表直接跟着页面设计，一个页面一张主子表的情况很多。业务逻辑分布在两个地方：一部分写在 UI 事件里，一部分堆在几个上帝类中。所谓上帝类，就是那种什么都能干、方法数量上百个、依赖一半项目文件的类。最夸张的一个类有 3000 多行，里面既有数据校验，又有状态变更，还直接拼 SQL 去查询数据库。

当时我们做了一次简单的代码规模统计，结果触目惊心：

• 表现层和数据访问代码的耦合度高到离谱，UI 里直接操作 DbConnection 的代码占比超过四成。
• 大约 70% 的业务规则无法通过单元测试覆盖，因为测试的启动成本太高，需要拉起整个运行环境。
• 数据库访问没有统一入口，同一个查询逻辑在三个地方有实现，而这三处的行为还不完全一致——有一处会过滤已删除数据，另一处不过滤。
• 新增一个简单的列表查询接口，平均需要改动 4 到 5 个文件，牵一发而动全身。

这些数据其实就是重构的“证据”。团队内部讨论过：如果继续在这样的地基上加楼层，哪怕只是维持现有业务的功能稳定，都要投入越来越多的资源。而那次重构立项的直接触发点，是业务方提出要把一个核心流程从串联改造成并联，涉及跨模块的状态流转和权限联动。相关负责人带着技术方案去评审，结果发现光是说明改动影响范围就讲了两个小时，还没法给出一个清晰的改动清单。

2.2 目标定义：三层架构重构到底解决什么问题

目标不能拍脑袋定。我们在重构启动前，花费了大量时间把目标写清楚，并且每条目标都对应到可验证的结果上。三层架构重构的目标不是“让代码更好看”——好看不是可衡量的东西。

具体目标包含：

• 强制分离表现层、业务逻辑层、数据访问层，从物理项目结构上杜绝 UI 直接访问数据库的可能。
• 业务逻辑收敛到业务服务层，所有业务规则具备明确的宿主位置，新增需求时，开发人员能快速定位应该修改哪个类的哪个方法。
• 数据访问统一走仓储接口，数据库表结构的变更只影响数据访问层内部实现，上层代码不感知。
• 建立接口规范与依赖方向约定，项目之间只允许上层依赖下层，不允许反向依赖或同层横向依赖。
• 通过依赖注入解耦具体实现，让核心业务逻辑可以脱离数据库和 UI 进行单元测试，显著提升测试效率。

我一直觉得架构重构最大的难点不在技术，而在“让团队对目标形成共识”。如果你问十个开发人员“重构是为了什么”，得到五个答案，这个重构基本要乱。所以在文档里，我把目标分成了两个层次：

第一层是工程质量指标，比如耦合度下降、重复代码率降低、单元测试覆盖率提升；第二层是业务响应指标，比如需求平均开发工时下降、缺陷率下降。第一层是手段，第二层是最终要交付给业务方的价值。很多架构文档只写了“我们做了什么”，没写“我们为什么要做这些”，这是我觉得特别遗憾的事情。

2.3 方案选型：为什么是三层架构，而不是微服务或 DDD

在这个部分必须说点实在的。当时团队内部不是没有争议，有成员提出直接上微服务，也有成员认为应该采用领域驱动设计做聚合划分。我个人的观点是：架构选型的关键是匹配组织能力与业务复杂度，而不是追逐技术名词。

微服务拆分的启动成本与运维成本，是当时团队无法承受的。团队满打满算只有七名开发人员，其中还有两名是刚入职不久的新人。如果强行拆成多个服务，光基础设施与部署链路的搭建就需要至少一个月，而当时留给整个重构的窗口期只有三个月。领域驱动设计则是一个非常优秀的思考工具，但它的战术模式实施门槛偏高，需要团队对领域模型的认知达到相当一致的程度——否则很容易出现每个模块一套“自己的 DDD”，反而比原来的上帝类更难维护。

三层架构的优势在于：

• 认知成本低。表现层、业务逻辑层、数据访问层三层划分，任何一个有基本开发经验的人都能快速理解边界在哪里。
• 渐进式重构的可行性高。不需要一夜间把所有代码改造完，可以按模块逐步迁移，每完成一个模块就能收获一部分成果。
• 技术栈延续性。不需要引入新的基础设施组件，原有的数据库、框架、部署方式都可以保留，主要变的是代码的组织结构。

还有一点我觉得值得分享：三层架构听起来“老派”，但它恰恰是后续演进的基础。如果将来真的要拆微服务，业务逻辑层和数据访问层的分离，会让你更容易识别出哪些逻辑属于独立业务域。换句话说，三层架构不是终点，而是通往更复杂架构路径上的稳定踏脚石。

3. 重构设计：核心细节与关键决策

3.1 分层职责边界：容易被模糊掉的部分

三层架构最大的坑，不是分不清层，而是在细节处模糊掉边界。文档里我对每一层的职责做了非常明确的“白名单”定义，这比任何高深的架构描述都更有约束力。

表现层负责的是：

• 接收用户输入，完成基础格式校验（非空、长度、类型）。
• 调用业务逻辑层接口，获取结果。
• 组织视图模型，返回给前端展示。

表现层不得包含任何业务规则，不得直接访问数据库，不得持有任何持久化对象。判断一个校验到底是表现层校验还是业务逻辑，有个很实用的标准：同一个校验规则是否会被不同入口复用。如果会，它应该下沉到业务逻辑层。

业务逻辑层负责的是：

• 业务流程编排，跨实体的状态流转。
• 业务规则校验，如权限判断、状态合法性判断、数据完整性校验。
• 事务边界控制，保证一组业务操作要么全部成功，要么全部回滚。
• 调用数据访问层接口，获取和持久化领域数据。

业务逻辑层不得感知 UI 的存在。这句话听起来简单，做起来很难。很多代码库里的 Service 方法，注释写着“返回给前端展示用”，这就说明业务逻辑层已经开始被表现层污染了。

数据访问层负责的是：

• 数据库连接管理与事务协调。
• SQL 语句的编写，或通过 ORM 完成的实体映射。
• 数据实体的 CRUD 操作。

数据访问层不得包含业务规则。这一点最容易犯的错误是，开发人员觉得在查询方法里加上“只查状态为有效的数据”是顺手为之的事，但这类隐含过滤逻辑一旦散落在数据访问层，上层很难排查数据异常。

依赖方向是铁律：表现层依赖业务逻辑层，业务逻辑层依赖数据访问层，任何一层都不允许反向依赖。为了从物理上保证这一点，我们按项目结构强制隔离：三个独立的类库项目，数据访问层不引用任何表现层和业务逻辑层的程序集——注意，是项目级别的引用配置上就杜绝，而不是靠代码审查。我用一句话给团队解释这个设计的用意：“程序集引用是宪法，依赖注入是法律，代码审查是交警。宪法首先要清晰，交警的工作量才能降下来。”

3.2 DTO 与实体：不搞模型复用至上

关于模型设计，这是我们踩过最多坑的地方。最开始团队成员倾向于直接用数据库实体类作为表现层返回值，理由是代码量少、开发效率高。但实际一跑，问题立刻就暴露了：接口返回给前端的 JSON 里出现了密码哈希字段、内部状态码、审计时间戳，前端莫名其妙拿到了它完全不需要的数据。

文档里我定了一个模型划分规范，可能看起来有点繁琐，但实际收益非常大：

• 数据实体（Entity）：对应数据表结构，专属于数据访问层。
• 业务模型（Model）：表达核心业务对象的完整状态，用于业务逻辑层内部流转。
• 视图模型（ViewModel）：针对特定 UI 场景裁剪，只包含表现层需要展示和提交的数据。

三个模型之间通过映射器转换。很多人觉得这样“多此一举”，但当你处理过一个复杂的权限系统之后，就会明白视图模型和业务模型分离的必要性。举个例子，一个用户编辑页面，需要把用户的角色列表、部门列表、直属上级等信息拼到一起，但如果你的业务模型严格对应到数据库实体，你为了组装这个页面，可能要发七八次查询。有了面向场景的视图模型，情况就完全不同了，可以明确这个视图需要哪些数据，并在业务逻辑层做一次聚合查询。

映射工作确实增加了一些样板代码，但我们用了自动化映射工具之后，体力劳动仅限于处理一些字段名不完全一致的情况。我更愿意说：手动模型赋值不是效率问题，而是维护风险问题——一旦实体字段变更而映射遗漏，错误往往在运行时才暴露。

3.3 接口粒度设计：服务该多“细”才舒服

接口粒度这个问题，在重构开始前我脑子里也没有非常精确的答案。经过几轮迭代和团队评审，我们最终形成了一套相对可靠的设计基线，在这里可以给你做参考：

服务接口按业务用例组织，而不是按实体组织。你只要用 Word 先把用例列表拉出来，一个用例对应一个接口方法，这个方法的名字就是对业务意图的描述。“下单”“取消订单”“查询订单详情”是好的方法命名，而“Save”“Update”“Delete”这类泛化命名，要在大规模的业务系统里控制得非常严格才行。

每个服务方法的参数，应该是视图模型或业务模型，而不是散落的原始参数。超过三个参数的方法，要主动考虑封装为请求对象。这不仅是代码整洁度问题，更关键的是：当业务需求发生变化，比如增加一个查询条件时，你不需要修改方法签名，只需要给请求对象加一个属性，对调用方完全兼容。

事务边界放在服务方法级别。一个服务方法就是一组业务操作的最小不可分割单元。这个约定的作用在于统一所有人的认知：无论什么操作，进入服务方法时事务开始，方法正常返回时提交，抛出异常时回滚。它不要求你了解底层事务传播机制的各种细节，却可以避免大量事务失控问题。

3.4 异常处理规范：别让异常“裸奔”

重构之前，这个系统的异常处理状况可以用“各显神通”来概括。有的地方捕获后打印日志，有的地方捕获后返回空对象，有的地方压根不捕获，让运行时直接抛给用户看到一个又长又难懂的堆栈页面。重构中我重点设计了一套分层异常处理规范，整体思路比较清晰：

数据访问层只抛出数据访问异常，例如数据库连接失败、唯一键冲突、字段超长，这些异常是底层技术细节的直接外化。

业务逻辑层抛出业务异常，业务异常必须携带明确的错误码和面向用户的可读信息。状态非法、余额不足、权限不足，这些都是业务异常，它们由开发人员在业务代码中显式创建。

表现层统一捕获异常，把业务异常转换为带错误码的响应结构，其余异常转换为通用错误，并在日志中记录完整堆栈。

判断异常该不该被捕获和转换，我分享一个自己总结的经验：如果是可控的、预期内的分支——用户操作不允许、数据状态不合法——用业务异常显式表达；如果是不可控的、预期外的故障——数据库宕机、磁盘满、第三方接口超时——则让异常向上传播到全局处理器，由基础设施统一兜底。这个区分对刚入行的同事极其重要，因为他们最容易犯的毛病是到处 catch 后把异常吞掉。

4. 重构实施与文档落地

4.1 渐进式重构：模块优先级怎么排

整体重构不是一个“小步快跑”的过程，但它的单位切换策略，我们选择的是“域驱动、逐步蚕食”。

核心思路是先挑一个业务边界清晰、影响范围可控的模块作为试点模块，完成全链路的三层架构改造，沉淀出一套团队认可的代码风格和文档模板。试点模块完成后，再按业务域分批推进，每批改造完都做回归验证，改造期间新旧代码共存，业务逻辑层提供适配接口供表现层调用。

模块优先级排序的依据有三个：

• 业务重要性：优先改造对当前业务增长最关键、变更最频繁的模块，这部分改造的收益最直观。
• 数据独立性：优先改造数据表关系简单、依赖较少的模块，降低改造初期的复杂度。
• 团队熟悉度：优先选择团队成员最熟悉的模块，减少探索成本。

我们在第一个试点模块上耗时比预期多了 30%，因为不仅仅是写代码，还要建立分层结构的代码规范、命名规范、异常处理模板、映射器和依赖注入的注册方式。但第二个模块推进时，效率明显提升，因为骨架已经搭好，开发人员需要做的只是往里面填业务逻辑。

我的核心观点是：第一个模块要慢，后面的模块才会快。不要一上来就想全量改造，那通常会在中后期出现巨大的返工成本。

4.2 接口文档与技术方案的设计方式

说到这里，我必须专门聊聊接口文档和技术方案该怎么组织。因为这次重构项目的文档，不是简单记录结果，而是为团队留下可追踪的决策上下文。

当时团队接到的要求很常见：项目周期之内要形成一套可供后续维护者理解结构、理解设计动机、理解约束条件的文档，因此整个文档体系的组织方式，不是“拼装”，而是“分层记录”：

• 第一篇是架构决策记录，用表格列出每个关键决策的背景、可选方案、决策结论与理由。表格的精华在于“理由”列要写出约束条件，比如“团队 7 人，三个月内必须上线”“现有运维体系不支持容器化部署”。这些约束条件就是后续接手的工程师判断“这条决策是否仍然适用”的唯一依据。
• 第二篇是模块改造清单与进度追踪表。清理过程中保留一份全景表，每个模块一行，记录它的改造状态、责任位置、依赖信息、当前风险与阻塞事项。
• 第三篇是接口规范与分层约定速查表，面向日常开发。
• 第四篇是排查手册，记录改造和回归过程中真实遇到过的典型问题，包括失败模式、日志关键片段、追查路径与最终解法。

团队评审后一致觉得最有价值的反而是表格型记录。不要低估表格的威力，我想表述的是：架构文档本身如果只是一篇充满架构图的论述，读者看了会困；但当它变成“决策表 + 清单 + 速查表”的组合时，它就是团队真正会反复翻阅的一本工作手册。另外，每个表格都配了一句话“边界红线”，直接指明这块域里最容易犯的错。

4.3 数据访问层重构：JPA 与查询规范

这个系统原有的数据访问方式，是极其随意的原生 SQL 拼接。重构数据访问层时，我们用了当时团队最熟悉的 ORM 框架，搭配若干补充工具做复杂查询。这个选择的价值在于平滑迁移：团队成员本来就熟悉这套技术栈，不需要引入学习成本，唯一要改变的只是比以往更规范地使用它。

数据访问层的设计有几个关键决策：

实体注解要完整定义表映射关系，字段命名显式映射，而不是依赖命名约定。这样做的好处是，数据库字段改名时，你能立刻知道哪些映射到了哪里，而不是靠猜。

复杂查询必须走查询规范模式。经过实践我发现，把查询条件封装为查询对象的方式，好处远超预期：可以很自然地复用公共查询条件，组合复杂查询时不用再写奇奇怪怪的动态 SQL；同时让查询意图变得明确——看查询对象有哪些属性，一目了然。刚开始写动态查询时，有人觉得判断条件写起来繁琐，但习惯了之后，它比字符串拼接安全得多，也没有 SQL 注入的顾虑。

所有数据访问层方法返回强类型结果集合，禁止返回动态类型。这一点约束曾经让少数成员觉得“不自由”，但当你看到跨三层的数据结构始终稳定，你就能体会到强类型的价值——编译期就能拦截一大批错误，而不是上线后借助日志去回溯。

一个让我印象非常深刻的事故是：重构期间某次联调，接口返回的数据偶尔会缺少某个字段。排查了很久，最后定位到原因是同一个实体在多个 mapper 方法里被映射成视图模型，但不同 mapper 的字段配置有差异，有的包括了该字段，有的没有包括。这个问题的根源不是某个人的粗心，而是缺少统一的映射规范。在那之后，我们立了一条规则隔离数据实体的属性集合，同时在代码评审中把“DTO 映射是否完整”作为必查项目。

4.4 依赖注入与生命周期管理

三层架构与依赖注入可以说是天生的搭档，但如果生命周期管不好，联调阶段就是灾难现场。常见的问题包括：无状态服务类被注册成单例，自己内部却持有有状态字段；DbContext 被注册成单例，造成并发请求下的数据错乱——我们实际排查过一个特别诡异的问题，两个用户同时请求数据时，查询结果偶尔会串。

当时文档里明确写了一整套生命周期照管约定，核心内容大致如下：

• 业务服务类默认作为瞬时服务注册，每次请求解析时创建新实例，因为服务类内不应持有请求范围内的状态，所以可以安全地每次新建。
• 数据库上下文按作用域注册，与 Web 请求共用生命周期，请求结束即释放资源。
• 工具类、日志提供者等只读组件注册为单例，但注册前必须确认其内部没有任何可变状态。

依赖注入还有一个特别容易踩的坑是循环依赖。三层架构下的依赖方向本身是单向的：表现层 → 业务逻辑层 → 数据访问层。但只要有人图省事，在数据访问层里去引用业务逻辑层的一个辅助方法，循环依赖就出现了。解决方式不是调整容器配置，而是从代码结构上消灭环——把共享逻辑下沉到更通用的基础组件层。

4.5 重构中的回归验证与上线策略

重构最怕的不是改代码，而是“改完了不知道坏没坏”。我们当时做回归验证的经验可以总结为“三张清单加一个入口”：

第一张清单是原有系统访谈清单。在重构开始前，对每名开发负责人和熟悉系统的骨干工程师做访谈，把系统里所有“非明面但必须存在”的隐性行为列出来。很多隐性行为非常隐蔽，比如“某个整数字段为 0 时，前端显示‘未设置’，后端也需要在返回的数据里特别标记”。这类规则通常不在代码注释里，只存在于老开发人员的脑海里。

第二张清单是接口签名比对清单。重构期间每个接口留下改造前后签名对比记录，字段类型、默认值、边界条件都要逐项目比对。我特意在文档里强调了这一点：哪怕只是少返回一个 null 字段，对前端契约来说，就是一次破坏性变更。

第三张清单是自动化验证用例的完备性检查。启动重构前，我们为关键接口补齐了自动化测试用例，作为重构安全网。重构后的每一轮迭代，都要先跑安全网，确保基础行为没有发生漂移。

上线策略上我们选的是“新旧并行，按流量灰度”。通过配置开关控制新老代码路径，先切 1% 的流量观察日志和监控，稳定后逐步到 10%、50%、100%。这个策略的关键是，数据访问层做了一组兼容方法：旧写接口写库后，新读接口必须能立刻读到一致的数据，因此在数据库层面没有做任何破坏性变更。新表、新索引通过附加的方式引入，切换完成后才清理旧代码路径与旧表结构。

5. 常见问题与排查技巧实录

5.1 前端页面出现“幽灵字段”

重构上线后，前端同事反馈，某个详情页的数据在偶发情况下会多出几个不知道含义的字段。排查发现，这些字段来自数据库实体的属性——原来的写法里，实体直接被序列化后返回前端，字段多了也就多了。

这个问题的根因是“表现层和实体强耦合”的遗留习惯没有彻底改掉。虽然规范要求返回视图模型，但个别接口为了方便，直接把数据实体的属性拷贝到了返回对象。解决方式，除了规范约束，还有一条更加硬性的防护办法：JSON 序列化时统一配置忽略空值，并且对返回类型做一次性快照比对，差异项一律视为缺陷。经过这次，团队对“实体不等于视图模型”的理解彻底到位了。

5.2 接口事务频繁超时

重构后测试环境频繁出现接口超时，压测一上来，数据库连接池直接被打满。最初怀疑重构代码有性能问题，后来定位到原因：一个批量处理服务方法内部，循环里逐条调用数据访问层保存方法，每条保存都是一个独立事务，一条外层事务套了 500 次独立提交，数据库要处理 500 次日志刷盘。

修复方法很简单：把逐条提交改成批量提交，同时对数据访问层的批量方法做整体事务控制。这个事故带来的教训是：事务边界放在服务方法级这个约定本身没问题，但服务方法内部的实现必须对自己发起的每个数据写操作负责，避免不必要的小事务，在设计服务接口时就要考虑批量语义。

5.3 查询数据不一致

有段时间，用户反馈报表模块导出的数据和页面上显示的统计数字对不上。经过排查，发现是因为同一个统计口径，在两个服务中分别实现了一次，而其中一个实现把“未支付订单是否计入”这个条件写错了。这正是“业务逻辑分散在多个地方，你无法保证它们始终一致”的真实写照。

我们的修复措施和长期防御机制是：所有统计口径在逻辑层里统一为公共方法，用自动化测试把口径锁死，任何一处修改都必须跑测试。这件事也让我明白，架构重构之后必须做“逻辑收敛审计”，最怕的就是重构时一批逻辑沉到了服务层，但它们还是分散的多个实现。

5.4 重构后单元测试跑不动

重构后，开发人员比较容易遇到测试代码无法运行的问题，最常见的原因是服务类依赖了数据库相关的实现，接口没有注入独立测试替身。我们处理的方式并不复杂：数据访问层接口实现中，凡是涉及外部资源的，全部提取为可替换的接口，并配置了内存化替身。

但我要提醒你的是，测试基础设施的建设最好放在重构试点阶段同步完成。如果重构代码已经铺开，再回头补测试设施，推广阻力会非常大。因为到那个时候，多数开发人员已经在用旧方式写测试了。

6. 文档沉淀与团队协作中的实用经验

文档最大的作用，是让团队在“遇到问题怎么处理”上取得一致性。我们的接口文档最终形成了几类高度可复用的模板和约定，直接影响着日常开发的效率与质量。

6.1 接口签名自查表

写任何一个对外提供的服务方法，至少要在代码评审时自查以下内容：方法名是否为业务动作命名；参数对象是否超过三个属性；返回字段是否有未赋值的风险；异常是否都有对应的错误码类别；事务边界是否清晰；日志是否在关键分支打了必要的记录。我把这些做成一个十几项的检查列表，放在接口模板的备注里。评审的时候过一遍，能挡住相当大一部分返工。

6.2 模块改造交接单

每个模块改造完成，在交接给维护者时，必须附带一份简短交接单，写清楚改造前的主要怪异行为、改造后确认过的行为差异、遗留的技术债清单、未来可能的改造方向。这些内容看着琐碎，但当你四个月后再回头维护这个模块时，它们是无价的信息。

6.3 团队从“个人英雄”到“结构化协作”

这次重构给我最大的组织层面感受是，它倒推着团队改掉了“各写各的”习惯。因为三层结构下，一个人很难独立完成一个全栈功能，必须依赖相邻层提供的接口。一开始有人觉得流程变重了，但运行一两个迭代后，大家意识到：接口稳定之后，每层内部的修改都不再影响其他人，调试和信息同步的成本大幅下降。

文档里我还专门开辟了一节，叫“写给后来维护者的六句话”。内容不多，但每一条都是血泪教训换来的。这里可以提前透露几条：

• 不要为了省一次调用，跳过业务逻辑层直接操作数据访问接口。
• 不要为了改一个字段，顺手改掉实体映射关系而不更新视图模型。
• 新出现一个业务规则时，问自己一句：“它应该出现在哪一层？”如果回答不出来，大概率是需求还没想清楚。
• 如果你的改动跨越了三层，一定要重新审视接口契约是否正确，而不是图省事在某一层里堆逻辑。

7. 重构之外的几点切身体会

项目结束之后，回过头看这份三层架构重构项目文档，最有价值的不是那些架构图，也不是那些代码规范，而是它如实记录了决策的约束条件和踩坑过程。任何一个项目文档，如果想对后来者有价值，它必须回答“当时为什么这么做”和“当时为什么不那么做”。技术选型不是永恒的，需求会变，团队能力会变，技术栈会变，但决策逻辑是稳定的参考系。

我个人在实际操作中体会到，重构类项目比新项目难，难在它必须在“继续跑着的系统”上做手术。手术能不能成功，不取决于主刀医生的技术多精湛，而取决于术前准备——对现状的理解程度、团队共识的深度、安全网的完整度——以及术后护理——回归验证、监控、文档交接。三层架构看似朴素，但它提供了一个足够清晰的骨架，让整个手术过程有章可循。

如果你也正筹备老项目治理，最后再分享一条小技巧：重构开始前，花两周时间把系统的关键接口行为用自动化测试录制下来，哪怕部分测试用例写得很笨拙。这一组测试，就是重构过程中心里踏实感的来源。没有安全网的第一次重构，基本等同于蒙眼走钢丝，而你不需要用这种极端方式证明自己的勇敢。