用途
本技能用于对现有 Spring Boot 应用进行分阶段升级。它通过迁移扫描器、Boot 4 / Modulith 2 / Testcontainers 2 参考指南，以及严格的迁移顺序来提供价值，避免一次性混合过多改动。
关键规则
- 绝不盲目迁移，先扫描代码库。
- 绝不一次性应用所有迁移，遵循分阶段升级。
- 除非用户要求更窄的目标，否则将 Spring Boot 4、Spring Modulith 2 和 Testcontainers 2 视为本技能的预期目标技术栈。Boot 4 的 Java 基线为 17；建议新编译目标使用 Java 25，但不要强制升级超出迁移实际所需。
- 每个阶段后验证，出现失败即停止。
工作流程
第 1 步：扫描项目
在规划或编辑之前使用迁移扫描器。它读取 pom.xml、build.gradle 或 build.gradle.kts（项目实际使用的那个），以及 Java 源码、properties 文件和 Flyway 迁移：
python3 "${CLAUDE_SKILL_DIR}/scripts/scan_migration_issues.py" /path/to/project
使用扫描输出识别：
- 当前 Spring Boot 版本
- starter 重命名工作
- 注解和导入迁移
- 配置变更
- Spring Modulith 兼容性
- Testcontainers 兼容性
第 2 步：确定适用的迁移
只加载与代码库匹配的参考：
| 迁移 | 触发条件 | 读取 |
|---|---|---|
| Spring Boot 4.0 | Boot 3.x 升级到 4.x | references/spring-boot-4-migration.md |
| Spring Modulith 2.0 | 现有 Modulith 1.x 使用 | references/spring-modulith-2-migration.md |
| Testcontainers 2.x | 现有 Testcontainers 1.x 使用 | references/testcontainers-2-migration.md |
| 跨领域场景与陷阱 | 混合升级规划 | references/migration-overview.md |
第 3 步：分阶段规划迁移
使用参考指南按以下顺序规划和执行。
阶段 1：依赖
- 更新 pom.xml 或 build.gradle
- 在需要时重命名 starter
- 添加或移除目标技术栈所需的依赖
- 对齐版本属性
阶段 2：源码变更
- 更新导入和包名
- 迁移测试注解
- 修复 Jackson 3 问题
- 在相关处修复 Testcontainers API 变更
阶段 3：配置
- 更新 application.properties 或 application.yml
- 有意识地应用 Boot 4 默认值
- 在相关时更新 Spring Modulith 事件存储配置
阶段 4：验证
- 运行单元测试
- 运行集成测试
- 在存在时运行基于容器的测试
- 检查弃用和启动失败
第 4 步：混合升级使用正确的迁移顺序
当涉及多个生态时，使用此顺序：
- Spring Boot 4
- Spring Modulith 2
- Testcontainers 2
在偏离此顺序之前阅读 references/migration-overview.md。
第 5 步：每个阶段后报告进度
每个阶段后报告：
- 变更了什么
- 还剩什么
- 如果有，什么失败了
- 是否可以安全继续
参考加载指南
- Spring Boot 4 迁移详情：references/spring-boot-4-migration.md
- Spring Modulith 2 迁移详情：references/spring-modulith-2-migration.md
- Testcontainers 2 迁移详情：references/testcontainers-2-migration.md
- 混合场景与常见问题：references/migration-overview.md
可用脚本
scripts/scan_migration_issues.py
输出格式
在规划或报告迁移时，返回：
## Migration scope
- Current versions:
- Target versions:
## Planned phases
1. ...
2. ...
3. ...
## Files expected to change
- `path/to/file`
## Verification
- Tests or checks to run
何时不使用本技能
- 从零创建新的 Spring Boot 项目
- 没有实际迁移任务的宽泛架构建议
- 属于 spring-data-jpa 的 JPA 特定实现工作