opensolon/soloncode/spring-to-solon-skill

Spring to Solon Migration Skill

为将 Spring Boot / Spring Cloud 项目迁移到 Solon 框架 提供专家指导。Solon 是独立的 Java 企业框架（不基于 Spring），开发体验相近，但注解、架构与生态不同。

官方对照: https://solon.noear.org/article/compare-springboot Cloud 对照: https://solon.noear.org/article/compare-springcloud 官网: https://solon.noear.org 当前版本: 4.0.3

版本声明：本文档所有示例基于 Solon 4.0.3（最后一次确认: 2026-07）。如需迁移到其他版本，请调整对应版本号。Solon 高版本保持向后兼容，通常仅需修改 solon-parent 版本号即可。reference 内写「跟随 SKILL 目标版本」时，以本节为准。

Critical Migration Rules

1. 意图闸门（优先于一切）：本 skill 仅在用户明确要求将 Spring 项目迁移到 Solon 时适用（明确表述：迁移 / Spring转Solon / 替换 starter / 去 Spring 依赖等，或明确要求换框架）。用户未明确要求时：保持项目现有框架（Spring），禁止修改 pom 依赖、启动类、配置文件名与注解体系；不要把「项目里存在 Spring 依赖」当作迁移请求；意图不明确时先询问，不得动手。其他规则均以此条为前提。
2. Solon 不是 Spring。 禁止混用 Spring 注解与 Solon 注解。替换全部 Spring import。（仅在 Rule 0 确认后执行）
3. 禁止 Spring 依赖。 移除所有 spring-boot-starter-*、spring-*。Solon 使用 org.noear groupId。（仅在 Rule 0 确认后执行；未确认前任何 Spring 依赖都不是“待清理项”）
4. 配置文件是 app.yml（或 app.properties），不是 application.yml。
5. 入口是 Solon.start(App.class, args)，不是 SpringApplication.run()。
6. Parent POM 是 solon-parent（groupId=org.noear）。
7. 包扫描在主类用 @Import / 主类包路径，不是 @ComponentScan。
8. 无 setter 注入。 Solon 只支持字段注入与构造器注入；构造器参数必须显式 @Inject。
9. 组件用 `@Component`，不要用 @Service / @Repository。
10. 所有示例目标 Solon 4.0.x（默认 4.0.3），除非用户指定其它版本。
11. 中文支持。 用户使用中文时，回复与代码注释使用中文。
12. 不确定的 API 不要臆造。 对照本 skill reference；Solon 原生细节查 solon-development-skill。
13. 校验坐标 为 `solon-security-validation`（不是 solon-validation）。类级启用 @Valid，实体参数/字段用 @Validated。
14. 调度选型：单机 → @Scheduled（scheduling_migration.md）；分布式防重 → @CloudJob（cloud_observability_migration.md）。勿一律替换。

与 solon-development-skill 的边界

执行流程

1. 确认迁移意图（Step 0，必须最先做）：仅当用户明确要求迁移时才进入本流程；若意图不明（如只是提到 Spring、依赖报错、想优化性能），先向用户确认，未确认前禁止改动 pom / 启动类 / 配置文件。本项目确属 Spring 且用户要继续用 → 不适用本 skill，直接按 Spring 方式干活。
2. 扫项目：父 POM、starter 列表、配置文件名、启动类、测试入口、是否有 Security / Validation / Scheduling / Cloud。
3. 按 Checklist Step 1→12 推进；每步只 read 1～2 个 reference，避免一次加载全部。
4. 生成代码前核对 Critical Migration Rules（尤其：app.yml、无 Spring 混用、@Component/@Inject、校验坐标）。
5. 数据层优先 datasource_orm_migration.md（含 solon.dataSources、SqlUtils、@Db）。
6. 安全优先 security_migration.md（不要复刻完整 Spring Security 过滤器链）。
7. 校验优先 validation_migration.md（与 web_advanced 摘要冲突时以 validation 文为准）。
8. 迁移完成后的 Solon 深化（AI/Flow/进阶 API）交给 solon-development-skill。

