1. 工程结构设计到底在设计什么我见过太多能跑的项目了代码能跑、接口能用、页面能点看起来一切正常。但只要你有机会把代码拉下来打开看一眼那种窒息感会瞬间涌上来——几百个类堆在几个包里Service里躺着几千行的业务方法一个Controller同时干着参数校验、权限判断、数据组装、日志记录的活DTO和Entity在层与层之间毫无原则地互相传递。我管这叫能跑但活不久的项目。这种项目往往不是死在业务复杂度上而是死于工程结构失控。第一年大家还能靠记忆力撑着第二年主力离职之后就没人说得清某个接口到底在哪几层做了哪些事第三年一个看似人畜无害的需求改动牵一发动全身测试要回归两天上线战战兢兢。所以当有人问我后端工程结构怎么设计的时候我给的答案从来不是某张架构图、某个目录模板而是先问一个问题你这套代码是只想让它跑起来还是想让它活过三年1.1 拿到一个能跑的项目先看哪里最痛判断一个后端工程质量不需要看文档不需要开代码评审会你只需要做三件事。第一随便找一个业务需求比如查询订单详情然后从Controller入口开始往下跟看这条调用链要穿越多少个类、跨多少个包、经过几次类型转换。如果从Controller到数据库查询这段路走下来要经过六七个类每个类之间还互相new来new去这个项目的基本盘就有点危险了。第二统计一下最大的那个Service类有多少行。超过两千行不是问题超过五千行是常态一万行以上就是灾难。行数本身不杀人杀人的是行数背后隐藏的上帝类——所有业务逻辑都堆在一起没有层次、没有边界、没有任何约束。第三看一眼现有的包结构。如果整个项目只有controller、service、mapper、entity四个包而且包下面平铺了所有业务模块的类我可以负责任地说这个项目在半年到一年之间就会进入维护地狱。类会越来越多命名会越来越随意新来的同学根本不知道该往哪个包里放代码最后的结果就是哪里有缝往哪塞。这三个检查点基本能反映一个后端工程的结构健康状况。你觉得扎心说明你见过。1.2 好的工程结构三个目标就够了关于工程结构很多文章会讲一堆高深的概念DDD、整洁架构、六边形架构、CQRS……这些理论本身没错但对多数中小团队来说落地时最容易出现的状况是理论学了一堆代码一写还是老样子。我不反对学架构理论但我觉得工程结构设计的第一性原理其实很朴素。一套结构只要能帮你稳定达成三个目标它就是合格的。目标一边界清晰。任何一个类放在哪个包、哪一层、承担什么职责是有明确规则的。别人看到包名就能大概猜到里面是什么东西不需要打开类才能反推结构。目标二依赖可控。整条调用链的方向是单向的、可追踪的。上层可以依赖下层下层不能反向依赖上层同层之间的横向依赖有明确约束不允许随便乱调。目标三变更成本可预估。加一个新接口、改一个业务规则、换一个数据源维护者能明确知道改动影响哪些文件不需要全局搜索才能摸清影响面。这三个目标听起来简单但能同时做到的项目其实不多。原因也很现实结构是反人性的人类天然倾向于怎么方便怎么来而工程结构恰恰要求你在写每一行代码的时候都想着这个类放哪里更合适。这种心智负担需要靠结构设计和配套规范来分担不能全指望个人自觉。1.3 三种主流工程结构形态后端工程的代码组织方式归纳下来大概有三种主流形态。形态一经典分层结构。也是Spring Boot最普及的形态——Controller暴露接口Service承载业务Mapper操作数据库。优点是人人都熟新同学上手快缺点是如果只有这四层没有别的约束项目一大就必然走向混乱。形态二按业务模块分包。不按技术层次分而是按业务域分比如user、order、product三大包每个包内部再各自分层。优点是高内聚一个业务相关的类都在附近缺点是跨模块调用如果管理不好很容易产生循环依赖。形态三多Module的模块化结构。把工程拆成多个Maven或Gradle模块比如common、framework、system、business几个Module各自独立编译模块之间通过接口或API交互。优点是边界最硬、编译期就能约束依赖方向缺点是前期搭建成本高对团队的分层能力有要求。没有哪个形态是绝对正确的。关键在于跟团队规模和业务复杂度匹配。三五个人做内部系统硬套多Module纯粹是给自己找麻烦二十个人做大项目还在平房式的单包里堆类迟早要还债。1.4 为什么Spring Boot默认的单包结构撑不过一年Spring Boot的初始化器给你生成的工程默认是这样一个结构一个主类在最外层下面自动生成controller、service、mapper、entity、config等几个包。说实话这个结构作为骨架是合格的但作为项目的最终形态它撑不过一年。原因不复杂。Spring Boot给的默认包结构是基于技术分层思想的——所有Controller放一起所有Service放一起。这套结构在小项目里没问题类不多你翻一下就能找到。但项目一旦膨胀问题就来了订单相关的Controller、用户相关的Controller、支付相关的Controller全部挤在controller包里在IDE的文件列表里都分不清谁是谁。这不是包结构有问题是技术分层平铺业务的组合撑不住业务扩张。所以很多成熟的团队会演进到业务分包或者在业务模块内再嵌套分层本质上是在技术分层的骨架上加了业务维度。这个演进方向后文我会详细展开。2. 后端分层设计Controller、Service、Mapper的边界到底在哪分层这件事看起来是后端开发的基本常识但真正能把边界划清楚的人不多。每次代码评审我都能看到大量违反分层原则的代码在堂而皇之地往仓库里提交。最常见的几个典型问题Controller里写事务、Service里拼HTML、Mapper里写复杂到天际的SQL、Service和Service之间随意互相new、DTO直接传给了Mapper层然后Mapper返回Entity再被Controller直接序列化给前端……这些问题单独拎出来都能用懒来解释但本质上是层与层之间的职责边界没有在团队里达成共识。2.1 Controller层只做协议适配不做业务Controller的核心职责是HTTP协议的适配层它的工作只包含三件接收请求参数并完成基础校验、调用Service层方法、把Service的返回值转换成可序列化的响应体。不要把业务规则写进Controller。最典型的反面教材是在一个Controller方法里手写分页计算或者在Controller里判断用户角色来决定走哪条业务分支。这些都属于业务逻辑放在Controller里会让业务规则散落在接口层后续想复用就找不到入口想改规则就得在HTTP协议层里翻代码。Controller层还有一个隐性的职责——参数对象的生命周期管理。Controller接收的Request对象在方法结束后就应该被丢弃不应该把它传给Service层去做业务处理。正确的做法是在Controller里完成从Request参数到业务参数的转换Service层只接收它定义的业务入参不感知HTTP协议的任何细节。这就是Controller做协议适配的含义。2.2 Service层业务逻辑的唯一合法位置Service层是整个后端工程的核心。判断一个项目结构是否健康最直接的方式就是看业务逻辑的分布如果业务规则全部在Service里结构是健康的如果业务逻辑散落在Controller、Mapper注解甚至前端JS里那结构肯定是有问题的。Service层设计的几个关键点我逐个说。第一个关键点Service是事务的边界。如果你的项目用了Spring的Transactional它的正确位置一定是在Service层的公开方法上。一个Service方法就是一个完整的事务单元方法内部要么全部成功要么全部回滚。不要把事务注解打在Controller上也不要在Mapper上做事务控制。把事务放在Service层意味着事务的粗细粒度由业务方法决定这是最合理的控制粒度。第二个关键点一个Service只服务一个业务域。尽量避免把两个不相关的业务逻辑塞进同一个Service类。订单Service只管订单用户Service只管用户如果订单创建过程中需要扣减库存订单Service应该调用库存Service的接口而不是自己直接去写库存表的Mapper操作。这种跨域调用要保持“单向依赖”不要让库存Service反向依赖订单Service否则模块间就成了蜘蛛网。第三个关键点Service之间的调用用接口不要直接new。用Spring的依赖注入把其他Service作为依赖注入到当前Service中。新手最容易犯的错是Service里new一个其他Service来用这种写法会破坏依赖管理让单元测试没法做Mock也让Spring的代理机制失效。2.3 Mapper/DAO层数据访问的最底层Mapper层是数据访问的最底层它的职责非常单纯负责SQL的执行和结果集的映射。业务条件判断、数据组装、字段计算这些都不该在Mapper里做的。我见过很多把业务逻辑写进Mapper XML的做法比如在一个查询语句里堆了十几个if判断根据不同的参数组合生成不同的查询条件。这种做法在短期内看着很方便能把一个复杂查询压缩在一个方法里但长期维护是噩梦——你根本不知道这个方法被多少个Service调用过每个调用方传入了哪些参数任何一个分支逻辑的改动都可能影响全局。Mapper的正确定位是“数据访问原子操作”的提供者。一个Mapper方法对应一个明确、单一的数据访问需求比如根据ID查询、按条件分页、更新某几个字段。复杂的业务查询可以通过多个Mapper方法的组合来完成而不是强行把业务逻辑翻译成一条大SQL。Mapper层还有一个很容易被忽略的点事务内的连接管理。Spring的Transactional作用于Service层时同一线程内的多次Mapper调用会共享同一个数据库连接这是Spring利用ThreadLocal实现的事务传播机制。所以你在Mapper层不要尝试自己获取连接或关闭连接这些都交给Spring统一管理。2.4 依赖方向与分层铁律分层结构一旦定下来依赖方向就是铁律。在标准的三层架构中依赖方向是Controller → Service → Mapper。Controller可以依赖ServiceService可以依赖Mapper反过来都不行。Controller不应该直接依赖MapperService不应该被Mapper反向调用。这条铁律有什么意义它保证代码的调用链永远是单向的、可追踪的。你可以顺着Controller开始往下追从接口到业务到数据不会遇到环路。一旦依赖方向失控比如Mapper里注入了某个Service来拿配置数据那整个结构就乱套了——看似只是一个小小的反向依赖实际意味着你在数据访问层耦合了业务逻辑后续要替换数据源或者做缓存改造时会牵出一堆业务依赖。在检查依赖方向的时候我建议团队里至少要有一两个代码洁癖患者。他们存在的意义不是让代码“好看”而是在依赖方向失控的早期把它掐灭在萌芽状态。2.5 DTO、VO、BO、Entity别让它们打架分层依赖方向背后还藏着一个几乎所有后端团队都要面对的问题数据模型怎么分层。这里要区分清楚四类对象的职责。**Entity实体对象**映射数据库表结构字段与表字段一一对应只存在于Mapper层与数据库之间。**DTO数据传输对象**在服务间或服务与外部接口间传输比如RPC调用的请求和响应就是DTO。**VO视图对象**是面向接口输出层的直接决定前端能拿到什么数据字段命名、类型都应该贴合前端需求。**BO业务对象**承载业务处理过程中的临时数据状态用于Service内部逻辑。很多项目做不好分层就是因为这一块混乱。最常见的反模式是Entity直接传给Controller然后序列化返回给前端。短期看很省事长期全是坑——数据库字段暴露给前端了不想让前端看到的内部字段泄漏了前端想要的字段名和数据库字段对不上你只能在前端做各种奇怪的兼容。正确的做法是Entity只在Mapper与Service之间传递Service返回BO或DTO给ControllerController再转换成VO输出。每一层之间的对象转换可以手工写也可以用MapStruct等工具来减少样板代码。我知道有人会吐槽说这太繁琐了项目里字段那么多转来转去很麻烦。但请记住能活三年这个目标——你一次转换的繁琐换来的是后续所有维护者对数据边界和层次边界的清晰认知这笔账怎么算都值。3. 单体内的包结构与模块划分层与层之间怎么协作搞清楚了下一步要解决的是包怎么组织、模块怎么划分。这部分直接关系到日常开发中新代码往哪里放这个高频问题。3.1 技术分层包 vs 业务分包怎么选在实战中包结构设计最纠结的一个选择是按技术分层建包还是按业务建包。纯技术分层包就是Spring Boot默认生成的那种controller包、service包、mapper包、entity包各管一摊。优点是结构简单、理解成本低缺点是业务跨层追踪时要在多个包之间跳来跳去业务本身的内聚性被割裂了。纯业务分包就是按业务域建包user包、order包、product包每个包内部再自己分controller、service、mapper。优点是高内聚——跟用户相关的所有代码都在user包下面缺点是跨业务模块交互时职责归属容易模糊比如订单要查用户信息访问的是user包暴露的service接口但user包里是允许别人随便注入自己的service还是通过一个专门的facade接口暴露很多团队定义不清楚最后会退化成包之间直接互相new。从我经历过的项目来看组合式结构是最稳的选择按业务模块建立顶层包每个业务模块内部再按技术层次分包。兼顾业务内聚与技术分层两个维度也不复杂团队容易上手。3.2 推荐的包结构模板下面是我在项目里落地过多次、被验证能活三年的单体应用包结构模板供参考。com.xxx.xxx ├── common/ # 通用模块工具类、通用常量、通用异常 │ ├── constant/ │ ├── enums/ │ ├── exception/ │ └── utils/ ├── config/ # 全局配置Spring配置、安全配置、缓存配置 ├── framework/ # 框架封装若依风格的通用基类、切面、拦截器 │ ├── aspect/ │ ├── interceptor/ │ └── base/ ├── module/ # 业务模块按业务域划分 │ ├── user/ │ │ ├── controller/ │ │ ├── service/ │ │ ├── mapper/ │ │ ├── entity/ │ │ ├── dto/ │ │ └── vo/ │ ├── order/ │ │ ├── controller/ │ │ ├── service/ │ │ ├── mapper/ │ │ ├── entity/ │ │ ├── dto/ │ │ └── vo/ │ └── ...其他业务模块 └── Application.java这个结构的好处在于业务模块自包含跨模块调用只能访问对方暴露的Service接口各模块内部的分层逻辑与技术分层一致新来的同学看一眼例子就能很快知道代码该放哪里。这是一种把业务分包技术分层融合的结构在很多中大型项目里被验证过是实用可落地的。3.3 什么时候该把单模块拆成多Module单模块工程能支撑的业务规模是有上限的。当项目膨胀到一定程度你可能需要把工程拆成多Module的Maven工程。什么程度是需要拆的信号我列几个判断依据团队规模超过15人以上大家都在同一个Application里开发频繁的代码冲突开始拖慢开发效率业务模块之间的边界已经稳定比如系统管理模块与核心业务模块几乎没有交叉改动出现了“只想给某个业务模块加部署实例但不希望其他模块一起发布”的诉求公共类的变更会触发所有业务模块的联调即使改动本身只影响某一个模块。拆Module的核心价值不是把代码分散开而是用Maven或Gradle的依赖管理把模块边界变成编译期约束。哪个模块能依赖哪个模块在pom.xml里定义好破坏了边界直接编译不过。这是最硬的结构保障靠代码评审和个人自觉是无法替代的。常见的模块划分方式包括common纯工具不依赖任何业务、framework框架封装依赖common、system系统管理相关业务、business核心业务模块等。模块之间的依赖关系必须是单向的、无环的出现循环依赖的Module结构时一定是设计没有理清。3.4 参考若依框架的模块设计好在哪里提到后端工程结构很多人会想到若依框架。抛开它的具体业务功能不谈单从工程结构设计的角度若依的模块划分确实有一套值得参考的逻辑。若依把工程拆成了几个核心模块ruoyi-common放通用工具、ruoyi-framework放框架核心、ruoyi-system放系统服务、ruoyi-admin作为Web入口、ruoyi-ui是前端。这个划分把通用能力和业务功能做了隔离公共逻辑下沉到底层模块业务模块依赖底层模块但不反向依赖。这样后续如果要做微服务拆分common和framework直接下沉到独立的基础库业务模块单独出来成服务过渡成本低很多。它对单体或SRM型项目的借鉴意义在于通用能力和业务能力分层的理念是普遍适用的。哪怕你就一个单体模块也要在包结构上把common、framework、business三块分开。这能避免一个最常见的坑业务代码里到处是工具方法改一个公共工具类的签名全项目跟着编译错误。4. 配套规范撑起工程结构的隐形骨架工程结构不只是目录长什么样更是代码怎么长。很多项目的目录结构是挺好的但代码写的随心所欲包名大小写混乱、类名不能表达职责、方法动不动写两三百行、异常信息一串看不懂的英文……这些看起来都是细枝末节但它们共同决定了一个工程能否长期可维护。4.1 命名规范包、类、方法的统一约定命名这件事人人都会但把命名当作工程规范来严格执行的团队不多。包名建议全小写单词之间不用分隔符比如userinfo而不是userInfo、user_info。这是Java的长期约定别为了标新立异去打破它。类名的命名要确保“见名知责”。Controller以Controller结尾Service以Service结尾ServiceImpl以ServiceImpl结尾Mapper以Mapper结尾Entity不带后缀DTO以DTO结尾VO以VO结尾。这些约定看起来很简单但在快速迭代的项目里如果没有强制约束很容易出现UserService、UserBiz、UserHandler、UserManager这种混乱的命名新人根本搞不清哪个才是真正的Service入口。方法命名同样要统一。查询以get或query开头、新增用create或add、修改用update或modify、删除用delete或remove。一套统一的方法命名会让代码的阅读体验大幅提升我在做代码评审时看到符合约定命名的方法基本可以跳过不看看到奇奇怪怪的命名就得多花几分钟去理解它的意图。4.2 接口安全规范别让一个漏洞毁掉整个结构结构设计得再漂亮如果安全层面有漏洞整个系统也活不久。这里说的活不久不只是指被攻击者攻破还包括因为安全问题导致的大量紧急修复、临时补丁这些补丁往往会破坏原有的工程结构。后端接口安全有一些底线规范是必须坚持的。输入校验不能只靠前端。请求参数在后端必须重新校验。长度、格式、枚举值范围、必填项后端都要校验一遍。前端校验只是用户体验后端校验才是安全边界。上传功能要严格做类型校验。上传文件不能只校验扩展名因为扩展名可以被轻易伪造。要校验文件的MIME类型、文件头魔数、文件大小上传目录建议禁用脚本执行权限。这一条在Apache、Nginx等服务器上都需要单独配置很多团队都因为上传校验不严格吃过亏。SQL注入的防线不能依赖外部组件。用MyBatis的#{}参数占位不要用${}直接拼接。如果业务上实在需要动态排序字段建议用白名单而不是直接把前端传的字段名拼进SQL。敏感数据加密存储。用户密码必须用BCrypt等不可逆算法加密存储不能是MD5加盐就了事。前端展示的数据要脱敏手机号、身份证号只能显示部分字段。防重放与越权。后端接口要校验用户的权限范围不只是是否登录还要校验这个用户是否有权限操作这条数据。常见的越权漏洞就是只校验了登录态没有校验数据归属。4.3 代码审查与架构守护怎么让规范真正落下去规范写得再好没有闭环的落地机制就是一张废纸。代码审查和架构守护是让结构规范真正成为团队习惯的两个关键手段。代码审查的制度设计有几个注意点。一是别让审查变成走过场要让审查的人真的去读代码、理解改动而不是光看diff有没有冲突。二是审查的重点要放在结构正确性上——这个类放在了正确的包吗Service有没有绕过Mapper直接操作数据源DTO被Controller以外的地方使用了吗这些问题比变量名拼写对不对重要得多。架构守护方面可以考虑引入自动化工具。我用过ArchUnit它能用JUnit的方式编写架构规则测试比如controller包下的类不得直接依赖mapper包下的类、所有Service实现必须放在service.impl子包下、只有DTO可以被其他模块引用等等。把这些规则写进单元测试在CI构建时运行一旦有人破坏了架构规则构建直接失败。这是把人工审查和自动化检查结合起来的最优解。4.4 用ArchUnit守住架构边界简单演示一下ArchUnit的用法。假设你定了这么几条规则controller包不直接访问mapper包service实现类的命名必须以ServiceImpl结尾entity包不得依赖service包反向依赖禁止在测试目录下建一个ArchUnitTest类写类似这样的检查RunWith(ArchUnitRunner.class) AnalyzeClasses(packages com.xxx.xxx) public class ArchitectureTest { Test public void controller_should_not_depend_on_mapper() { noClasses() .that().resideInAPackage(..controller..) .should().dependOnClassesThat() .resideInAPackage(..mapper..) .check(new ClassFileImporter().importPackages(com.xxx.xxx)); } Test public void service_impl_should_be_named_correctly() { classes() .that().resideInAPackage(..service.impl..) .should().haveSimpleNameEndingWith(ServiceImpl) .check(new ClassFileImporter().importPackages(com.xxx.xxx)); } }ArchUnit的核心价值在于把架构规范变成了可运行的代码团队可以定期执行也可以放到CI里。它不能替代代码评审但它能把结构层的问题在早期就暴露出来省掉大量人工review的时间。5. 配套设施让工程在线上真正活下来项目结构搭好之后还有一些非业务的配套设施决定一个工程能不能健康地活在线上。这些设施不是某个具体业务功能但缺了它们整个工程就是裸奔。5.1 统一响应体与全局异常处理前端对接后端接口最怕的就是每个接口的返回格式都不一样。有的接口直接返回业务数据有的接口返回一个包装对象出错时有的抛异常、有的返回null、有的返回一个业务错误码。这种混乱会让前后端联调效率极低也会让前端代码里塞满各种防御式判断。所以后端工程从第一天就应该约定一个统一响应体。常见的做法是用一个Result 类型统一包装接口返回值包含code状态码、message提示信息、data业务数据三个字段。正常返回时code为成功值业务异常时code为对应的错误码message给前端展示友好的错误信息。配合统一响应体的是全局异常处理。用Spring的RestControllerAdvice配合ExceptionHandler可以统一捕获Controller层抛出的异常把它们转换成标准响应体输出。这样业务代码里不需要到处写try-catch只需要在需要的地方抛出业务异常即可异常处理逻辑收敛到一处维护成本大幅降低。5.2 配置管理环境的切换不该改代码一个工程在它的生命周期里至少要经历本地开发、测试、预生产、生产多个环境。不同环境的数据库地址、Redis连接、第三方服务的密钥都可能不同。如果这些配置是写死在代码里的部署时就要改代码重新编译这简直是灾难。正确做法是把配置外置。Spring Boot的application.yml天然支持多环境配置区分通过application-{profile}.yml来分割不同环境的配置再通过启动参数spring.profiles.active指定当前激活的环境。如果项目在容器或者K8s里跑可以考虑用环境变量或者配置中心如Nacos、Apollo来管理配置实现配置的实时动态更新避免修改配置还要重启服务的尴尬。配置管理的另一个重点是敏感信息的保护。数据库密码、第三方密钥不能明文存在配置文件里。常见的做法是使用环境变量注入或专门的密钥管理服务。很多生产事故和数据泄露事件根源都是配置文件被泄露或者密钥写死在代码仓库里。5.3 日志规范与链路追踪排查问题的底牌线上出了问题第一手排查工具不是Debugger是日志。但很多项目的日志是没有规范的——日志散落在各种类里格式不统一没有日志级别区分出了问题想捞日志要么捞不到、要么捞出来是一堆无用的信息。日志规范要解决几个问题。日志格式统一时间、线程名、级别、类名、消息内容每一行日志都有统一格式方便收集和检索。日志级别规范error记录系统和业务异常warn记录不直接影响功能但需要注意的情况info记录关键业务流程的关键状态debug记录方法级别的细节。业务关键路径要有日志比如订单创建、支付回调、用户登录这些核心动作必须在info级别有明确的日志输出这样才能在问题出现时快速定位事情做到哪一步了。链路追踪是更进一步的保障。在微服务或者分布式场景下一个请求会经过多个应用排查问题时要能做到根据一个请求ID串联起整条调用链。当前端报一个错误时如果你能拿到一个traceId然后在一堆日志里按traceId搜一遍整个链路的调用情况就一目了然。即使是单体应用也可以在入口处生成一个requestId放进MDC里在日志中打印出来排查问题同样受益。5.4 API版本管理与兼容策略后端接口一旦被前端、APP、第三方系统使用就变成了一个“有契约”的接口。如果哪天你改了某个接口的字段名、调整了参数结构、升级了响应格式下流调用方轻则报错重则核心功能瘫痪。API版本管理就是解决这类问题的关键手段。常见的版本管理方式有几种URL路径带版本号/api/v1/order、请求头带版本号、参数带版本号。业界最常用也最容易被接受的是URL路径带版本号的方式直观、可读性好也方便在网关层做路由分发。版本管理要配套一个策略不轻易删旧版本的接口。旧接口下线需要给调用方留一个缓冲周期先标记为deprecated再逐步切流量到新版本最后实在没有调用量了再下线。这个过程需要一定的流程管理依靠人来自觉不现实最好在API文档平台或者接口管理工具上做标记和统计。6. 从能跑到能活三年实践清单与常见问题前面聊了这么多原理和方法这一节我来点实际的——如果你现在接手一个结构混乱的工程或者正在从零搭建一个新工程具体该怎么操作。6.1 接手中型项目先做这三件事第一件事先画依赖图再动手重构。花一天时间把现有的包结构梳理清楚按业务域和依赖关系画出一个粗略的依赖图。标出哪些模块是高内聚的、哪些是严重耦合的、哪些是循环依赖的重灾区。这个图是你后续所有重构决策的依据画清楚再动手不然重构就是拆东墙补西墙。第二件事先立规矩再改代码。不要一上来就搬代码要先定好目标结构——用前文推荐的包结构模板确定包命名、类命名、依赖方向、DTO/Entity边界这些规范把它写进团队的开发规范文档里。规矩立好了后续的代码迁移才有依据否则改到一半发现当初定的结构有问题又得推倒重来。第三件事从边缘模块开始逐步迁移。最有价值也最稳妥的方式是选一个跟其他模块耦合较小的业务域比如系统管理或者操作日志模块先按新结构完整迁移一遍跑通了流程、验证了规范再逐步推广到其他模块。千万不要想着一次性把整个项目的结构重构完那是一个高风险、长周期、几乎必然失败的计划。6.2 常见问题速查表遇到直接翻我把这些年做后端工程结构落地时最容易踩的坑整理成一张速查表遇到问题可以对着看。问题现象根本原因解决方案一个Service类上千行甚至上万行业务逻辑没有按业务域拆分按业务域拆Service跨域调用用接口前端报错但后端没有日志缺少全局异常处理或日志级别设置不当增加RestControllerAdvice统一异常处理关键路径加info日志Controller直接操作Mapper分层边界不清晰强制Controller只能调用Service层改了公共工具类全项目编译错误公共类承载了过多被依赖的随意方法缺乏下沉与收敛收敛公共类按模块下沉减少跨模块依赖一个查询方法传十几个参数Mapper方法职责不单一拆分Mapper方法职责单一化必要时引入查询DTO对象环境之间配置混乱配置没有外置环境切换靠改代码引入多profile配置或配置中心事务不生效事务注解放在私有方法或同类内部调用上事务注解放在Service层public方法避免同类内部自调用跨域请求失败前后端分离场景下未配置跨域策略统一配置CorsFilter或使用网关跨域这里单独说一个热搜词场景——微信小程序真机调试请求无法到达后端。这类问题多数不是工程结构本身的问题而是网络环境的问题小程序真机调试时的域名必须是HTTPS且已在后台配置合法域名本地开发时又要打开“不校验合法域名”的选项。这些点跟后端结构没关系但排查时需要你懂不然会怀疑是自己的代码写错了。6.3 三年后回头看这些决策最重要项目能活三年的关键往往不是你的技术有多炫、不是你的框架选了多新而是当初在最基础的结构决策上有没有想过:业务边界是不是划清楚了。哪些属于用户域、哪些属于订单域、哪些属于支付域这个边界一旦定了后续大部分代码放哪、模块怎么复用都是水到渠成的事。依赖方向是不是定死了。Controller只能调ServiceService只调自己的依赖Entity不往上层传DTO不往下层漏。这些铁律在项目初期没什么感觉撑过一年之后你就会发现它们是项目不乱套的底线。公共逻辑是不是真正下沉了。工具方法、基类、通用组件这些有没有沉淀到common或framework模块而不是散落在各个业务类里。没有下沉的公共逻辑是项目膨胀后最难治理的地方可以说是“陈年债务”的源头。工程结构是给人看的更是给时间看的。它的价值不是让你今天开发起来多顺手而是让三年后的同事——不管是你还是接手你代码的人——看到这台“代码机器”的时候还愿意维护它。从这个角度看后端工程结构设计这个题目本质上是个长期主义的技术活。