前几天我在一个内部项目的技术评审上讲架构调整PPT刚翻到“模块化”那一页就有人直接举手问“你们说的模块化和我现在把 Maven 拆成几个子模块有什么区别”这个问题我太熟了两年前我也这么问过。当时以为自己把 service、dao、controller 分到不同 Maven module 里就是模块化了结果两年后代码一样乱循环依赖一样绕线上出问题时还是要在包之间翻来翻去。Spring Boot 4 的模块化架构正是冲着这个痛点去的。它不是让你换个目录结构就算完事而是希望你在代码层面把业务边界、依赖方向、自动配置的加载范围都想清楚。这篇文章我会直接说清楚Spring Boot 4 的模块化到底改了什么和 Spring Boot 3 的自动配置模式有什么本质区别以及如果你手上正好有个老项目按什么步骤迁过去最不容易翻车。适合正在做单体应用整理、准备微服务拆分、或者单纯被自家 Spring Boot 项目的依赖关系搞到头疼的人。1. 升级到 Spring Boot 4 前先看懂模块化架构的来龙去脉1.1 为什么 Spring Boot 4 要把“自动配置”收敛成“模块边界”Spring Boot 从 1.0 开始就靠“自动配置”打天下开发者引入一个 starter 就能凭空多出一整套可用的能力。对快速启动一个 demo 来说这简直是神技但把项目养到三四年、几十万行代码之后问题就变了你根本说不清楚某个 bean 是被哪个自动配置拉进来的。我印象很深的是有一次排查 Redis 连接池的闲置超时翻到某个中间件 jar 里的RedisAutoConfiguration才发现配置顺序被另一个 starter 影响了那种排查效率基本靠猜。Spring Boot 4 在模块化架构上做得最坚决的一件事就是让模块边界成为比“依赖坐标”更真实的组织单元。你可以把多个配置类、领域服务、数据访问对象收进一个显式的模块里模块与模块之间不再默认可见所有 bean。换句话说Spring Boot 4 希望你把原先靠package scan和Autowired碰出来的关系改成可以用代码和工具验证的显式依赖。这跟我做项目时的感觉是一致的。显式依赖虽然写起来多花几行代码但整个系统的行为会回归可推测的状态。比如你要换掉某个核心实现不再需要担心“哪个地方还隐式引用了这个 bean”因为模块的依赖清单已经列清楚了。1.2 从包扫描到显式模块声明工程组织方式怎么变了Spring Boot 3 时代大多数项目的起点是一个主类主类所在的包默认成为根包然后从这个根包往下扫描所有Service、Component、Repository。这套机制非常省事但它有个隐藏的副作用包结构本质上只表达了代码的存放位置不表达业务上的依赖规则。你去读任何一个项目的包目录能看出“订单模块不能依赖支付模块”吗看不出来因为扫描机制下谁都能引用谁。Spring Boot 4 的模块化架构把这个默认行为改了。你在代码里声明模块的时候通常会指定这个模块能访问哪些其他模块。例如一个order模块可以在声明中指定允许依赖customer和inventory但不允许依赖delivery。这个声明不是注释它会被模块化工具在编译期和测试期做校验。我在本地实验时故意在订单模块里注入了一个delivery模块的 service结果上下文启动时直接报错把非法依赖从运行期风险变成了启动期错误。从工程组织上看Spring Boot 4 鼓励你把原先散落的包重新收拢成这种结构com.example.app ├── customer │ ├── CustomerModuleConfiguration.java │ └── internal ├── order │ ├── OrderModuleConfiguration.java │ └── internal └── inventory ├── InventoryModuleConfiguration.java └── internal模块的内部包分成两层对外暴露的公共接口、内部实现。外部只能依赖公共接口内部实现哪怕漏了public修饰符模块校验工具也能识别出来。这一套组合拳把“分包”升级成了“分模块”。1.3 模块化架构对已上线项目最直接的三点影响第一bean 默认不再是无差别注入。Spring Boot 4 的模块系统会对跨模块的注入做限制新项目如果不注意启动时就会被明确指出“跨模块依赖未声明”。这个变化比 Spring Boot 3 里的循环依赖检查更严格因为循环依赖检查只针对对象之间的环而模块检查针对的是包与包之间的方向。第二自动配置的粒度被收紧。Spring Boot 4 强化了对第三方自动配置的开关控制很多原先靠“放到 classpath 里就生效”的组件现在要求你在模块配置中明确导入或排除。听起来麻烦但我在实践里能明显感觉到应用启动变得可控不会因为加了某个 SDK 突然多出一堆你并不需要的定时任务或连接池。第三测试的边界更清晰。以前写SpringBootTest会把整个上下文都拉起来跑一个单元测试等几十秒。模块化之后可以用模块级的测试注解只加载当前模块的上下文。我在实践中的体感是单测编译和启动时间平均降了 30% 以上这对模块多的项目帮助很大。2. 模块化带来的核心变化与常见误区2.1 显式声明模块后原来的“约定”失效在哪里最容易踩的坑是以为把原来的SpringBootApplication挪到某个模块里就完事。Spring Boot 4 里主类默认只负责引导启动包扫描规则变得严格甚至在某些配置下不推荐再用全量扫描。也就是说原来你随手放在根包下的Component现在可能根本不会被加载。我踩过一次印象很深的坑把一个老项目升级到 Spring Boot 4 里程碑版本后启动日志全部正常但某个定时任务就是不触发。排查了半天发现那个任务类放在项目根包的一个schedule子包里主类的模块配置只声明了order和customer两个模块这个子包不在扫描范围内。老项目把扫描范围当默认配置新架构把扫描范围当成显式约束这个思维转换是升级的第一道坎。另外SpringBootApplication里隐含的EnableAutoConfiguration在新版本中建议你拆分出来。比如你可以在模块配置类上单独使用EnableAutoConfiguration并指定excludeName来控制自动配置的启用范围。这样主类职责更单一模块自身的能力边界也更清楚。2.2 三类模块拆分方式怎么选我见过不少团队在讨论模块化拆分时先争技术架构再谈业务。实际上模块化的核心是业务边界。按我的经验有三类拆分方式比较常见第一类是“按业务域拆分”。这是最推荐的做法。把订单、用户、库存、支付这些业务域拆成模块每个模块内部包含自己的 controller、service、repository 和事件监听器。优点是最贴合业务认知团队天然知道自己该维护哪个模块。第二类是“按技术层拆分”。把 controller、service、mapper 各拆一个模块。这种拆法编码阶段很清爽但每加一个业务需求要横向改多个模块时间一长模块数量爆炸。我只在很小的项目或底层基础库上见过这种拆法勉强能跑。第三类是“按功能点拆分”。比如说把“订单导出”“订单统计”“订单分润”各拆一个模块。这种拆法适合业务功能相对独立、复用度低、希望独立部署的场景。缺点是模块边界太细重复代码容易在多个模块里散落。选择标准我用一个很朴素的原则看模块间依赖是稳定的还是易变的。凡是一两个月内经常一起改动的代码不论叫什么名字都不该拆到两个模块里。实践一段时间你会认同这个标准模块化拆分的核心不是“分”而是“如何让高频一起变化的事物保持内聚”。2.3 模块间通信的正确姿势模块化之后一个最直接的疑问是模块之间肯定有数据交互怎么通信才不算破坏边界我的建议是优先定义“模块对外接口”而不是把内部实现类暴露给其他模块。比如订单模块要查询用户模块的收货地址你可以在customer模块里定义一个接口public interface CustomerQueryPort { Address getDefaultAddress(String customerId); }然后在customer模块内部有一个类实现它订单模块只依赖这个接口两个模块之间不直接碰具体 service 类。这就是模块化架构里常说的“端口与适配器”模式虽然多写一个接口但好处非常直接依赖方向始终由业务方向决定而不会因为某个FeignClient或Mapper绕来绕去变成一团乱线。另外一个常用的通信方式是事件。当一个模块完成核心业务后发布领域事件其他模块通过监听响应。Spring Modulith 在这个场景下提供了ApplicationEventPublisher和ApplicationModuleListener的天然支持并且能够记录事件发布和消费的路径。我在订单支付成功后发送“订单已支付”事件的场景里就用事件通信避免了订单模块直接调用支付模块的内部方法。3. 从 Spring Boot 3 迁移到 Spring Boot 4 的实操流程3.1 升级前的依赖与基线检查不要直接一把梭改代码。Spring Boot 4 的模块化架构对老项目冲击最大的是依赖方向所以升级前我建议先做一次基线盘点。我把这次盘点分成三步第一步列出所有第三方 starter 的自动配置类。具体方法是扫描所有依赖 jar 里的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件看看每个依赖都带入了哪些自动配置。你会发现很多你以为没用上的功能其实一直在后台初始化。这一步不要偷懒后面排查启动慢和 bean 冲突全靠这张清单。第二步画出当前应用的主要调用依赖图。你可以用 IDE 的依赖分析功能或者直接靠架构评审手动梳理。重点标记出哪些包之间存在“跨业务域依赖”例如订单模块的 service 直接调用了配送模块的 mapper。这些点就是迁移时要优先处理的。第三步确认 Java 版本和构建工具。Spring Boot 4 的基线要求更严格老项目如果还在 Java 11 或 Java 8先把基础环境升级到位再谈模块化。构建工具建议至少用 Maven 3.9 或 Gradle 8.5否则部分插件解析新注解时会出现诡异问题。3.2 按业务边界拆模块一个订单模块的完整示例下面我以一个非常典型的订单场景演示从 Spring Boot 3 到 Spring Boot 4 模块化迁移的最小步骤。假设原项目结构是这样的com.example.store ├── StoreApplication.java ├── controller │ ├── OrderController.java │ └── CustomerController.java ├── service │ ├── OrderService.java │ └── CustomerService.java └── repository ├── OrderRepository.java └── CustomerRepository.java先拆customer模块。新建包com.example.store.customer在模块根包下放一个配置类package com.example.store.customer; import org.springframework.context.annotation.Configuration; Configuration(proxyBeanMethods false) public class CustomerModuleConfiguration { }然后把原先的CustomerController、CustomerService、CustomerRepository全部移动到这个模块下。为了让别的模块能引用它我在模块内单独建立一个CustomerApi接口把最常用的查询方法暴露出来package com.example.store.customer.api; public interface CustomerApi { String getCustomerName(String customerId); }模块内的 service 实现这个接口然后配置类通过Bean把它显式注册出去。接着拆order模块同样放一个OrderModuleConfiguration并在配置类中导入CustomerModuleConfiguration提供的接口实现对订单模块可见package com.example.store.order; import com.example.store.customer.api.CustomerApi; import org.springframework.context.annotation.Configuration; Configuration(proxyBeanMethods false) public class OrderModuleConfiguration { private final CustomerApi customerApi; public OrderModuleConfiguration(CustomerApi customerApi) { this.customerApi customerApi; } }这样装配的好处是order模块在编译期只依赖customer.api而不会依赖customer模块内部的 repository 或实体类。我在实际迁移时这种改动让原本纠缠在一起的关联关系肉眼可见地清晰了。3.3 控制自动配置的几种写法模块化之后对自动配置的控制不再是“全局一个大开关”而是分散到模块自己的配置类里。我常用的方式有三种。第一种模块级排除。在模块配置类上使用EnableAutoConfiguration(excludeName ...)例如Configuration EnableAutoConfiguration(excludeName { org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration }) public class SomeModuleConfiguration { }这个写法的适用范围是单个模块明确不需要某个自动配置能力。它让配置与模块需求一一对应不会因为全局配置误伤其他模块。第二种全局排除。在主配置里用spring.autoconfigure.exclude适合排掉那些对整个应用都无意义的自动配置。例如你根本没使用 Kafka却因为某个公共依赖把它带进来了spring: autoconfigure: exclude: - org.springframework.boot.autoconfigure.kafka.KafkaAutoConfiguration第三种使用 starter 条件化配置。在模块里通过ConditionalOnClass、ConditionalOnProperty等条件注解让配置类只在满足特定条件时生效。这种方式最灵活但也最容易写乱我建议只在确实存在“某些环境要开、某些环境要关”的需求时使用。3.4 配置文件的模块化分拆代码拆完之后配置文件也得跟着模块化否则还是会出现“订单模块按着 new-config 里的配置走”这种割裂感。Spring Boot 4 引入了配置文件的多个文档块和按模块导入能力你可以把配置拆成多个文件再在application.yml里导入spring: config: import: - classpath:order-module.yml - classpath:customer-module.yml每个模块维护自己的数据源、缓存、消息队列配置。我在实际项目里发现这个改动对团队协作的改善特别明显负责订单的人不需要在几百行的总配置文件里找自己的段落只要去order-module.yml里改就完事了。需要提醒的是模块配置文件和自动配置的加载顺序仍然遵循 Spring 的环境属性优先级规则。如果你在总配置里写了数据源地址又在模块配置里写了一遍总配置里的值会覆盖模块配置里的值。我第一次迁移时被这个优先级坑到以为模块配置没生效查了半天才发现两边都写了配置。4. 迁移中最常遇见的五个问题与排查方案4.1 模块的 Bean 没有被加载这是升级后最常见的现象主类能正常启动但某个模块的Service或Repository没被加载等到运行期处理业务时才报NoSuchBeanDefinitionException。我在迁移时就遇到过当时第一反应是代码没扫描到后来才发现是模块声明里没有把对应的配置类 import 进去。Spring Boot 4 对模块的加载依赖显式声明不像从前靠包路径自动覆盖。排查这种问题的路径很固定。先看启动日志有没有该模块配置类的初始化记录再用ContextConfiguration(classes ModuleConfiguration.class)单独测试模块最后检查模块之间的依赖声明是否遗漏。我建议把这一项加入 CI 的自检脚本每次提交都跑一遍模块上下文启动测试成本低收益高。4.2 循环依赖在模块化之后反而更多了听起来很奇怪模块化明明是为了解耦为什么循环依赖反而变多原因是一些团队把 service 层互相引用的坏习惯原样搬到了模块层。比如订单模块的 service 注入了用户模块的 service用户模块的 service 又注入了订单模块的审计服务在两个模块里各自看都合理连起来就是一个环。模块化工具只在启动阶段对明显的循环依赖做报错但业务层面的循环是隐性的。我的解决办法有两个一个是把争议的依赖下沉到一个基础模块中比如审计服务放到公共模块另一个是把双向调用改成事件通信让一方只发布事件另一方监听响应从而取消静态依赖。第二种办法实践下来对解耦最有效但前提是业务允许最终一致性如果你要的事务边界很强那就只能老老实实做代码级重构。4.3 测试环境与本地启动的差异我在一个里程碑版本上遇到过本地跑mvn spring-boot:run一切正常一到测试环境的 CI 上就报模块校验失败。仔细对比发现本地的 IDE 编译顺序和 Maven 多模块的构建顺序不一致导致模块校验器读到的依赖图不同。这种问题的隐蔽性很强不是代码问题而是构建环境问题。规避方法很简单统一用 Maven 或 Gradle 做本地和 CI 的构建不要依赖 IDE 的编译和运行能力。同时在 CI 上增加一条专门的任务运行一次全局模块验证测试。如果你还在用 IDE 直接跑主类做日常调试升级到 Spring Boot 4 后建议尽快切换到命令行构建方式减少这类“在我电脑上是好的”的灵异事件。4.4 第三方库的自动配置被“里外不是人”模块化之后由第三方 starter 自动装配的 bean默认归属变得模糊。比如某个内部中间件 starter 里的AutoConfiguration类自动装配进了用户模块的上下文但这个中间件的依赖项在另一些模块里也存在。你会在启动阶段看到“模块 runtime classpath 不匹配”等字样。处理办法是收缩自动配置的加载范围。先用 3.1 节里的方法列出第三方自动配置清单然后通过模块级excludeName逐个判断。注意看一下第三方 starter 是否提供了自己的模块化适配包我在实践中发现不少主流中间件已经出了与 Spring Boot 4 配套的模块扩展能直接声明依赖而不是靠扫描生效。4.5 过滤器、拦截器和 Servlet 组件的路径问题这是一个很容易被忽略的坑。老项目里一个全局过滤器可能写在common包里Spring Boot 3 时代随手就能注册到所有请求链路里。模块化之后过滤器如果不在模块的注册路径范围内就可能只对部分模块的请求生效。例如我在迁移时遇到权限过滤器只拦截了order/**没有拦截customer/**。排查办法是在模块配置类中显式注册过滤器并定义 URL 模式Bean public FilterRegistrationBeanAuthFilter authFilter() { FilterRegistrationBeanAuthFilter bean new FilterRegistrationBean(); bean.setFilter(new AuthFilter()); bean.addUrlPatterns(/api/*); return bean; }不要依赖Component加WebFilter的旧写法模块化下显式注册是更安全的选择。5. 模块化落地工具箱与个人的后端实践经验5.1 用 Spring Modulith 给模块加一道“架构安全网”Spring Boot 4 的模块化理念和 Spring Modulith 的协作非常紧密。我不建议全靠人肉 review 去保证模块边界而是建议直接用工具把“不能依赖”变成“编译期就不能依赖”。Spring Modulith 提供一个验证器可以扫描模块并生成依赖报告。在测试里加一个最基础但有价值的用例ApplicationModuleTest class ApplicationModularityTests { Test void shouldHaveCleanModuleDependencies() { ApplicationModules modules ApplicationModules.of(Application.class); modules.verify(); } }这个测试的目的不是验证业务逻辑而是验证构架规则哪些模块可以依赖哪些模块、哪些模块不能依赖哪些模块。跑一次如果架构被破坏了测试就挂。它相当于给模块边界装了一个报警器。5.2 在 CI 中加一层独立启动健康检查模块化改造最怕的就是“代码拆分通过但应用启动不了”。我建议在 CI 流水线里加一个contextCheck步骤单独跑一个空上下文启动任务启动时不连真实中间件使用本地测试配置和最小化的 bean 加载范围。这层检查可以在几分钟内发现自动配置冲突和模块依赖缺失比等到联调阶段再爆问题划算得多。我自己的习惯是专门建一个modularity-checkMaven profile里面放模块校验测试和上下文启动测试开发分支每次提交都跑主分支合并前再强制跑一遍。这样做之后模块化相关的问题基本在提交阶段就暴露了不需要拉一群人来一起看启动日志。如果有条件还可以把模块依赖图以 PlantUML 或 DOT 格式导出贴在项目 Wiki 里。团队新人读代码前先看模块图比看几百页开发文档更快上手。要注意的是不要用 mermaid 类的图表要求严格依赖方向校验直接用 Spring Modulith 生成的报告最权威。5.3 我推荐的落地顺序以及一个值得试的冷门技巧如果你手头的项目比较老不要试图在一个大版本里完成全部模块化。我推荐这个落地顺序先梳理依赖清单和自动配置清单再选定一个独立业务域做试点模块试点跑顺了再逐批推进。第一阶段别追求完美架构先把“扫描约定”改成“显式声明”这已经能让不少隐性依赖暴露出来。一个实操价值很高的冷门技巧是在迁移过程中先不要急着删掉旧的包路径。Spring Boot 4 的模块校验器支持排除规则你可以在迁移初期把尚未整理的老包设为“待迁移”状态让校验器放行这些包等新模块逐步覆盖后再收紧规则。这样既不会因为模块化导致项目长期无法发布又能渐进式地推进改造。我个人在实际改造中的体感是模块化架构最贵的成本不在编码而在团队对“依赖方向”的共识。以前写代码时顺手Autowired一个别的模块的类五分钟就写完了现在要先想接口、想事件、想依赖是否允许。但只要熬过了前两个迭代后续新增功能反而更顺因为你不再需要为了搞懂一段代码翻遍整个项目。最后再分享一个建议把模块化边界检查一直保留在 CI 里它是整个改造中最便宜、也最能防止架构腐化的防线。