Migration Scene Navigation

根据迁移场景读取对应 reference。大表加载策略：

- annotation_mapping.md：优先 §12 完整速查表 或目录中的单节；长 Before/After 去各 *_migration.md。

- dependency_mapping.md：优先 §3 速查表 + §1/§2；仅抄 POM 时读 §5。

- 数据层：datasource_orm（源/ORM 权威）与 transaction_cache（事务/缓存/Redis）职责已拆分，勿混读后互相覆盖。

快速对照

IoC / AOP / 配置

Web 层迁移

数据访问迁移

安全迁移

定时任务迁移

微服务迁移

测试迁移

Quick Migration Checklist

本 Checklist 仅在 Rule 0 / Step 0 确认用户明确要求迁移后执行；否则任何一步都不应发生。

Step 1: POM 改造

• Replace spring-boot-starter-parent → solon-parent（4.0.3）
• Replace Spring starters → Solon plugins
• Add solon-maven-plugin
• See: references/dependency_mapping.md

Step 2: 配置文件

• Rename application.yml / bootstrap.yml → `app.yml`（合并为单文件）
• Adjust configuration key names
• See: references/config_system_migration.md

Step 3: 启动类

• Replace @SpringBootApplication → @SolonMain
• Replace SpringApplication.run() → Solon.start()
• See: references/annotation_mapping.md

Step 4: 注解与 IoC

• Replace all Spring annotations with Solon equivalents
• See: references/annotation_mapping.md, references/ioc_aop_migration.md

Step 5: Web 层改造

• Replace @RestController → @Controller
• Replace @RequestMapping → @Mapping
• Handle HttpServletRequest/Response → Context
• Filter / 全局异常 / CORS 见 web_filter_interceptor_migration.md
• 上传 / SSE / WebSocket / 会话见 web_advanced_migration.md
• See: references/web_controller_migration.md

Step 6: 参数校验（如适用）

• spring-boot-starter-validation → `solon-security-validation`
• 类级 @Valid；实体参数 @Validated；异常 ValidatorException
• See: references/validation_migration.md

Step 7: 数据层改造

• spring.datasource → `solon.dataSources`（jdbcUrl；一般无需手写 DataSource @Bean）
• JdbcTemplate → SqlUtils；Mapper 用 @Db
• 事务 / 缓存 / Redis：transaction_cache_migration.md（与 ORM 文边界分离）
• See: references/datasource_orm_migration.md

Step 8: 安全改造（如适用）

• Remove Spring Security；用 AuthAdapter + AuthProcessor
• See: references/security_migration.md

Step 9: 定时任务（如适用）

• 单机：@Scheduled → org.noear.solon.scheduling.annotation.Scheduled + solon-scheduling-simple（或 quartz）
• 分布式：才考虑 @CloudJob（见 Step 10 / observability）
• See: references/scheduling_migration.md

Step 10: 微服务改造（如适用）

• 注册发现 / 配置：cloud_discovery_config_migration.md
• RPC / 网关 / 事件：cloud_gateway_rpc_migration.md
• 断路器 / 分布式任务 / 链路 / 锁：cloud_observability_migration.md
• Replace Spring Cloud components with Solon Cloud plugins（如 nacos-solon-cloud-plugin）

Step 11: 测试改造

• Replace @SpringBootTest → @SolonTest（禁止测试里混用 Spring 注解）
• See: references/test_basics_migration.md；进阶见 test_advanced_migration.md

Step 12: 收尾核对

• 全库无 org.springframework import / starter
• 配置仅为 app.yml（或 app.properties）
• 校验 / 安全 / 调度依赖坐标与 Critical Rules 一致
• 有需要时再读 solon-development-skill 补原生能力

明确不覆盖（避免硬编）

以下无完整一对一迁移手册，遇到时说明边界并查官网 / 开发 skill，不要臆造 API：

• Spring Batch / Spring Integration 全量编排
• Spring GraphQL / Spring AI / Spring Session 集群方案细节
• 完整 OAuth2 Authorization Server 产品级复刻
• 与业务强绑定的自研 Spring Boot Starter