springboot-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spring Boot Migration

Spring Boot 迁移

Critical Rules

关键规则

NEVER migrate blindly. ALWAYS scan the codebase first to understand the current state.

NEVER apply all migrations at once. ALWAYS follow the phased approach.

MANDATORY versions: Java 25 + Spring Boot 4.0.x + Spring Modulith 2.0.x + Testcontainers 2.x

绝对不要盲目迁移。务必先扫描代码库以了解当前状态。

绝对不要一次性完成所有迁移。务必遵循分阶段迁移方案。

强制要求版本： Java 25 + Spring Boot 4.0.x + Spring Modulith 2.0.x + Testcontainers 2.x

Workflow

工作流程

Step 1: Scan Project

步骤1：扫描项目

Use the migration scanner to identify what needs to be migrated:

bash

undefined

使用迁移扫描工具识别需要迁移的内容：

bash

undefined

Run from the skill directory

从skill目录运行

python3 <SKILL_DIR>/scripts/scan_migration_issues.py /path/to/project

Or if the skill is in .codex:

如果skill位于.codex目录下：

python3 .codex/springboot-migration/scripts/scan_migration_issues.py /path/to/project


**Note:** Replace `<SKILL_DIR>` with the actual path to this skill directory. When copying skills to `.codex/`, use the second form.

This will analyze:
- Spring Boot version and required changes
- Dependency issues (starter renames, version updates)
- Code issues (annotation changes, package relocations)
- Configuration issues (property renames, new defaults)
- Spring Modulith compatibility
- Testcontainers compatibility

python3 .codex/springboot-migration/scripts/scan_migration_issues.py /path/to/project


**注意：** 将`<SKILL_DIR>`替换为该skill目录的实际路径。当将skill复制到`.codex/`目录时，请使用第二种命令形式。

该工具将分析以下内容：
- Spring Boot版本及所需变更
- 依赖问题（starter重命名、版本更新）
- 代码问题（注解变更、包路径迁移）
- 配置问题（属性重命名、新默认值）
- Spring Modulith兼容性
- Testcontainers兼容性

Step 2: Assess Migration Scope

步骤2：评估迁移范围

Based on scan results, determine which migrations apply:

Migration	Trigger	Reference
Spring Boot 4.0	Any Spring Boot 3.x → 4.0 upgrade	`references/spring-boot-4-migration.md`
Spring Modulith 2.0	Using Spring Modulith 1.x	`references/spring-modulith-2-migration.md`
Testcontainers 2.x	Using Testcontainers 1.x	`references/testcontainers-2-migration.md`

Decision tree:

Is project using Spring Boot 3.x?
├─ Yes → Spring Boot 4.0 migration required
│   ├─ Using Spring Modulith? → Also migrate Spring Modulith 2.0
│   ├─ Using Testcontainers? → Also migrate Testcontainers 2.x
│   └─ Read: references/spring-boot-4-migration.md
└─ No → Check individual component versions

根据扫描结果，确定需要执行的迁移项：

迁移项	触发条件	参考文档
Spring Boot 4.0	任何从Spring Boot 3.x升级到4.0的场景	`references/spring-boot-4-migration.md`
Spring Modulith 2.0	当前使用Spring Modulith 1.x	`references/spring-modulith-2-migration.md`
Testcontainers 2.x	当前使用Testcontainers 1.x	`references/testcontainers-2-migration.md`

决策树：

项目是否使用Spring Boot 3.x？
├─ 是 → 需要迁移至Spring Boot 4.0
│   ├─ 是否使用Spring Modulith？ → 同时迁移至Spring Modulith 2.0
│   ├─ 是否使用Testcontainers？ → 同时迁移至Testcontainers 2.x
│   └─ 参考文档：references/spring-boot-4-migration.md
└─ 否 → 检查各个组件的版本

Step 3: Plan Migration Phases

步骤3：规划迁移阶段

CRITICAL: Migrations must be done in phases to ensure stability:

For scenario-specific guidance and common pitfalls, see

references/migration-overview.md

before planning.

关键提示： 必须分阶段进行迁移，以确保稳定性：

在规划前，请查看

references/migration-overview.md

获取场景化指导和常见问题说明。

Phase 1: Dependencies (Safe)

阶段1：依赖变更（安全可控）

