# Petclinic 路由层实战：从注解到 RequestMappingInfo 源码排障

```text
旧方案：只背注解，靠猜映射
冲突：需求一变，路由打架
后果：404、405、415 满天飞，排障靠玄学
```

我是老李，在深圳南山科技园的一家宠物医疗 SaaS 公司做架构师。团队最近接手了 Spring Petclinic 的 Owner/Pet 模块，要给宠物医院做一个对外开放的 REST API。

需求很简单：能按 ID 查主人、能新增宠物、能按名字搜主人。但联调第一天，前端就报了一堆 404 和 405。

为什么注解写对了，请求还是进不了 Controller？

当 URL 相同但 HTTP Method 不同时，Spring 到底怎么决定谁处理？

如果选错了路由匹配规则，会不会出现线上接口悄悄打到错误方法上的事故？

# 01、故事

```text
周二 09:40 → 南山科技园 → 交付 Owner/Pet API → 路由冲突
```

周二早上九点四十，我坐在南山科技园的工位上，任务是今天下班前把 Owner 和 Pet 的查询、新增接口联调通过。

前端同事小陈在群里催：“李哥，GET /owners/1 返回 404，POST /owners/1/pets 返回 405，到底哪个注解写错了？”

我打开代码一看，Controller 类上写了 @RequestMapping("/owners")，方法上写了 @GetMapping("/{ownerId}") 和 @PostMapping("/

{ownerId}/pets")，看起来没毛病。

但启动日志里，RequestMappingHandlerMapping 的映射表里就是找不到我预期的组合。

> 晨会催交付，路由先迷路
> 注解都认识，请求偏不认
> 源码藏答案，莫再背口诀
> 映射如棋局，一步定乾坤

# 02、问题

```text
需求变化：查单个主人 → 新增宠物 → 按名字搜索
冲突：路径模板相似，方法签名不同
后果：404、405、415 交替出现
```

第一个接口 GET /owners/{ownerId} 本来能通，但加上 POST /owners/{ownerId}/pets 后，前端说 POST 有时 405，有时 415。

我怀疑是路径变量和请求体解析冲突，但日志里没有异常堆栈，只有一句 “No mapping for POST /owners/1/pets”。

这说明请求根本没进 Controller，而是在路由匹配阶段就被拦下了。

可验证的验收标准是：GET /owners/1 返回 200 JSON，POST /owners/1/pets 带 JSON 请求体返回 201，GET /owners?

lastName=Smith 返回 200 列表。

> 路径像迷宫，方法像暗号
> 请求到门口，门内无人应
> 不是代码错，是路由没懂
> 排障先看表，莫怪注解少

# 03、原理

```text
启动扫描 → RequestMappingHandlerMapping → RequestMappingInfo → HandlerMethod
```

Spring MVC 启动时，RequestMappingHandlerMapping 会扫描所有 @Controller 和 @RestController Bean，把每个带 @RequestMa

pping 的方法包装成 HandlerMethod。

每个 HandlerMethod 对应一个 RequestMappingInfo，里面存了路径模式、HTTP Method、请求头、Consumes、Produces 等匹配条件。

运行时，DispatcherServlet 把请求交给 RequestMappingHandlerMapping，它会遍历所有 RequestMappingInfo，按路径、Method、Header

、Content-Type 依次匹配。

反直觉的是：路径匹配不是精确字符串比较，而是 AntPathMatcher 模式匹配，所以 /owners/{ownerId} 和 /owners/search 可能同时存在，但 /owners/se

arch 会被优先精确匹配。

> 注解是声明，映射是注册
> 启动建好表，请求来查表
> 路径有模式，匹配有顺序
> 反直觉之处，精确胜模式

# 04、架构

```text
HTTP 请求 → DispatcherServlet → RequestMappingHandlerMapping → RequestMappingInfo 匹配 → HandlerMethod
```

路由层在 DispatcherServlet 和 Controller 之间，负责把 HTTP 请求翻译成一次 Java 方法调用。

它的边界很清楚：只做匹配，不做业务。

匹配成功就返回 HandlerExecutionChain，失败就抛 NoHandlerFoundException 或 HttpRequestMethodNotSupportedException。

收益是 Controller 可以专注业务，代价是路由规则必须提前想清楚，否则排障成本很高。

适用条件是所有基于注解的 Spring MVC 项目，不适用于 WebFlux 函数式路由。

> 路由是门卫，不是服务员
> 只认通行证，不碰业务单
> 规则提前定，排障少绕弯
> 注解 MVC 用，函数式另算

# 05、第一版实战

```text
环境 → 配置 → 代码 → 启动 → 验证 → V1
```

环境：Spring Boot 3.2.x（需按当前官方文档核验），JDK 17，Maven 3.9，依赖 spring-boot-starter-web。

先建 OwnerController：

```java
@RestController
@RequestMapping("/owners")
public class OwnerController {

    @GetMapping("/{ownerId}")
    public Owner getOwner(@PathVariable Long ownerId) {
        return new Owner(ownerId, "Smith");
    }

    @PostMapping("/{ownerId}/pets")
    public Pet addPet(@PathVariable Long ownerId, @RequestBody Pet pet) {
        pet.setOwnerId(ownerId);
        return pet;
    }

    @GetMapping
    public List<Owner> searchOwners(@RequestParam String lastName) {
        return List.of(new Owner(1L, lastName));
    }
}
```

启动应用：

```bash
mvn spring-boot:run
```

验证请求：

```bash
curl -v http://localhost:8080/owners/1
curl -v -X POST http://localhost:8080/owners/1/pets -H "Content-Type: application/json" -d '{"name":"Buddy"}'
curl -v "http://localhost:8080/owners?lastName=Smith"
```

预期结果：第一个返回 200 JSON，第二个返回 201 JSON，第三个返回 200 列表。

未在当前环境实测，以下为预期结果。

> 环境先搭好，依赖别少导
> 注解写清楚，启动看日志
> 请求发三条，结果各不同
> 成功标准明，才算第一版

# 06、排查

```text
诊断树：404 → 路径不匹配？405 → Method 不匹配？415 → Content-Type 不匹配？
```

问题一：POST /owners/1/pets 返回 405。

怀疑是 @PostMapping 没生效，检查启动日志：

```text
示例输出：
Mapped "{POST /owners/{ownerId}/pets}" onto public Pet OwnerController.addPet(Long, Pet)
```

日志显示映射存在，说明不是注解问题。再检查请求，发现前端发的是 PUT 而不是 POST。

根因是前端代码写错 Method，修复后 405 消失。

问题二：POST 返回 415。

怀疑是 Content-Type 不对，检查请求头：

```bash
curl -v -X POST http://localhost:8080/owners/1/pets -d '{"name":"Buddy"}'
```

发现没带 Content-Type: application/json，而 @PostMapping 默认 consumes 为空，但 @RequestBody 需要 JSON 解析器。

根因是客户端没声明媒体类型，修复后 415 消失。

**错误尝试：** 我一开始以为 415 是路径变量类型转换失败，给 @PathVariable 加了 @DateTimeFormat，结果完全无效，浪费了半小时。

> 现象先分清，怀疑再验证
> 日志有映射，注解没写错
> 请求头缺失，媒体类型错
> 错误尝试记，莫再走弯路

# 07、优化

```text
V1：注解正确但匹配条件不完整 → 证据：405、415 → V2：显式声明 Method、Consumes、Produces
```

V1 的问题在于路由匹配条件太宽松，导致错误请求也能进入匹配流程，但最终被其他层拒绝。

优化方案是显式声明 consumes 和 produces，让路由层提前拒绝不匹配的请求：

```java
@PostMapping(value = "/{ownerId}/pets", consumes = "application/json", produces = "application/json")
public Pet addPet(@PathVariable Long ownerId, @RequestBody Pet pet) {
    pet.setOwnerId(ownerId);
    return pet;
}
```

同时给 GET 方法加上 produces：

```java
@GetMapping(value = "/{ownerId}", produces = "application/json")
public Owner getOwner(@PathVariable Long ownerId) {
    return new Owner(ownerId, "Smith");
}
```

这样 415 会在路由匹配阶段就返回，而不是进入消息转换器后才失败。

> 匹配条件松，错误往后传
> 显式声明后，路由先拦截
> 证据是 415，根因是缺头
> V2 更严格，排障更清晰

# 08、演进

```text
V2：显式匹配条件 → 能力：路由层提前拒绝非法请求 → 遗留：Header、Cookie 匹配未覆盖
```

用 V1 同一组请求验证 V2：

```bash
curl -v http://localhost:8080/owners/1
curl -v -X POST http://localhost:8080/owners/1/pets -H "Content-Type: application/json" -d '{"name":"Buddy"}'
curl -v "http://localhost:8080/owners?lastName=Smith"
```

预期结果：三条请求都返回正确状态码，且错误请求会在路由层被拒绝。

收益是排障更快，代价是 Controller 代码变长，每个方法都要写 consumes 和 produces。

适用条件是 JSON API，如果还要支持 XML，就得写成数组形式。

遗留问题是 Header 和 Cookie 匹配还没用到，比如版本号放 Header 的场景。

> 同一组请求，前后对比看
> 路由层拦截，错误早返回
> 代码变长点，排障省时间
> Header 和 Cookie，留给下一篇

# 09、洞见

```text
从现象到判断：路由匹配是条件组合，不是路径字符串
```

## 路由匹配是条件组合，不是路径字符串

```text
路径 + Method + Header + Content-Type = 唯一 HandlerMethod
```

很多人以为路由就是路径匹配，其实 Spring 把路径、Method、Header、Content-Type 组合成一个 RequestMappingInfo，任何一个条件不满足都会导致匹配失败。

## 反直觉判断：精确路径优先于路径变量

```text
/owners/search 优先于 /owners/{ownerId}
```

如果同时定义了 /owners/search 和 /owners/{ownerId}，请求 /owners/search 会优先匹配精确路径，而不是被路径变量捕获。

## 反直觉判断：405 不是注解没生效，而是 Method 条件不匹配

```text
405 = 路径匹配成功，Method 匹配失败
```

看到 405 时，不要怀疑 @PostMapping 没生效，而是检查请求的 HTTP Method 是否和映射表里的 Method 条件一致。

## 排障先看映射表，不要先改代码

```text
启动日志里的 Mapped 行是路由层的第一手证据
```

遇到 404、405、415，先看启动日志里 RequestMappingHandlerMapping 打印的映射表，确认请求条件是否真的注册了。

> 路由是组合，不是单条件
> 精确胜模式，顺序有讲究
> 405 非注解，Method 不匹配
> 排障先看表，莫急改代码

# 10、系统落地

```text
HTTP 请求 → DispatcherServlet → RequestMappingHandlerMapping → RequestMappingInfo 匹配 → HandlerMethod → Controller
```

原来 Petclinic 只有页面 Controller，没有 REST API。本篇增加了 Owner/Pet 的 REST 路由层，现在能按 ID 查主人、新增宠物、按名字搜索。

下一步缺的是 Header 和 Cookie 匹配，比如 API 版本号放 Header 的场景。

官方文档参考：https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-controller/ann-requestmappin

g.html

> 原来无 REST，现在有路由
> 查询和新增，都能走通
> Header 和 Cookie，还没覆盖
> 版本号场景，留给下一篇

# 11、小结

```text
三问三答：路由匹配是条件组合；精确路径优先；选错规则会打到错误方法
```

为什么注解写对了，请求还是进不了 Controller？因为路由匹配是路径、Method、Header、Content-Type 的组合，任何一个条件不满足都会失败。

当 URL 相同但 HTTP Method 不同时，Spring 怎么决定谁处理？RequestMappingInfo 里存了 Method 条件，匹配时逐个比较，不匹配就返回 405。

如果选错了路由匹配规则，会不会出现线上接口悄悄打到错误方法上的事故？会，比如路径变量和精确路径冲突时，如果顺序不对，可能打到错误方法。

当前状态：V2 已能正确处理 JSON 请求，路由层排障意识已建立。

> 三问已答清，路由不玄学
> 条件组合看，精确优先记
> 选错规则险，线上事故多
> 当前状态明，V2 已落地

# 12、作业

```text
理解 → 实战 → 排障 → 架构判断
```

## 理解题：RequestMappingInfo 里存了哪些匹配条件？

路径模式、HTTP Method、请求头、Consumes、Produces、参数条件等。

## 实战题：给 PetController 增加一个按 ID 查宠物的 GET 接口，要求 produces 为 application/json。

```java
@GetMapping(value = "/pets/{petId}", produces = "application/json")
public Pet getPet(@PathVariable Long petId) {
    return new Pet(petId, "Buddy");
}
```

## 排障题：GET /owners/1 返回 404，但启动日志里有 Mapped "{GET /owners/{ownerId}}"，可能是什么原因？

可能是请求路径拼写错误，或者路径变量类型转换失败，或者请求被其他 Filter 拦截。

## 架构判断题：把 API 版本号放在 Header 里，用 @RequestMapping(headers = "X-API-Version=1") 做路由匹配，是否合理？

合理，但要注意 Header 匹配是精确匹配，版本号变化时需要新增映射，适合版本间差异大的场景。

> 理解要透彻，实战要动手
> 排障要证据，架构要判断
> 四题都做完，路由算入门
> 莫停在注解，源码见真章

# 13、升华

```text
工程结论：路由层是 HTTP 到 Java 方法的翻译器，匹配条件是组合，排障先看映射表
```

路由层不是注解的简单堆砌，而是启动时注册、运行时匹配的一套机制。

理解 RequestMappingInfo 的组合匹配，才能从根因上解决 404、405、415。

下一篇将进入 Header 和 Cookie 匹配，以及 API 版本号的路由策略。

> 注解是入口，映射是核心
> 组合匹配明，排障有方向
> 源码读一遍，胜过背十遍
> 路由层通了，MVC 才入门

**系列项目：** 宠物医院 SaaS 系统的 Owner/Pet REST API

**已完成：** 环境搭建、Petclinic 启动、DispatcherServlet 请求分发

**本篇：** @Controller、@RestController、@RequestMapping 系列注解、RequestMappingHandlerMapping 路由注册与匹配、404/405/415 排障

**下一篇：** Header 与 Cookie 匹配、API 版本号路由策略

我是老李，在深圳南山科技园的一家宠物医疗 SaaS 公司做架构师。团队最近接手了 Spring Petclinic 的 Owner/Pet 模块，要给宠物医院做一个对外开放的 REST API。

《SpringMVC7实战》第4招 Annotated Controller怎么匹配请求

从 Petclinic Owner/Pet API 出发，深入 RequestMappingHandlerMapping 源码，用冲突、404、405、415

架构师

编程语言

后端

开发工具

SpringMVC路由匹配是路径、HTTP方法、请求头与Content-Type的组合条件，精确路径优先于路径变量。排障先查启动日志映射表，405多因方法不匹配、415因媒体类型缺失。显式声明consumes与produces可提前拦截错误请求，实现从注解到RequestMappingInfo源码级排查。

代码解释

路由

SaaS

JSON

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

《SpringMVC7实战》第4招 Annotated Controller怎么匹配请求-腾讯云开发者社区-腾讯云

《SpringMVC7实战》第4招 Annotated Controller怎么匹配请求

《SpringMVC7实战》第4招 Annotated Controller怎么匹配请求

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