前段时间接手一个老项目的改造需求技术栈锁定Spring Boot 3.2.10 OpenJDK 17业务要拆成xxx_api_service对外提供接口再单独做一个xxx_admin_service作为管理平台后端。很多人拿到这种需求第一反应就是先建一个多模块 Maven 工程把 common、api、admin 三个目录一摆然后开始写业务。这个思路不能说错但我在实际落地过程中发现如果不在动手前把模块边界、依赖方向、统一异常和日志链路这些“企业级规范”想清楚后面几周基本就是在和循环依赖、接口返回格式不统一、权限模型混乱做斗争。这篇文章就把我的规划过程和踩坑经历完整写出来给准备做 Spring Boot 3 多服务拆分、还在纠结模块怎么划的同学一份可以直接参考的作业。1. 先想清楚为什么要拆出 api_service 和 admin_service 两个服务1.1 两类接口的服务对象、风险模型完全不是一回事很多团队把对外接口和管理端接口放在同一个服务里图省事觉得无非就是多几个RequestMapping。但只要你站在“企业级开发规范”的角度看这两类接口的风险模型是天然冲突的。对外 API 的调用方是第三方系统、小程序、App流量不可控随时随地可能被刷、被爆破、被重放攻击。你要考虑签名、限流、幂等、错误信息模糊化甚至要按客户维度分配独立的访问凭据。而管理端接口的调用方是内部运营、管理员频率低但权限敏感核心诉求是 RBAC 权限控制、数据权限隔离、操作审计、登录态管理。如果把这两类接口混在一个服务里会出现一个很尴尬的情况要么为了对外安全把所有接口都套上签名校验导致管理端调试成本暴涨要么为了管理端方便把所有接口都放开对外接口的安全形同虚设。我用一个不太严谨但很直观的类比对外 API 就像餐厅门口的点餐窗口任何人路过都可能来敲一下管理后台就像后厨管理通道只允许穿制服的员工进出。你把窗户和管理通道修在同一个门里保安就没法定义“到底拦谁不拦谁”。所以拆成两个独立部署单元本质上是把安全边界的定义权分开了。1.2 拆分之后公共逻辑放哪最容易被忽略的问题拆成两个服务之后第一个遇到的问题就是公共的东西放哪。比如 Result 包装类、业务异常、通用工具类、各种枚举、DTO 基类两个服务都要用。我见过很多项目拆完模块之后公共逻辑乱放最后发展成xxx_admin_service直接依赖xxx_api_service只为了用里面一个UserDTO。这种依赖关系一旦形成两个服务的边界又糊了。正确的做法是抽一个独立的公共工程比如xxx-common但它只能放与业务无关的通用能力。真正和业务相关的 DTO、枚举、接口契约应该放在另一个独立的xxx-api-contract或xxx-api-client模块里这个模块可以被 api_service、admin_service、甚至未来的外部消费者共同引用。这里有一个很关键的思想转变拆服务的目的不是物理上分开就算完而是要明确每一层的“知识边界”。比如UserDTO不该属于某个 Web 模块它属于“对外契约”UserService接口属于业务核心逻辑UserServiceImpl属于业务实现。规划模块时按“契约、业务、实现、入口”四层来分而不是按 api 和 admin 两个词来分。1.3 什么时候不该拆中小项目的反向选择说句公道话不是所有项目都适合一上来就拆两个服务。如果你团队只有两三个人、业务模型还不稳定、并发和审计要求都还没起来强行拆成 api_service 和 admin_service意味着两套应用要部署、两套日志要采集、两套配置要维护光公共模块的版本升级就能拖垮你。这种情况下我更推荐“先分模块后分服务”的策略在一个 Spring Boot 应用里先按api和admin分包目录不与业务交叉同时把system、repository这些核心模块独立出来。等哪天业务边界清晰了、并发和权限要求上来了再基于这些模块拆成两个可独立部署的启动器。文章后面讲的模块规划方式其实对这种渐进式拆分同样适用因为它从第一天起就没有让业务逻辑和 Web 入口耦合。2. 基线选型Spring Boot 3.2.10 OpenJDK 17 的兼容性边界2.1 为什么锁死 3.2.10 而不是追新技术选型时团队定Spring Boot 3.2.10大概率不是因为你追新而是因为它是 3.2.x 这条维护分支里比较晚的补丁版本安全漏洞修得多同时又不至于像 4.x 那样激进到让一堆第三方组件适配不过来。OpenJDK 17 则是目前企业里最主流的 LTS 版本比 11 拿到更好的 GC 和容器感知能力比 21 的生态兼容风险小。我实际用下来3.2.x对 Spring MVC、MyBatis、Redis、OpenAPI 这些核心组件的兼容都比较成熟。它比 3.0/3.1 最大的进步是处理了一批 Spring Framework 6.1 底层的边界问题比如 HTTP 客户端在请求关闭后的异常行为、JDK 序列化相关配置警告。这些细节在开发联调阶段不显眼上线后在高并发下非常容易暴露。还有个现实原因很多企业内部依赖了自研或二方组件比如统一认证 SDK、日志框架、对象存储客户端这些组件往往还没跟进 Spring Boot 4.x。锁死 3.2.10可以避免在依赖升级上反复消耗工时。2.2 工具链版本对齐清单登录pom.xml之前先确认工具链版本。我在项目初始化时吃过太多版本错配的亏下面这份清单是当前 3.2.10 JDK 17 下我验证过比较稳的组合组件/框架推荐版本说明Maven3.9.x3.8 以下对 JDK 17 支持不完整Spring Boot3.2.10父 POM 统一管理依赖Lombok1.18.30老版本无法在 JDK 17 下编译MapStruct1.5.5.Final和 Lombok 一起用时需配 annotationProcessorPathsspringdoc-openapi2.5.0支持 Spring Boot 3.2旧 springfox 无法使用MyBatis-Plus3.5.73.5.5 以下对 Spring Boot 3 支持有缺陷Sa-Token / Spring Security按需选型注意要求 jakarta 命名空间版本Hutool5.8.25如果不想自己写工具类Fastjson22.0.5x不要再引入 fastjson 1.x这里特别提醒一下很多老项目之前在 Spring Boot 2.x 时代用的是springfox-swagger2这东西在 Spring Boot 3 里基本不可用因为它的底层依赖还是 javax。正确做法是迁移到 springdoc如果你的对外 API 需要给第三方看文档springdoc 的 OpenAPI 分组能力也更好用。2.3 JDK 17 带来的编译与反射限制JDK 17 不是换了个版本号那么简单它对做 Java 后端的人有三道坎第一Java EE 包从javax.*迁移到了jakarta.*。这意味着HttpServletRequest、PostMapping这些类的 import 全部要改。Spring Boot 3 的 starter 里已经内置了 jakarta API但很多老三方的 jar 还是用javax.servlet编译的运行时就会直接 NoClassDefFoundError这类问题只能通过升级依赖解决没有捷径。第二JDK 17 默认启用了强封装。以前我们可以用--add-opens来反射访问 JDK 内部类虽然能用但属于拿头撞墙。Spring Framework 6 已经调整了内部实现不再依赖强封装所以如果你在项目里手写了大量反射工具类建议趁这次改造改成 Spring 的ReflectionUtils或者MethodHandles。第三代理机制的变化。Spring Boot 3 默认使用 CGLIB 代理不强制使用 JDK 动态代理。CGLIB 意味着如果你的业务类被定义为final或者方法被定义为finalAOP 注解很可能不生效。这个问题在之前 Spring Boot 2 时代就有但在 3.x 里更明显因为很多自动配置内建代理都是 CGLIB。我建议团队统一约定被 AOP 注解的 service 实现类不要加 final。3. 模块规划实操能够直接落地的多模块工程结构3.1 顶层模块划分与依赖方向下面是我在项目里最终落地的一套模块结构直接把api_service和admin_service作为可部署的启动器应用业务核心逻辑放在system模块避免两个入口各自实现一遍。xxx-parent ├── xxx-common # 通用工具、Result、异常基类、上下文 ├── xxx-api-contract # 对外接口的 DTO、枚举、Feign API 定义 ├── xxx-system # 领域业务逻辑、service 接口与实现 ├── xxx-repository # MyBatis-Plus 实体、Mapper、数据对象 ├── xxx-api-service # 对外 API 启动器 └── xxx-admin-service # 管理端启动器依赖方向必须是一条单向链路starters - system - repository - commonstarters - api-contract - common绝对禁止反向依赖禁止两个 starter 之间互相依赖也禁止system依赖任何 starter。换句话说业务核心模块不感知自己是给 API 用还是给管理端用它只提供能力。这样的好处是将来如果再拆一个内部任务调度服务也能直接复用 system。为了让这条规则不被破坏我建议在父 POM 里用maven-enforcer-plugin配置 banned dependencies把反向依赖直接拦在编译阶段。这个动作成本很低但对团队执行力的约束效果非常好。3.2 对外接口模块 xxx-api-service 的建模重点xxx-api-service主要负责三件事接口路由、协议适配、入口安全。接口路由上我会给所有对外接口一个统一前缀比如/open/api/v1版本号从 v1 开始后续不兼容更新再升 v2。很多项目一上来就想“以后兼容”结果 v1 还没稳定就开始写 v2最后变成没人维护的死代码。协议适配是容易被忽略的点。对外接口返回给第三方的 DTO一定不要直接复用餐户体系里的内部实体而是用xxx-api-contract里专门定义的 DTO通过 MapStruct 做转换。内部实体字段改名不影响外部契约外部新增字段也不会污染内部逻辑。入口安全上至少要实现三层第一层是全局的签名校验 Filter校验 appId、timestamp、nonce、sign第二层是对敏感接口的 Token 鉴权第三层是接口级限流。这一层不应该散落到 Controller 里写重复代码而是用拦截器或 Filter 统一处理让业务开发只关注业务。3.3 管理平台 xxx-admin-service 的建模重点xxx_admin_service的核心不是接口设计而是权限模型。企业级管理后台最常见的需求是不同角色看到不同菜单、操作不同按钮、查询不同数据范围。我在规划这个模块时把权限拆成三个维度菜单权限能看见什么、操作权限能点哪个按钮、数据权限能查哪些行的数据。前两个通常基于 RBAC 模型用角色绑定菜单和按钮标识实现数据权限则在持久层拦截比如部门经理只能看本部门数据集团管理员可以看全量数据。管理端的接口风格可以比对外 API 更贴近内部系统习惯分页查询直接返回 PageResult导出文件返回二进制流操作成功返回简洁 message。但操作审计不能含糊必须记录操作人、操作时间、请求参数、操作结果、IP。这些审计日志在对外服务里属于可选在管理服务里是刚需。3.4 xxx-common 里到底该放什么、不该放什么xxx-common是个很容易失控的模块。我见过有人把业务常量、数据库字段枚举、甚至某个服务的 FeignClient 全塞进 common最后 common 变成一个巨大的垃圾堆每次改一个常量都要发一版 common。我的原则很简单common 里只放“和技术栈相关、和具体业务无关”的通用能力。具体包括统一响应体 Result、分页 PageResult业务异常 BizException、错误码枚举接口通用工具类JSON、日期、脱敏工具全局 TraceId 过滤器统一跨域配置如果有的话通用抽象类比如 BaseEntity、BaseQuery。不该放的东西任何数据库实体、任何 Mapper、任何和 xxx 公司业务强关联的常量、任何第三方 SDK 的封装。这些要么放进repository要么放进system要么放进api-contract。判断标准一句话如果删掉 common 里的类公司业务是否仍然成立成立就说明它足够通用不成立就说明它放错了地方。4. 企业级规范拆开讲统一响应、全局异常与日志链路4.1 统一响应体的泛型陷阱与文件下载例外“统一返回格式”是企业级开发规范里被喊得最多的口号但落地时最容易翻车的是泛型。我们通常定义ResultTController 直接返回它Spring 序列化时因为泛型擦除运行时拿着的是Result对象里面 data 字段的真实类型由getData()的实际对象决定。单条对象还好但一旦 data 是ListUser如果接口里还把类型写成了ResultListUser大部分框架能正确处理因为你没有手动 new 泛型对象。真正出问题的是有些同学在代码里用new ResultJSONObject()来组装返回或者通过泛型反射工具去解析这时候就容易丢类型导致第三方文档里看到的 schema 是{}而不是具体的对象结构。我的建议Controller 层直接返回强类型的ResultT不要返回ResultObjectJavaDoc 和 OpenAPI 注解里明确标注 data 结构。如果用的是 springdoc可以配合Schema(implementation UserDTO.class)把类型信息补全这样对外生成的 API 文档才不会出现一层套一层的泛型缩写。文件下载和导出是另一个例外。下载接口千万不要用Resultbyte[]包裹因为一旦包装后浏览器收到的就不是文件流了。这类接口直接返回ResponseEntitybyte[]或void用 HttpServletResponse 写流并且在 SpringDoc 里也单独配置不能混在统一返回那一类。4.2 全局异常处理的三个层级全局异常处理器不是写一个RestControllerAdvice加上ExceptionHandler(Exception.class)就完事。我在项目里按三个层级设计底层是“参数校验异常”比如MethodArgumentNotValidException、ConstraintViolationException这类异常要返回 400并且要把字段名和错误信息对应起来给前端一个结构化错误对象方便直接在表单上标红。第二层是“业务异常”也就是我们主动 throw 的BizException返回 200 的业务错误码或者你自己约定的 HTTP 状态码错误信息要能被前端弹窗或页面友好显示。第三层是兜底的Exception此时返回 500日志里记完整堆栈但返回给调用方的 message 只能是“系统繁忙请稍后重试”不能在响应里吐 SQL 错误、NPE 堆栈这些内部信息。我特别强调一点对外 API 服务和管理端服务的异常信息策略要不同。对外 API 的 message 越模糊越安全管理端可以略微多透露一点线索方便运营排查。因此RestControllerAdvice最好不要直接写在 common 里让两个服务共用同一个行为而是分别在 api_service 和 admin_service 里定义各自的 Advicecommon 里只放BizException和错误码接口。4.3 MDC 链路追踪与日志脱敏分布式链路追踪在企业级项目里不是可选项。没有 traceId排查一个跨服务调用的超时问题你能翻日志翻到怀疑人生。我在工程里的做法是写一个 OncePerRequestFilter在每个请求进来时生成traceIdUUID 或者雪花 ID写入 SLF4J MDC如果调用方在 Header 里带了X-Request-Id则优先复用方便第三方把他们的请求 ID 和我们日志对齐。Response 头里也回写这个 traceId。日志 pattern 统一加上[%X{traceId}]这样无论请求打到 api_service 还是 admin_service只要 traceId 相同就能用一条命令把整条调用链捞出来。MDC 用起来有个隐形坑子线程、异步线程池不会自动继承父线程的 MDC。如果你在业务里用了Async或线程池要在任务提交时手动把 traceId 传入子线程任务结束再移除。或者直接封装一个线程池工具类提交任务时自动装饰 Runnable。日志脱敏也不能落下。统一对手机号、身份证、银行卡号等字段做脱敏打印。最简单的办法是在日志方法或工具类里统一加脱敏处理更严谨的可以自定义 Logback 的MessageConverter不过成本稍高。我建议从源头规范实体转日志 DTO 时就不要打印明文敏感字段输出到日志的 JSON 里脱敏后再记。4.4 参数校验别只靠 Valid 撑场面Spring Boot 的Valid/Validated只能解决“字段级格式校验”它解决不了“业务规则校验”。比如注册接口要校验手机号是否已被占用、转账接口要校验余额是否足够、订单状态流转要校验当前状态是否合法这些都必须放在 service 层。我一般习惯把校验拆成两段Controller 层做基础格式校验非空、长度、格式service 层做业务校验。业务校验失败时抛BizException不要返回 false 或者直接 next。这样责任边界清楚后续再加校验也不至于堆在 Controller 里。跨字段校验是个容易被忽略的坑。比如创建订单接口如果orderType1则sellerId必填如果orderType2则buyerId必填。这种逻辑用NotBlank写不出来要自定义一个类级别注解在isValid里拿到整个请求对象做校验。Spring Boot 3.x 里自定义校验注解的写法没变但要注意ConstraintValidator的初始化时序不能在里面依赖 Spring 容器注入除非你把它注册成 Spring Bean。5. api_service 与 admin_service 的差异化策略对照5.1 一张表看懂安全模型、令牌与审计的差别两个服务规划阶段最容易扯皮的就是“为什么 API 不沿用我们的管理后台登录态”。下面这张表我建议直接贴到团队文档里维度xxx_api_servicexxx_admin_service服务对象第三方、App、小程序内部运营、管理员认证方式AccessToken 签名账号密码/SSO 会话令牌有效期短 Token建议 2 小时左右会话或 JWT结合刷新机制权限粒度接口级权限按客户维度控制RBAC 菜单、按钮、数据权限审计要求核心写操作审计全量操作审计登录日志必留错误提示模糊化避免暴露内部信息相对友好可返回可读描述限流策略按客户/接口严格限流按账号/IP 限流阈值放宽网络策略可被网关/公网访问仅内网可访问部署方式多副本、弹性伸缩一般副本数固定或较少这张表最大的作用是告诉大家把 API 服务和管理端服务拆开不只是为了代码目录好看而是它们在网络安全、令牌策略、审计要求上完全走两条线。如果你只有一个服务这两套策略塞在一起迟早会因为“方便”而互相妥协最后两个需求都满足不好。5.2 对外接口的幂等、限流与签名设计对外接口设计里幂等是必须考虑的。第三方调用你的接口失败后一定有重试机制如果重试导致重复下单、重复扣款责任就在你。我常用的方案是幂等键机制调用方在 Header 里传Idempotency-Key服务端在 Redis 里以业务标识:接口路径:appId:幂等键为 key 缓存请求结果。第一次请求执行完写入 cache超时时间根据业务定比如订单创建 24 小时后续相同幂等键的请求直接返回第一次的结果不再执行业务。注意一定要用 Redis setnx 或者加锁保证并发下只有一个请求真正执行业务否则你会在压测时看到两个请求同时打到数据库。限流方面对外接口建议用 Redis Lua 实现令牌桶或滑动窗口。按 appId客户维度限流是最基本的一层比如某个客户 QPS 上限 50其次可以按接口维度限流比如某个核心接口全局 QPS 100。管理端接口也需要限流但主要防暴力破解和脚本刷接口阈值可以给得宽一些。签名设计也不要拍脑袋。标准做法是 appId timestamp nonce signsign 用商户私钥对请求参数做签名服务端验签后还要校验 timestamp 在可接受时间窗口内比如 5 分钟以及 nonce 未使用过这样能挡住大部分重放攻击。这块设计代码量不大但一定要放在公共框架层不要让每个业务接口自己验签。5.3 管理端的数据权限与操作审计如何落地管理端服务里最容易被业务同学做成“全表查询”的就是数据权限。比如销售只能看自己的客户、门店主管只能看本门店的数据。这个逻辑不能散落在每个 Service 里否则绝对会漏。我的习惯是基于 MyBatis-Plus 的DataPermissionInterceptor做统一处理在 SQL 执行前根据当前登录用户解析出可见的数据范围比如部门 ID 列表然后自动拼接dept_id IN (...)条件。这样业务代码里只需要关心业务逻辑不需要担心每个列表查询又忘了带数据权限条件。拦截器里要注意超级管理员角色放行避免误拦截子查询和多表关联要确定好哪张表的别名对应dept_id。操作审计最轻量的落地方式是用自定义注解AuditLog Spring AOP。注解上配置模块名称、操作类型、是否需要记录请求参数/响应结果切面在方法执行前记录开始时间执行后记录成功/失败、耗时、操作人、IP异步写入审计表或消息队列避免影响主流程。审计日志不要只在管理端服务里做但对管理端而言是强约束对 API 服务来说通常只需要在核心写操作上做。6. 周边模块与部署规划从数据库到流水线一次讲清6.1 数据库与 MyBatis-Plus/JPA 的规范选择选型时在 JPA 和 MyBatis-Plus 之间纠结很正常。我的建议如果你的团队对 SQL 控制力要求高、业务有大量复杂报表查询选 MyBatis-Plus如果主要是 CRUD 和领域模型驱动JPA 也可以但要做好懒加载和 N1 控制。在企业级项目里我更倾向于 MyBatis-Plus原因是它对多租户、乐观锁、逻辑删除、自动填充这些企业刚需支持得很齐全而且团队上手成本低。数据库规范这块建议直接在检查清单里锁死表名统一小写带下划线每张表必须有主键id用 bigint不要用 UUID 当主键索引性能和存储成本都不划算业务表统一带create_by、create_time、update_by、update_time、deleted五个审计字段用 MP 的自动填充统一维护删除一律逻辑删除不执行物理 DELETE表结构变化用 Flyway 或 Liquibase 管理不允许手工去生产库执行 DDL。另外要特别提醒api_service和admin_service可以连同一个业务数据库但数据库账号必须区分。API 服务只能连只读优先级高、不可 DDL 的账号管理端服务账号可以放宽但也不能有 DROP/TRUNCATE 权限。这样即使某个服务被拖库破坏范围也有限。6.2 Redis、配置中心集成时的模块归属Redis 在项目里承担的东西很多缓存、分布式锁、幂等键、限流计数器。这些工具类封装应该放进common还是单独模块我建议把基础的 Redis 操作、分布式锁、幂等模板封装在common因为它不包含业务但具体的缓存 key 设计、业务值对象序列化、缓存清理逻辑放在各自的服务模块里。配置中心方面如果你所在的基建已经有 Nacos建议引入spring-cloud-starter-alibaba-nacos-config注意版本要适配 Spring Boot 3.2.x 的 2023.0.x 系列。如果没有配置中心先用多环境 profile 也完全够撑到 10 个服务以内。引入配置中心不是目的目的是让配置变更不再需要重新发版但这同时也要求你把配置项的变更权限管好。6.3 多环境 profile 与配置中心的实际用法我在工程里默认建了五个 profilelocal、dev、qa、pre、prod。每个 profile 都有独立的application-{profile}.yml里面主要放各环境不同的数据源、Redis、日志级别、注册中心地址等。这里一个非常关键的规范任何环境下的数据库密码、Redis 密码、密钥都禁止写入仓库。本地开发用本地密码测试和生产环境的配置从环境变量或配置中心读取并在配置里用${DB_PASSWORD}占位。可以在项目里放一个.env.example或者application-local.yml模板但里面只写占位符和默认值。配置中心使用时有一点容易被忽视公共配置和业务配置要分开。Nacos 里有公共 group 和每个服务私有的 dataId不要把 api_service 和管理后台的差异化配置塞到同一个 dataId 里否则一个服务改配置会影响另一个违背了拆服务的一部分初衷。6.4 CI/CD 和容器化如何让规范真正被执行规范写得再好没有流水线约束就是空话。我在团队里最看重的一件事是把代码规范、测试、依赖检查全部挂到 CI 里合并请求不通过流水线就不允许合并。Maven 多模块项目建议至少执行四步mvn clean verify跑单元测试、spotbugs:check静态缺陷扫描、mvn dependency:analyze检查依赖、以及强制检查分支覆盖率如果加了 JaCoCo。这一步能提前拦掉很多“本地能跑上测试就挂”的问题。容器化方面Dockerfile 直接用openjdk:17-jdk-slim作为基础镜像配合 Spring Boot 3.2 官方支持的 layered jar 方式构建。具体是启用spring-boot-starter-parent提供的 layers 配置把依赖层、资源层、应用层分开这样后续发版时只要依赖没变Docker 构建能直接命中缓存层部署包体积和启动时间都会小很多。启动命令里记得加-XX:MaxRAMPercentage75.0这类参数让 JVM 在容器内存限制内自适应堆大小。7. 升级到 3.2.10 JDK 17 后我踩过的几个大坑7.1 jakarta 命名空间迁移导致的批量编译失败这个坑基本是每个从 Spring Boot 2 迁移到 3 的团队必踩。现象很典型项目编译报大量程序包javax.servlet不存在或者运行时抛ClassNotFoundException: javax.servlet.Filter。排查链路是这样的先看报错包名确认是javax而不是jakarta然后全局搜索import javax.servlet、import javax.persistence、import javax.validation接着去查第三方依赖很多老版本的commons-xxx、swagger、shiro都会引入旧包。解决办法分为两步第一步把代码里的javax.servlet.*改成jakarta.servlet.*javax.persistence.*改成jakarta.persistence.*javax.validation.*改成jakarta.validation.*第二步用mvn dependency:tree找哪些依赖传递引入了旧javax.servlet-api排除掉或者升级到兼容 Spring Boot 3 的版本。我在项目里就是被一个老旧的 Excel 导入工具给拖住了它内部用了javax.xml.bind最终只能换库解决。记住Spring Boot 3 下一切旧javax依赖都是隐患排查优先级很高。7.2 JDK 17 下 Lombok 与 MapStruct 注解处理器冲突如果你的项目里同时用了 Lombok 和 MapStruct在 JDK 17 下大概率遇到编译期错误MapStruct 生成的实现类里找不到 getter/setter 方法或者直接报“找不到符号 getUserName”。原因很简单MapStruct 在注解处理阶段需要读取源文件的 getter/setter而这些方法是由 Lombok 生成的。JDK 17 下注解处理器的执行顺序如果不对MapStruct 拿到的是还没有生成 getter/setter 的中间状态。解决方式不是把 Lombok 排除掉而是在maven-compiler-plugin里显式声明annotationProcessorPaths顺序是 Lombok 在前、MapStruct 在后plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId configuration annotationProcessorPaths path groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version1.18.30/version /path path groupIdorg.mapstruct/groupId artifactIdmapstruct-processor/artifactId version1.5.5.Final/version /path /annotationProcessorPaths /configuration /plugin如果你用 IntelliJ IDEA改了 POM 之后还要进 Settings 把Annotation Processing的“从 Maven 自动获取处理器路径”打开不然 IDE 里编译还是老行为容易产生“命令行能过IDE 报红”的诡异气氛。7.3 虚拟线程的诱惑JDK 17 上别急着开Spring Boot 3.2 的发行说明里高调支持了虚拟线程配置项也很简单spring.threads.virtual.enabledtrue。很多同学看到这个特性就激动想着一个开关把 Tomcat 的线程模型换成虚拟线程吞吐量翻倍。但这里有个前提你可能没注意虚拟线程是 JDK 21 正式转正的特性JDK 17 根本没有这个能力。项目技术栈锁定 OpenJDK 17 时哪怕你在配置里写spring.threads.virtual.enabledtrue实际也不会生效甚至某些自动配置会因为找不到虚拟线程相关类而抛出异常。换句话说如果想用虚拟线程要么升级 JDK 到 21要么老老实实用平台线程。不过对大多数业务系统来说瓶颈往往不在 Tomcat 线程数而在数据库连接池和下游服务时延。先把 SQL 慢查询、连接池配置、缓存命中率这些问题解决比追虚拟线程更有价值。7.4 上线前的版本验证清单标准化版本验证能避免很多低级事故。在我最终上线前会固定跑一组检查这里直接给你参考java -version确认是 OpenJDK 17mvn -v确认 Maven 3.9.xmvn clean package确认无编译错误且target/generated-sources里能看到 MapStruct 生成的代码mvn dependency:tree全量扫描确认已经没有javax.servlet-api、javax.validation-api等老依赖本地docker build一次通过镜像内java -version与实际环境一致启动时挨个检查openapi.json、actuator/health、核心接口冒烟测试。这套清单看起来简单但每次都能救我一命上次就是靠它发现测试环境里实际跑的是 JDK 11而流水线一直没报错。如果你现在正准备从单体直接切到这套 api_service admin_service 的结构我的建议是第一个迭代不要追求一步到位。先把xxx-common和xxx-api-contract建出来把两个启动器跑通然后迁第一个相对独立的业务模块进去。等这个流程顺了再逐步把新模块按同样的路径切进来。这样既不会让改造节奏失控也能让团队逐步体会分层的收益。这个过程里你肯定还会踩到一些奇怪的依赖问题这时候别硬刚先看依赖树再翻版本兼容性大多数坑最后都落在“你用了一个没有跟进 Spring Boot 3.x 的旧库”上。