migrate-spring-to-quarkus

Spring Boot 到 Quarkus 迁移

以模块化、门控驱动的方式将 Spring Boot 应用迁移到 Quarkus。

关键规则

• 绝不删除无法迁移的代码。 如果无法完整迁移某段代码，请保留原代码，并添加 // TODO: Migration required — <reason> 注释，说明需要更改什么以及原因。此规则适用于：
  • 不知道如何转换的方法、类或注解
  • 没有明确 Quarkus 对应项的 Spring 专属模式
  • 用途不明确的配置或装配代码 如果必须删除代码（例如，仅适用于 Spring 的基类），请在同一位置使用 // REMOVED: 注释说明删除了什么以及原因。
• 不要破坏构建。 每个阶段完成后，都要在 <target> 中运行编译命令（Maven 使用 cd <target> && ./mvnw clean compile -DskipTests，Gradle 使用 cd <target> && ./gradlew clean compileJava -x test）。构建失败时，绝不要进入下一阶段。
• 源代码只读。 绝不要修改 <source> 中的文件。所有更改都写入 <target>。唯一例外是 <source>/migration-metadata/，可以在其中写入提取元数据。
• 记录每项决策。 在选择迁移方案时，向用户说明权衡取舍。
• 不做无声更改。 每项文件修改都必须有意为之且可追溯。如果某个阶段完成后检查失败，请诊断并修复，不要跳过检查或删除失败的代码。

参考文件

在处理模块时，加载相关参考文件：

参考资料	使用时机
references/dependency-map.md	构建模块：依赖项和插件映射
references/annotation-map.md	代码模块：注解、DI、REST、Data、安全迁移
references/config-map.md	构建模块：配置属性迁移

步骤 1：执行模块

说明

• 根据以下决策门表执行各模块的说明
• 始终按照以下格式记录评估的模块、门控检查及其状态： Gate result: and <CONDITION_EVALUATED>

决策门表

• 检查 <source>，评估每个模块是否适用。只有门状态为：PASS 时，模块才会执行。
• 检查 <source> 以确定门检查结果——不要依赖盲目运行 grep 命令；请运用你对代码库的理解。

模块	门检查	门结果
prerequisite	JDK 版本、构建工具（建议使用 Maven ≥ 3.6，推荐 3.9+ / 建议使用 Gradle ≥ 7，推荐 8.x）、容器运行时	ALWAYS — ABORT 整个迁移（如果任何硬性检查失败）；不运行后续模块
planning	前置条件检查通过	ALWAYS — 生成 <target>/migration-spec.yaml
build	pom.xml 中的 Spring Boot parent/starters/spring-boot-maven-plugin，或 build.gradle(.kts) 中的 Spring Boot/io.spring.dependency-management 插件	PASS（如果发现 Spring Boot 构建标记）；否则 SKIP
code	Java 源码中的 Spring 注解（@Component、@Service、@Controller、@Repository、@Entity、@Autowired 等）	PASS（如果发现 Spring 注解）；否则 SKIP
messaging	Java 源码中的 @KafkaListener、@RabbitListener、@JmsListener、@SendTo、@EnableKafka、@EnableRabbit、KafkaTemplate、RabbitTemplate 或 JmsTemplate	PASS（如果发现任意一项）；否则 SKIP
frontend	templates/ 或 webapp/ 中的 Thymeleaf/JSP 模板、static/ 中的静态资源、webapp/ 或 META-INF/resources/ 中的 JSF XHTML 文件、FreeMarker 模板（.ftl、.ftlh、.ftlx）、freemarker.* 导入，或 FreeMarkerConfigurer Bean	PASS（如果发现视图层）；否则 SKIP
testing	测试源码中的 Spring 测试注解（@SpringBootTest、@WebMvcTest、@MockBean）	PASS（如果发现 Spring 测试）；否则 SKIP
cleanup	其他所有模块执行完毕后残留的 Spring 工件	ALWAYS -- 在其他所有模块执行完毕后运行

执行协议

STEP 0 — PREREQUISITE GATE (mandatory, runs before everything else)
  1. LOAD modules/prerequisite/prerequisite.md and execute all checks
  2. IF prerequisite gate == FAIL
       → log "Migration aborted — prerequisite gate failed: <failing check(s)>"
       → STOP immediately. Do not evaluate or execute any further module.
  3. IF prerequisite gate == PASS (warnings are allowed)
       → log "Prerequisite gate: PASS — proceeding with migration"
       → continue to the module loop below

