Solon中@Mapping路径匹配失败的常见原因有哪些？

Question

Solon中`@Mapping`路径匹配失败的常见原因包括：1）路径拼写错误或大小写不一致（如`/user/list`误写为`/User/List`，而默认路由不忽略大小写）；2）未正确配置根路径前缀（如全局`solon.app.path`与控制器`@Controller("/api")`叠加导致实际路径为`/api/api/user`）；3）HTTP方法不匹配（如用`@Mapping("/user")`响应GET请求，但客户端发了POST，且未显式声明`method = HttpMethod.POST`）；4）路径参数或通配符使用不当（如`@Mapping("/user/{id}")`却访问`/user/123/`，末尾斜杠触发404）；5）类路径扫描失效——控制器未被`@Configuration`或`@Import`引入，或包未被`SolonApp.scanPackage()`覆盖；6）与其他注解冲突（如同时使用`@Mapping`和`@Get`，后者会覆盖前者）。建议开启`solon.debug=true`查看实际注册的路由表，快速定位问题。

Answer 1

```html

一、现象层：HTTP 404 响应的直观表征

当客户端发起请求（如 GET /user/list）却收到 404 Not Found 时，Solon 并未匹配到任何处理器。这不是业务逻辑错误，而是路由注册与请求路径之间存在“语义断层”。该现象是所有后续分析的起点，也是运维监控中最先捕获的信号。

二、语法层：路径字面量的精确性校验

• 大小写敏感性默认开启：Solon 路由引擎默认区分大小写，@Mapping("/user/list") 不匹配 /User/List；
• 末尾斜杠隐含语义差异：路径 /user/{id} 严格匹配 /user/123，但不匹配 /user/123/（后者被视作子路径）；
• 路径拼写零容错：多一个空格、少一个下划线、中英文标点混用（如中文引号）均导致匹配失败。

三、配置层：根路径前缀的叠加陷阱

全局配置与类级注解存在隐式串联关系：

配置项	值	控制器声明	实际生效路径
solon.app.path	/api	@Controller("/api")	/api/api/user ❌（重复前缀）
solon.app.path	/v1	@Controller("/user")	/v1/user ✅（推荐模式）

四、语义层：HTTP 方法契约的显式约定

@Mapping 是泛型占位符，**不绑定任何 HTTP 方法**。若仅写：

@Mapping("/user")
public Object createUser(){...}

则该方法仅响应 GET 请求（Solon 默认行为），而 POST/PUT/DELETE 将全部 405 Method Not Allowed。正确做法必须显式声明：

@Mapping(value = "/user", method = HttpMethod.POST)

或直接使用语义化注解：@Post("/user")、@Get("/user/{id}")。

五、架构层：组件生命周期与类路径扫描机制

Solon 的路由注册依赖于 Bean 生命周期初始化阶段的自动发现。常见失效场景包括：

1. 控制器类未位于 SolonApp.scanPackage("com.example") 指定包或其子包内；
2. 类上缺失 @Controller 或 @Configuration，且未通过 @Import(MyController.class) 显式引入；
3. 模块采用多 module 结构，但主应用未配置跨模块扫描（需 scanPackage("com.example.*") 或启用 solon.app.scanAll=true）。

六、工程层：注解组合冲突与优先级规则

Solon 注解存在明确的覆盖链：

graph LR
A[@Mapping] -->|被覆盖| B[@Get]
A -->|被覆盖| C[@Post]
B -->|可叠加| D[@Mapping(method=HttpMethod.GET)]
C -->|可叠加| D
style A fill:#ffebee,stroke:#f44336
style B fill:#e8f5e9,stroke:#4caf50

例如同时标注 @Mapping("/user") 和 @Get("/user") 时，@Get 完全接管该路径的 GET 处理逻辑，前者对 GET 无效——这并非 Bug，而是设计上的职责分离。

七、诊断层：动态路由表可视化与调试闭环

启用 solon.debug=true 后，启动日志将输出完整路由注册快照：

[ROUTER] GET  /api/user/{id}       → com.example.ctrl.UserController::getUser
[ROUTER] POST /api/user              → com.example.ctrl.UserController::createUser
[ROUTER] GET  /actuator/health     → org.noear.solon.boot.web.ActuatorHandler::health

该输出是唯一可信的事实源，可交叉验证配置、注解、包扫描是否协同一致。建议将其接入 ELK 或 Prometheus + Grafana 实现路由健康度可观测。

八、进阶实践：构建路由健壮性防护体系

• 在 CI 流程中集成 curl -I http://localhost:8080/actuator/routes 自动校验关键路径可达性；
• 定义 Lombok 风格的 @ApiPrefix("/v1") 元注解，统一管理版本前缀，规避硬编码叠加；
• 利用 Solon 的 RouteInterceptor 实现路径标准化（如自动移除末尾斜杠、强制小写重定向）；
• 为测试环境启用 solon.route.strict=false（开发友好），生产环境保持 strict=true 保障契约严谨性。

```