我见过太多SpringBoot项目启动类后面跟着五个包controller、service、dao、entity、config。三个月后service包下膨胀出几百个类命名从UserService到UserServiceImpl再到UserBizService没人说得清某个功能到底在哪个类里。改一个需求要翻三四个包加一个字段要动五个文件。这种结构的核心问题不是“分不够细”而是包结构完全是技术分层的复读从未表达过业务边界。清晰的SpringBoot项目结构第一原则是包结构映射业务域而不是映射技术角色。技术分层是运行时依赖的约定目录是用来让人快速理解“这个系统管哪些事”的。当你打开项目的顶级包看到的应当是“订单”“商品”“用户”这样的业务域而不是“controller”“service”“dao”这样的技术层。业务域之间天然隔离改动彼此独立而技术层之间则存在强耦合任何需求都会穿透三层导致改动无法局部化。有人会问那controller、service这些放哪里答案是放在业务域内部作为二级包。比如com.company.order下面可以有controller、service、repository、domain但“tech.layer”作为顶级目录只会让代码按照“我是什么”分类而不是按照“我属于哪块业务”分类。按业务域组织后你要改订单相关功能直接进入order域无需在全局几十个技术包里做“语境切换”。这才是“清晰”的第一含义——减少导航成本。第二个必须想清楚的问题是项目结构到底要为谁服务为一个刚启动的Demo服务单模块加技术分层没问题但一旦业务复杂到十几个人协作结构就必须能隔离团队、隔离发布、隔离失败。很多人上来就拆多模块结果拆出五个模块互相同引最后干脆用一个公共common包放所有实体——这比单模块更糟。拆分的核心依据是依赖方向而不是“看着整齐”。一个模块如果被所有其他模块依赖那它就是变相的全局垃圾场。SpringBoot项目里最典型的反面教材就是common或util模块里面塞满DateUtils、StringUtils、BaseEntity、Result最后没人敢删因为所有模块都引了它。第三个犀利观点entity、DTO、VO的分离不是“多写几个类”的问题而是结构腐化的分水岭。很多项目为了“简化”直接用entity充当响应体甚至把数据库字段暴露给前端。等加了权限校验、脱敏、版本兼容需求时只能往entity里塞一堆JsonIgnore和临时字段。正确的做法是让每一层有自己的模型语言JPA实体只表达持久化结构DTO负责API输入输出Domain对象承载业务规则。哪怕初期看起来重复但当业务复杂到一定程度这种“重复”恰恰是保护层让数据库表结构变化不至于炸到接口契约。那么包结构究竟怎么落地我推荐“业务域内部结构”的清晰范式。顶级包按业务域拆分每个域内部包含api对外接口与DTO、application应用服务/用例、domain实体、值对象、领域服务、infrastructure持久化、外部客户端。这个结构借鉴了整洁架构但不必拘泥于五层。关键是依赖方向必须从外向内api依赖applicationapplication依赖domaininfrastructure依赖domain但被application反向依赖。SpringBoot的依赖注入让这些方向天然正确但目录却常常写反导致infrastructure里的工具类被controller直接调用绕过了业务规则。我见过最隐蔽的坏味道是“万能service”。一个OrderService里同时处理支付回调、库存扣减、积分发放、物流同步。表面看它“包治百病”实际上它违反了单一职责所有用例被揉进一个上帝类。当你想复用“确认订单”逻辑时发现它必须在某个service方法里而且你没法只调用它而避开其他副作用。破局之道是把“用例”作为一等公民——一个用例一个类命名如PlaceOrderUseCase、CancelOrderUseCase。这些类放在application包下它们编排domain对象和repository接口而不再有所谓的“业务service”层。这会让项目结构看起来类变多了但每一个类的名字都直指业务意图可测试性也大幅提升。另外包与包之间的循环依赖是结构清晰度的最大杀手。在SpringBoot中循环依赖有时能被容器“勉强”解决但包结构的循环依赖会让人彻底崩溃。比如order包的service反向依赖了user包的repository而后者的某处又依赖了order的DTO。这种纠缠一旦出现你无法独立改动任何一个域任何局部重构都像在雷区跳舞。强制规则很简单业务域名之间禁止相互依赖跨域协作通过领域事件或解耦接口进行。具体做法是当订单需要用户信息时不要在order包里直接注入UserRepository而是定义UserQueryPort接口让infrastructure层实现这个端口。这样order包只依赖一个抽象契约真正的用户状态由user域负责。还有一个高频痛点Controller里堆业务逻辑。有人把参数校验、数据组装、权限判断全写在Controller方法里一个方法上百行。这和包结构无关却直接反映结构设计缺失。Controller的唯一职责是解析HTTP、绑定参数、调用应用服务、返回响应。任何超出这些的动作都必须下沉到application或domain。否则你会看到Controller依赖了repository、甚至事务注解——这意味着技术层之间的边界已经荡然无存。判断结构是否清晰最简单的方法是看一个改动需要同时触碰几个包。让我用一次真实重构展示效果。原项目顶级包是controller/service/mapper/entity其中service有120个类实体和VO混用。重构后顶级包变为order/product/user/payment/customer-support每个业务域下用api/application/domain/infrastructure组织。原UserService被拆成GetUserUseCase、UpdateProfileUseCase等并把UserEntity拆成UserAccountDO持久化和UserProfileVO响应。结果修改用户头像的功能只动了user里的四个文件不需要打开order包新接一个支付渠道时新增类只在payment/infrastructure里。整个系统的可理解性直接从“按打字员分类”升级为“按业务负责人分类”。有人担心这种结构过度设计对于小项目是负担。确实一个只有三个实体的CRUD服务按业务域加用例类会显得笨重。但结构设计从来不是为今天写的而是为三个月后的预期复杂度写的。更务实的做法是渐进式重构先保证顶级包按业务域划分哪怕内部暂时保留controller/service/dao当某个业务域里的service超过十个方法或三个用例时再内部引入application和domain。 记住清晰的结构不是一次画出来的是随着对业务理解的加深不断演进出来的。关键是建立一套“依赖方向”和“命名即意图”的纪律并把这种纪律写进CheckStyle或ArchUnit测试里让CI拦住下一次腐化。如果给所有原则排个序我最看重一条包结构应当是“按业务能力垂直切片”而不是“按技术细节水平分层”。垂直切片意味着每个业务域拥有自己从API到持久化的完整实现改动被限制在切片内水平分层则让每次需求穿过所有层等于每次改动都在“全量编译”。SpringBoot给了你极大的自由但也给了你极大的腐蚀空间。真正的清晰不是目录多么优雅而是任何一位新成员都能在十分钟内找到“某个操作”应该住的包并且改完不担心影响别处。当你的项目做到这一点SpringBoot结构设计才算真正及格。
我见过太多SpringBoot项目启动类后面跟着五个包controller、service、dao、entity、config。三个月后service包下膨胀出几百个类命名从UserService到UserServiceImpl再到UserBizService没人说得清某个功能到底在哪个类里。改一个需求要翻三四个包加一个字段要动五个文件。这种结构的核心问题不是“分不够细”而是包结构完全是技术分层的复读从未表达过业务边界。清晰的SpringBoot项目结构第一原则是包结构映射业务域而不是映射技术角色。技术分层是运行时依赖的约定目录是用来让人快速理解“这个系统管哪些事”的。当你打开项目的顶级包看到的应当是“订单”“商品”“用户”这样的业务域而不是“controller”“service”“dao”这样的技术层。业务域之间天然隔离改动彼此独立而技术层之间则存在强耦合任何需求都会穿透三层导致改动无法局部化。有人会问那controller、service这些放哪里答案是放在业务域内部作为二级包。比如com.company.order下面可以有controller、service、repository、domain但“tech.layer”作为顶级目录只会让代码按照“我是什么”分类而不是按照“我属于哪块业务”分类。按业务域组织后你要改订单相关功能直接进入order域无需在全局几十个技术包里做“语境切换”。这才是“清晰”的第一含义——减少导航成本。第二个必须想清楚的问题是项目结构到底要为谁服务为一个刚启动的Demo服务单模块加技术分层没问题但一旦业务复杂到十几个人协作结构就必须能隔离团队、隔离发布、隔离失败。很多人上来就拆多模块结果拆出五个模块互相同引最后干脆用一个公共common包放所有实体——这比单模块更糟。拆分的核心依据是依赖方向而不是“看着整齐”。一个模块如果被所有其他模块依赖那它就是变相的全局垃圾场。SpringBoot项目里最典型的反面教材就是common或util模块里面塞满DateUtils、StringUtils、BaseEntity、Result最后没人敢删因为所有模块都引了它。第三个犀利观点entity、DTO、VO的分离不是“多写几个类”的问题而是结构腐化的分水岭。很多项目为了“简化”直接用entity充当响应体甚至把数据库字段暴露给前端。等加了权限校验、脱敏、版本兼容需求时只能往entity里塞一堆JsonIgnore和临时字段。正确的做法是让每一层有自己的模型语言JPA实体只表达持久化结构DTO负责API输入输出Domain对象承载业务规则。哪怕初期看起来重复但当业务复杂到一定程度这种“重复”恰恰是保护层让数据库表结构变化不至于炸到接口契约。那么包结构究竟怎么落地我推荐“业务域内部结构”的清晰范式。顶级包按业务域拆分每个域内部包含api对外接口与DTO、application应用服务/用例、domain实体、值对象、领域服务、infrastructure持久化、外部客户端。这个结构借鉴了整洁架构但不必拘泥于五层。关键是依赖方向必须从外向内api依赖applicationapplication依赖domaininfrastructure依赖domain但被application反向依赖。SpringBoot的依赖注入让这些方向天然正确但目录却常常写反导致infrastructure里的工具类被controller直接调用绕过了业务规则。我见过最隐蔽的坏味道是“万能service”。一个OrderService里同时处理支付回调、库存扣减、积分发放、物流同步。表面看它“包治百病”实际上它违反了单一职责所有用例被揉进一个上帝类。当你想复用“确认订单”逻辑时发现它必须在某个service方法里而且你没法只调用它而避开其他副作用。破局之道是把“用例”作为一等公民——一个用例一个类命名如PlaceOrderUseCase、CancelOrderUseCase。这些类放在application包下它们编排domain对象和repository接口而不再有所谓的“业务service”层。这会让项目结构看起来类变多了但每一个类的名字都直指业务意图可测试性也大幅提升。另外包与包之间的循环依赖是结构清晰度的最大杀手。在SpringBoot中循环依赖有时能被容器“勉强”解决但包结构的循环依赖会让人彻底崩溃。比如order包的service反向依赖了user包的repository而后者的某处又依赖了order的DTO。这种纠缠一旦出现你无法独立改动任何一个域任何局部重构都像在雷区跳舞。强制规则很简单业务域名之间禁止相互依赖跨域协作通过领域事件或解耦接口进行。具体做法是当订单需要用户信息时不要在order包里直接注入UserRepository而是定义UserQueryPort接口让infrastructure层实现这个端口。这样order包只依赖一个抽象契约真正的用户状态由user域负责。还有一个高频痛点Controller里堆业务逻辑。有人把参数校验、数据组装、权限判断全写在Controller方法里一个方法上百行。这和包结构无关却直接反映结构设计缺失。Controller的唯一职责是解析HTTP、绑定参数、调用应用服务、返回响应。任何超出这些的动作都必须下沉到application或domain。否则你会看到Controller依赖了repository、甚至事务注解——这意味着技术层之间的边界已经荡然无存。判断结构是否清晰最简单的方法是看一个改动需要同时触碰几个包。让我用一次真实重构展示效果。原项目顶级包是controller/service/mapper/entity其中service有120个类实体和VO混用。重构后顶级包变为order/product/user/payment/customer-support每个业务域下用api/application/domain/infrastructure组织。原UserService被拆成GetUserUseCase、UpdateProfileUseCase等并把UserEntity拆成UserAccountDO持久化和UserProfileVO响应。结果修改用户头像的功能只动了user里的四个文件不需要打开order包新接一个支付渠道时新增类只在payment/infrastructure里。整个系统的可理解性直接从“按打字员分类”升级为“按业务负责人分类”。有人担心这种结构过度设计对于小项目是负担。确实一个只有三个实体的CRUD服务按业务域加用例类会显得笨重。但结构设计从来不是为今天写的而是为三个月后的预期复杂度写的。更务实的做法是渐进式重构先保证顶级包按业务域划分哪怕内部暂时保留controller/service/dao当某个业务域里的service超过十个方法或三个用例时再内部引入application和domain。 记住清晰的结构不是一次画出来的是随着对业务理解的加深不断演进出来的。关键是建立一套“依赖方向”和“命名即意图”的纪律并把这种纪律写进CheckStyle或ArchUnit测试里让CI拦住下一次腐化。如果给所有原则排个序我最看重一条包结构应当是“按业务能力垂直切片”而不是“按技术细节水平分层”。垂直切片意味着每个业务域拥有自己从API到持久化的完整实现改动被限制在切片内水平分层则让每次需求穿过所有层等于每次改动都在“全量编译”。SpringBoot给了你极大的自由但也给了你极大的腐蚀空间。真正的清晰不是目录多么优雅而是任何一位新成员都能在十分钟内找到“某个操作”应该住的包并且改完不担心影响别处。当你的项目做到这一点SpringBoot结构设计才算真正及格。
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