FOR module IN [planning, build, code, messaging, frontend, testing, cleanup]:

  1. EVALUATE — inspect <source> for the gate condition
  2. DECIDE
     IF gate == ALWAYS → proceed to step 3
     IF gate == PASS   → proceed to step 3
     IF gate == SKIP   → log "Module {name}: SKIPPED — {reason}", mark checkbox, continue
  3. LOAD — read the module file and relevant reference files
  4. EXECUTE — read from <source>, write to <target>. Follow the module instructions, adapting to the chosen strategy
  5. COMPILE — run the compile command in <target> (`cd <target> && ./mvnw clean compile -DskipTests` for Maven, `cd <target> && ./gradlew clean compileJava -x test` for Gradle)
     Fails → load [modules/compile-fix.md](modules/compile-fix.md) and follow the retry procedure.
             If compile-fix reports MANUAL_REVIEW_REQUIRED (unresolved errors after 3 retries),
             ask the user whether to continue with the next module or stop the migration.
  6. LOG — mark checkbox as done

单独运行模块

若要在完整迁移流程之外运行单个模块，请直接读取模块文件夹中的所有文件：

• “读取 modules/build/build.md 并执行”
• “仅运行 frontend 模块”
• “重新运行 cleanup 模块”

模块将使用当前的 <source> 和 <target> 路径，以及已选定的策略（如果已选定）。如果尚未选择策略，模块会询问。

步骤 2：验证迁移

所有验证检查都针对 <target> 运行。按顺序运行每项检查。检查失败 = 停止并修复后再继续。

#	检查	命令（在 <target> 中运行）	通过标准
1	构建	cd <target> && ./mvnw clean package -DskipTests / cd <target> && ./gradlew clean build -x test	退出代码为 0，且无编译错误
2	无 Spring 依赖	在 <target> 的构建文件中搜索 org.springframework	不存在 Spring 依赖（若采用 Spring 兼容扩展策略，则例外）
3	包含 Quarkus	在 <target> 的构建文件中搜索 io.quarkus	存在 Quarkus BOM 和至少一个扩展
4	测试通过	cd <target> && ./mvnw test / cd <target> && ./gradlew test	所有测试均使用 @QuarkusTest 并通过
5	成功启动	cd <target> && ./mvnw quarkus:dev / cd <target> && ./gradlew quarkusDev	应用成功启动，curl http://localhost:8080/q/health 返回 UP
6	无遗留模板	在 <target> 中搜索 Thymeleaf/JSP 引用	不存在遗留引用（除非有意保留）

步骤 3：报告

验证完成后，运行报告模块。该模块会读取验证结果和所有模块的数据，并生成：

• <target>/migration-metadata/execution-metadata.json -- Agent、模型、令牌、成本、用时、验证结果
• <target>/migration-summary.md -- 包含完整 13 个章节的迁移报告

报告模块必须在验证之后运行，以便纳入检查结果并记录准确的 finished_at 时间戳。

控制台摘要

报告模块完成后，直接向用户展示以下内容，让他们无需打开生成的文件即可快速了解概况。

如实回答以下每个问题：

1. 哪些内容迁移顺利？ 能够一对一映射的模式。
2. 哪些内容需要人工判断？ 所做的非显而易见的决策。
3. 哪些内容留作 TODO？ 每一条 // TODO: Migration required 注释及其原因。
4. 是否移除了代码？ 移除了哪些代码、位于何处，以及移除理由。标明运行时风险。
5. 哪些检查最初未通过？ 验证过程中出现的失败，以及修复方式。
6. 技能参考中缺少什么？ 需要自行摸索的映射。

然后按结构化报告的形式展示：

## Migration Report: [app-name]

### Summary
- Source: [source directory path]
- Target: [target directory path]
- Strategy: [Full Migration / Spring Compatibility]
- Agent: [AI agent name - e.g claude, pi, opencode, gemini, etc]
- Model: [model name — e.g. claude-sonnet-4-6, check system context]
- Modules completed: [X/8]
- Checks passed: [X/6]
- Token usage: [input tokens / output tokens — check session stats]
- Estimated cost: [~$X.XX — token counts × per-model pricing from anthropic.com/pricing]

### Changes by Module
| Module | Files changed | Key changes |
|--------|--------------|-------------|
| build | pom.xml or build.gradle(.kts), application.properties | ... |
| code | ... | ... |
| frontend | ... | ... |
| testing | ... | ... |

### Validation Results
| Check | Result | Notes |
|-------|--------|-------|
| Builds | PASS/FAIL | |
| No Spring deps | PASS/FAIL | |
| Has Quarkus | PASS/FAIL | |
| Tests pass | PASS/FAIL | |
| Starts up | PASS/FAIL | |
| No leftover templates | PASS/FAIL | |

### Unmigrated Code (TODOs)
| File | Line | What | Why not migrated |
|------|------|------|-----------------|

### Removed Code
| File | What was removed | Justification |
|------|-----------------|---------------|

### Skill Improvement Suggestions
- [Any missing mappings, unclear instructions, or edge cases discovered]