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. 重构之外的几点切身体会项目结束之后回过头看这份三层架构重构项目文档最有价值的不是那些架构图也不是那些代码规范而是它如实记录了决策的约束条件和踩坑过程。任何一个项目文档如果想对后来者有价值它必须回答“当时为什么这么做”和“当时为什么不那么做”。技术选型不是永恒的需求会变团队能力会变技术栈会变但决策逻辑是稳定的参考系。我个人在实际操作中体会到重构类项目比新项目难难在它必须在“继续跑着的系统”上做手术。手术能不能成功不取决于主刀医生的技术多精湛而取决于术前准备——对现状的理解程度、团队共识的深度、安全网的完整度——以及术后护理——回归验证、监控、文档交接。三层架构看似朴素但它提供了一个足够清晰的骨架让整个手术过程有章可循。如果你也正筹备老项目治理最后再分享一条小技巧重构开始前花两周时间把系统的关键接口行为用自动化测试录制下来哪怕部分测试用例写得很笨拙。这一组测试就是重构过程中心里踏实感的来源。没有安全网的第一次重构基本等同于蒙眼走钢丝而你不需要用这种极端方式证明自己的勇敢。