Update
```
pom.xml
```
/
```
build.gradle
```
Rename starters (web→webmvc, aop→aspectj, etc.)
Add missing dependencies (Spring Retry, etc.)
Update version numbers

Reference: Each migration guide's "Dependency Changes" section

更新
```
pom.xml
```
/
```
build.gradle
```
重命名starter（web→webmvc、aop→aspectj等）
添加缺失的依赖（如Spring Retry）
更新版本号

参考： 各迁移指南中的“Dependency Changes”章节

Phase 2: Code Changes (Breaking)

阶段2：代码变更（可能存在破坏性）

Update imports and package relocations
Migrate test annotations (@MockBean→@MockitoBean)
Fix Jackson 3 usage (if applicable)
Update Testcontainers imports (if applicable)

Reference: Each migration guide's "Code Changes" section

更新导入语句和包路径
迁移测试注解（@MockBean→@MockitoBean）
修复Jackson 3的使用（如适用）
更新Testcontainers导入语句（如适用）

参考： 各迁移指南中的“Code Changes”章节

Phase 3: Configuration (Optional)

阶段3：配置变更（可选）

Update application.properties
Configure new Spring Boot 4 defaults
Add Spring Modulith event store config (if applicable)

Reference: Each migration guide's "Configuration Changes" section

更新application.properties
配置Spring Boot 4的新默认值
添加Spring Modulith事件存储配置（如适用）

参考： 各迁移指南中的“Configuration Changes”章节

Phase 4: Testing (Mandatory)

阶段4：测试验证（强制要求）

Run unit tests
Run integration tests
Verify container tests
Check for deprecation warnings

运行单元测试
运行集成测试
验证容器测试
检查废弃警告

Step 4: Execute Migration

步骤4：执行迁移

For each phase:

Read the relevant migration guide (don't skip this)
Apply changes to files identified in scan
Verify after each phase with tests
DO NOT continue if tests fail - fix issues first

Migration order for multi-component upgrades:

Spring Boot 4.0 first (base framework)
Spring Modulith 2.0 second (depends on Boot 4)
Testcontainers 2.x third (test infrastructure)

针对每个阶段：

阅读相关迁移指南（请勿跳过此步骤）
对扫描工具识别出的文件应用变更
每个阶段完成后通过测试验证
如果测试失败，请勿继续 - 先修复问题

多组件升级的迁移顺序：

首先升级Spring Boot 4.0（基础框架）
其次升级Spring Modulith 2.0（依赖于Boot 4）
最后升级Testcontainers 2.x（测试基础设施）

Step 5: Verification Checklist

步骤5：验证检查清单

After migration, follow the verification sections in the relevant references.

迁移完成后，请遵循相关参考文档中的验证章节进行检查。

Quick Reference

快速参考

When to Load References

何时加载参考文档

Spring Boot 4 issues →
```
references/spring-boot-4-migration.md
```

Spring Modulith 2 issues →

references/spring-modulith-2-migration.md

Testcontainers 2 issues →

references/testcontainers-2-migration.md

Scenarios, strategies, common issues →
```
references/migration-overview.md
```

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
```

Available Scripts

可用脚本

```
scripts/scan_migration_issues.py
```
- Analyzes project for migration issues

```
scripts/scan_migration_issues.py
```
- 分析项目中的迁移问题

Anti-Patterns

反模式

Don't	Do	Why
Migrate everything at once	Migrate in phases	Easier debugging
Skip scanning	Scan first	Know the scope
Ignore test failures	Fix immediately	Prevents cascading issues
Use classic starters permanently	Migrate to modular eventually	Technical debt
Suppress type errors with `@ts-ignore` equivalent	Fix root cause	Maintainability
Skip reading migration guides	Read before implementing	Avoid mistakes

不要做	应该做	原因
一次性完成所有迁移	分阶段迁移	便于调试
跳过扫描步骤	先执行扫描	明确迁移范围
忽略测试失败	立即修复问题	防止问题扩散
长期使用传统starter	最终迁移至模块化starter	避免技术债务
使用类似 `@ts-ignore` 的方式抑制类型错误	修复根本原因	保障可维护性
跳过阅读迁移指南	先阅读再实施	避免错误

Key Principle

核心原则

Understand before changing. Verify after changing. Never skip testing.

变更前先理解。变更后再验证。绝不跳过测试。