spring-to-solon-skill

name

spring-to-solon-skill

description

Expert guidance for migrating Java projects from Spring Boot / Spring Cloud to the Solon framework. Provides annotation mapping, dependency replacement, architecture differences, and step-by-step migration for IoC, Web, Data, Security, Scheduling, Validation, Cloud, and Testing. Use when migrating Spring Boot/Cloud projects to Solon, replacing Spring annotations/dependencies, rewriting application.yml → app.yml, Feign→Nami, @SpringBootTest→@SolonTest, Spring Security→solon-security-auth, validation→solon-security-validation, or when the user says 迁移/Spring转Solon/替换starter/去Spring依赖. Not for greenfield Solon apps (use solon-development-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. Solon 不是 Spring。 禁止混用 Spring 注解与 Solon 注解。替换全部 Spring import。
2. 禁止 Spring 依赖。 移除所有 spring-boot-starter-*、spring-*。Solon 使用 org.noear groupId。
3. 配置文件是 app.yml（或 app.properties），不是 application.yml。
4. 入口是 Solon.start(App.class, args)，不是 SpringApplication.run()。
5. Parent POM 是 solon-parent（groupId=org.noear）。
6. 包扫描在主类用 @Import / 主类包路径，不是 @ComponentScan。
7. 无 setter 注入。 Solon 只支持字段注入与构造器注入；构造器参数必须显式 @Inject。
8. 组件用 @Component，不要用 @Service / @Repository。
9. 所有示例目标 Solon 4.0.x（默认 4.0.3），除非用户指定其它版本。
10. 中文支持。 用户使用中文时，回复与代码注释使用中文。
11. 不确定的 API 不要臆造。 对照本 skill reference；Solon 原生细节查 solon-development-skill。
12. 校验坐标 为 solon-security-validation（不是 solon-validation）。类级启用 @Valid，实体参数/字段用 @Validated。
13. 调度选型：单机 → @Scheduled（scheduling_migration.md）；分布式防重 → @CloudJob（cloud_observability_migration.md）。勿一律替换。

与 solon-development-skill 的边界

场景	使用 skill
Spring → Solon 对照、替换、迁移步骤	本 skill
纯 Solon 新功能 / AI / Flow / 最佳实践	solon-development-skill
两边都提及时	先按本 skill 完成迁移对照，再链开发 skill 补原生写法

执行流程

1. 扫项目：父 POM、starter 列表、配置文件名、启动类、测试入口、是否有 Security / Validation / Scheduling / Cloud。
2. 按 Checklist Step 1→12 推进；每步只 read 1～2 个 reference，避免一次加载全部。
3. 生成代码前核对 Critical Migration Rules（尤其：app.yml、无 Spring 混用、@Component/@Inject、校验坐标）。
4. 数据层优先 datasource_orm_migration.md（含 solon.dataSources、SqlUtils、@Db）。
5. 安全优先 security_migration.md（不要复刻完整 Spring Security 过滤器链）。
6. 校验优先 validation_migration.md（与 web_advanced 摘要冲突时以 validation 文为准）。
7. 迁移完成后的 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）职责已拆分，勿混读后互相覆盖。

快速对照

Scenario	Reference File	Grep Keywords
注解替换对照表 / Spring→Solon 注解映射	references/annotation_mapping.md	@Autowired, @Inject, @RequestMapping, @Mapping, @Service, @Component, @Value
Maven 依赖替换 / starter → solon 插件 / POM	references/dependency_mapping.md	pom.xml, spring-boot-starter, solon-web, solon-lib, solon-parent

IoC / AOP / 配置

Scenario	Reference File	Grep Keywords
IoC / DI / 组件 / 作用域 / 生命周期 / AOP / 事件	references/ioc_aop_migration.md	@Inject, @Configuration, @Bean, LifecycleBean, @Init, @Destroy, @Aspect, EventBus
配置文件 / 属性注入 / 配置类 / 条件装配	references/config_system_migration.md	app.yml, @Inject("${"), @Configuration, @Bean, @Condition, solon.config

Web 层迁移

Scenario	Reference File	Grep Keywords
Controller / 请求参数 / 返回值 / Context	references/web_controller_migration.md	@Controller, @RestController, @Mapping, @Param, @Body, Context
Filter / Interceptor / 全局异常 / CORS	references/web_filter_interceptor_migration.md	Filter, RouterInterceptor, @ControllerAdvice, GlobalExceptionFilter, @CrossOrigin
上传下载 / SSE / WebSocket / 会话	references/web_advanced_migration.md	UploadedFile, SseEmitter, WebSocket, SessionState
参数校验 / 自定义校验 / 错误处理	references/validation_migration.md	@Valid, @Validated, @NotNull, ValidatorException, solon-security-validation

数据访问迁移

Scenario	Reference File	Grep Keywords
数据源 / SqlUtils / MyBatis / Plus / JPA / 多数据源	references/datasource_orm_migration.md	@Db, SqlUtils, solon.dataSources, jdbcUrl, MyBatis, JdbcTemplate
事务 / 缓存 / Redis	references/transaction_cache_migration.md	@Transaction, @Cache, Redis, @CacheRemove, CacheService

安全迁移

Scenario	Reference File	Grep Keywords
Spring Security → AuthAdapter / 路径鉴权 / 权限角色	references/security_migration.md	SecurityFilterChain, AuthAdapter, AuthProcessor, @AuthPermissions, @PreAuthorize

定时任务迁移

Scenario	Reference File	Grep Keywords
单机 @Scheduled / cron / fixedRate / Quartz	references/scheduling_migration.md	@Scheduled, cron, solon-scheduling-simple, solon-scheduling-quartz
分布式 任务（多实例防重）	references/cloud_observability_migration.md	@CloudJob, solon.cloud.job

微服务迁移

Scenario	Reference File	Grep Keywords
注册发现 / 配置中心	references/cloud_discovery_config_migration.md	Nacos, Eureka, CloudClient, @CloudConfig, nacos-solon-cloud-plugin
RPC (Feign→Nami) / 网关 / 事件消息	references/cloud_gateway_rpc_migration.md	Feign, NamiClient, CloudGateway, @CloudEvent, Gateway
断路器 / 分布式调度 / 链路 / 锁/ID/文件/监控	references/cloud_observability_migration.md	Breaker, @CloudJob, Trace, CloudLock, CloudId, Metric

测试迁移

Scenario	Reference File	Grep Keywords
依赖 / 测试类 / HTTP / Mock / 回滚	references/test_basics_migration.md	@SpringBootTest, @SolonTest, HttpTester, Mock, @TestRollback
切面 / 条件 / 生命周期 / 数据层 / 陷阱（接 basics）	references/test_advanced_migration.md	@Rollback, @SolonTest, @EnableAutoConfiguration

Quick Migration Checklist

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