如果你跟我一样日常写接口第一反应就是GetMapping(/list)那一行注解背后其实藏着不少东西。直到有一天我调试一个接口路径对、参数对、PathVariable也对但请求死活进不了方法最终发现是params条件把路由“筛”掉了。那时候我才意识到GetMapping不是简单的“短路径注解”它是一整套路由匹配机制的入口。这篇就从使用方式讲到 Spring MVC 的匹配原理争取让你以后再遇到 404、405、406 这类问题时能直接定位根因而不是靠试。1. 从一行注解说起GetMapping 到底帮你省了什么1.1 请求到方法的路由是 Spring MVC 的核心逻辑在没有注解的年代写一个 Web 接口往往要在配置文件中手动声明 URL 和处理器类的对应关系。Spring MVC 做的第一件大事就是让“URL 到 Java 方法”的映射变成声明式的你在方法上放一个注解框架就能在收到请求后自动找到该方法。GetMapping就是这种声明式路由里最常用的一种。看一个最普通的例子RestController RequestMapping(/api/users) public class UserController { GetMapping(/{id}) public User getUser(PathVariable Long id) { return userService.findById(id); } }这个接口接收GET /api/users/123路径里的123会被绑定到id。没有 XML、没有 Servlet 配置一行注解就把请求方法、路径模式、参数绑定都表达了。但这行注解到底做了什么它只是给 Spring 看的一张“说明书”。真正干活的是RequestMappingHandlerMapping它会在应用启动时扫描所有被注解标记的方法把注解上的信息编译成一种内部结构等到请求进来再拿请求信息去匹配这个结构。这个结构在 Spring 里叫RequestMappingInfo。1.2 GetMapping 与 RequestMapping(method GET) 的关系很多人知道GetMapping是RequestMapping(method RequestMethod.GET)的简写但不清楚具体怎么个“简写法”。实际上GetMapping本身是一个被RequestMapping修饰的组合注解Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) RequestMapping(method RequestMethod.GET) public interface GetMapping { // name、value、path、params、headers、consumes、produces 属性 }关键点在于GetMapping的每个属性都不是独立存在的它们通过AliasFor指向了RequestMapping对应属性。所以你在GetMapping里写的value、params、consumes最终都会“合并”到 Spring 看到的 RequestMapping 语义里。method属性被固定在 GET因此普通用户没办法在GetMapping里改请求方法。这带来一个好处路由契约在一个注解里就能看完代码更紧凑坏处是很多人把GetMapping当成“路径标记”忽略了params、headers、produces这些同样会参与路由匹配的属性。1.3 日常开发的直观收益使用GetMapping最直观的收益就是接口定义稳定。一个方法只处理 GET就不会因为漏写method而把 POST 请求也吞下来。特别是在接口较多、前后端联调频繁的项目里方法级语义明确能避免很多低级错误。不过正如后面要讲的组合注解的属性合并机制也带来了一些隐蔽行为。如果只把GetMapping当成“URL 绑定器”遇到复杂路由条件时就会很被动。2. 字段逐个拆六个条件与一个固定方法GetMapping一共开放了六个可配置条件外加一个固定不可改的 GET 方法。这六个条件有点像六个筛子请求要进入方法必须同时通过所有筛子。属性作用常见用法value/pathURL 路径模式两者互为别名GetMapping(/users/{id})name映射名称一般不常用GetMapping(name getUser)params必须携带的请求参数条件params type1headers必须满足的请求头条件headers X-Platformappconsumes限制 Content-Typeconsumes application/jsonproduces限制 Accept / Content-Type 响应produces application/json;charsetUTF-82.1 value/pathURL 模板与路径变量value和path是同一个东西Spring 里它们互为别名。日常写路径时不需要纠结用哪个保持一致就行。路径模式支持通配符。/users/*可以匹配/users/123但匹配不了/users/123/orders/users/**可以匹配多级路径。除了通配符更常用的是路径变量GetMapping(/users/{id}) public User getUser(PathVariable(id) Long id) { return userService.findById(id); }有一点需要注意路径变量默认按路径片段匹配。如果你想限定格式可以在变量名后加正则GetMapping(/users/{id:[0-9]}) public User getUser(PathVariable Long id) { return userService.findById(id); }加了正则后/users/abc就不会匹配这个方法。这个能力很好用但也容易踩坑如果你在另一个 Controller 里写了/users/abc这样无正则的映射两个方法可能在启动阶段被判定为冲突也可能在请求阶段出现你意想不到的匹配顺序。路径匹配的排序规则在后面会详细说。2.2 params用请求参数做路由分支params是很多人容易忽略的“路由筛子”。它表示“请求必须携带指定参数才会命中该映射”。GetMapping(value /search, params typebasic) public Result basicSearch(RequestParam String q) { return searchService.basic(q); } GetMapping(value /search, params typeadvanced) public Result advancedSearch(RequestParam String q) { return searchService.advanced(q); }上面的写法让同一个路径根据type参数走到不同方法。这是合法的路由设计但要注意如果请求没有带type两个方法都不会命中结果通常是 404而不是 400。因为params参与的是“能不能找到处理器”的过程不是“找到后校验参数”的过程。params不仅支持keyvalue还支持params type要求必须带type参数值随意。params !type要求必须不带type参数。params type!basic要求type参数不等于basic。这些写法的共同点是它们都是路由条件不是业务校验。2.3 headers / consumes / produces按请求头与内容协商分流headers条件与params类似只不过它检查的是请求头GetMapping(value /data, headers X-Version1) public Result dataV1() { return service.v1(); } GetMapping(value /data, headers X-Version2) public Result dataV2() { return service.v2(); }consumes限制的是客户端发送内容的类型也就是请求的Content-Type。比如接口只接收 JSONGetMapping(value /users, consumes application/json) public User createUser(RequestBody User user) { // ... }等等GetMapping一般不会配合RequestBody使用因为 GET 请求很少带 body。这个例子只是为了说明consumes的行为。produces限制的是响应内容类型会结合请求的Accept头进行内容协商GetMapping(value /report, produces application/json;charsetUTF-8) public Report report() { return service.report(); }如果客户端请求头没有声明Accept: application/json而服务端只声明了 JSONSpring 可能返回 406 Not Acceptable。这里要留意produces也是路由条件它在 HandlerMapping 阶段就会影响是否能找到方法而不仅仅是控制响应格式。2.4 method为什么你在注解里改不了它GetMapping没有提供method属性因为这一层已经被固定为 GET。这是组合注解的设计思路把某一组常用约束直接固化让使用者少写一个属性。这个设计也意味着如果你需要一个既支持 GET 又支持 HEAD 的接口用GetMapping反而不合适应该用RequestMapping(path /x, method {RequestMethod.GET, RequestMethod.HEAD})。Spring 对 HEAD 请求有特殊处理如果一个 HEAD 请求映射不到 HEAD 方法但能找到 GET 方法Spring 会调用 GET 方法并丢弃响应体只返回头信息。所以GetMapping在 HEAD 请求下通常也能正常工作但如果你显式只允许 GET语义上就会有一些微妙差别。3. 请求进来之后GetMapping 的匹配链路3.1 DispatcherServlet 不会直接读你的注解Spring MVC 的入口是DispatcherServlet但它不负责解析注解。DispatcherServlet只负责两件事找到合适的HandlerMapping拿到处理器执行链然后调用HandlerAdapter执行。在注解驱动环境下核心的HandlerMapping是RequestMappingHandlerMapping。这个 Bean 在 Spring Boot 的 Web 自动配置里默认注册。它做的事情可以拆成两步启动时扫描Controller、RequestMapping、GetMapping等注解构建路径与 HandlerMethod 的映射表。请求进来时根据请求的 URL、方法、请求头、Content-Type、Accept 等信息从映射表中找到最匹配的那个 HandlerMethod。所以你在方法上写GetMapping不是在“声明一个 URL 对应的函数”而是在给RequestMappingHandlerMapping提供“路由字典”的源数据。3.2 RequestMappingInfoGetMapping 在运行时的真实身份启动时RequestMappingHandlerMapping会把注解信息转化为RequestMappingInfo。这个对象就是路由字典里的“键”。它内部包含多个条件PatternsRequestCondition路径模式。RequestMethodsRequestCondition请求方法。ParamsRequestCondition请求参数条件。HeadersRequestCondition请求头条件。ConsumesRequestConditionContent-Type 条件。ProducesRequestConditionAccept 条件。可以简单理解为一个GetMapping(/users/{id})会被拆成六个条件对象只有六个条件同时满足请求才能命中目标方法。如果你在类上还加了RequestMapping(/api)Spring 还会把类级条件和方法级条件组合起来。组合的规则不是简单拼接字符串而是每个RequestCondition都实现了combine方法路径条件通过拼接得到新的路径模式参数条件、请求头条件则是取并集。3.3 匹配与排序Spring 怎么选出“最合适”的方法当请求到来时RequestMappingHandlerMapping会先按路径缩小候选集合再从候选里逐个调用getMatchingCondition让每个条件判断自己是否匹配。匹配成功后如果候选不止一个就得排序。排序比较的是“精确度”。大致逻辑是路径模式越精确越优先。/users/{id:[0-9]}比/users/{id}优先精确路径比通配符优先。条件数量越多越优先。比如一个有params条件的映射会比没有参数条件的映射更“专一”。请求方法条件、请求头条件、Content-Type 条件、Accept 条件都会参与比较。这个排序规则很重要。它决定了“同路径多条件”场景下请求会进入哪个方法。反过来如果两个方法的RequestMappingInfo在比较后仍然分不出高下Spring 可能抛出IllegalStateException: Ambiguous mapping。实际排查时直接看源码里的RequestMappingInfo.compareTo比空想更快。我经常在本地调试接口时打印RequestMappingHandlerMapping.getHandlerMethods()看看某个路径到底注册成了什么条件。4. 路由歧义与条件竞争为什么会 404、405、415、4064.1 同路径不同方法405 的来源假设你有这样的接口GetMapping(/order/{id}) public Order getOrder(PathVariable Long id) { return orderService.get(id); } PostMapping(/order/{id}) public Order updateOrder(PathVariable Long id, RequestBody Order order) { return orderService.update(id, order); }前端对一个 URL 发送不同方法时Spring 能正确区分因为RequestMethodsRequestCondition是条件的一部分。但如果前端对GET /order/123发送的是 POST而后端只有 GET 映射就会返回 405 Method Not Allowed并且在响应头里带上Allow: GET。很多同学看到 405 第一反应是“没有 POST 接口”这方向没错但更快的验证方法是看响应的Allow头它会明确告诉客户端这个路径当前允许哪些方法。这比翻代码快得多。curl -i -X POST http://localhost:8080/order/123看到HTTP/1.1 405和Allow: GET基本就能确认方法条件的问题。4.2 同路径不同条件谁更适合当两个GetMapping路径一样但params、headers、produces不同Spring 会利用条件的对比规则选一个“更匹配”的。GetMapping(value /user, params modesimple) public User simple() { // ... } GetMapping(value /user, params modefull) public User full() { // ... }请求GET /user?modesimple会命中第一个请求GET /user?modefull会命中第二个。但如果请求GET /user没有mode参数两个条件都不满足结果就是 404。这种设计在 A/B 测试、多版本参数分流时很实用但也是一把双刃剑一旦参数条件写错接口会在特定参数组合下“消失”很难从日志里看出来。4.3 相同映射的启动报错如果两个方法不仅路径相同所有条件也完全一样Spring 会在启动阶段直接报错IllegalStateException: Ambiguous mapping. Cannot map ...这是好事因为它把错误前置了。真正麻烦的是“看起来相同但条件里有细微差别”的情况比如一个方法写了produces application/json另一个没写Spring 会认为它们是不同的映射启动不会报错但请求到来时可能命中不是你预期的那个。我之前就遇到过两个接口路径一样一个produces指定了 JSON一个没指定。结果客户端带了Accept: application/jsonSpring 优先命中有produces的那个另一个方法永远进不去。排查了好久才意识到produces不是装饰它真的参与路由。5. 条件映射不等于参数校验一个常见的认知误区5.1 params 条件只是“路由筛选器”我见过不少同学在 Controller 里这样写GetMapping(value /download, params token!null) public void download(String token) { // 这里假设 token 非空 }这个写法并不能保证token不为空。params token!null的含义是“请求参数里如果带了 token那么它的值不能是字符串形式的null”。如果请求根本没带token这个条件根本不会参与判断。更严格地说params的处理对象是请求参数列表而不是 Java 方法参数。路由条件关心的是“这个请求该不该交给这个方法”而不是“方法内部的参数是否合法”。如果你希望校验参数需要依靠方法参数注解和校验框架GetMapping(/download) public void download(RequestParam String token) { // token 缺失时抛出 MissingServletRequestParameterException }5.2 400 和 404 的分工弄清楚这个误区对错误码的理解也清晰了请求能匹配到路径和方法但参数缺失或类型错误Spring 返回 400。请求根本匹配不到任何处理方法Spring 返回 404。路径匹配到了但 HTTP 方法不对Spring 返回 405。路径和方法都对但 Content-Type 不匹配Spring 返回 415。路径和方法都对但 Accept 与 produces 不匹配Spring 返回 406。这四个状态码背后对应的是不同阶段的条件判断。遇到问题时先分清楚是“没找到方法”还是“找到方法但条件不满足”能节省大量排查时间。6. 理解组合注解的编程模型才能用好 GetMapping6.1 AliasFor 如何让派生注解与父注解互通前面提到GetMapping的属性通过AliasFor指向RequestMapping。这个机制是 Spring 注解编程模型的核心Spring 在解析注解时不是只看方法上的主注解而是会把被元注解修饰的注解“展开”拿到完整的属性集。用开发者视角理解GetMapping(value /users)等价于RequestMapping(value /users, method GET)。Spring 会把value属性从GetMapping里取出来再合并给RequestMapping的value。两级注解之间如有同名属性内层注解的显式设置会覆盖或合并外层默认值。理解这一点你就不会再问“为什么GetMapping没有method属性”这类问题了。因为它的method已经在元注解里写死组合的是一个更具体的“请求方法条件”。6.2 自定义组合注解的姿势既然 Spring 支持元注解我们也可以基于GetMapping再组合出业务语义更强的注解Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) GetMapping(produces application/json;charsetUTF-8) public interface GetJson { AliasFor(annotation GetMapping.class, attribute path) String[] path() default {}; }这样在 Controller 里就可以写GetJson(/users/{id}) public User getUser(PathVariable Long id) { // ... }好处是团队内部可以统一“返回 JSON 的 GET 接口”的写法不用每个方法都重复写produces。但要提醒一句自定义组合注解越复杂排查时的心智成本越高。如果团队里不是所有人都熟悉 Spring 的AliasFor机制建议只在需要强约束时才用。6.3 调试注解的实用方法如果你怀疑某个接口的最终生效条件和你理解的不一致可以在本地加一个临时调试入口Autowired private RequestMappingHandlerMapping mapping; GetMapping(/debug-mappings) public Object debugMappings() { return mapping.getHandlerMethods().entrySet().stream() .map(entry - entry.getKey() - entry.getValue()) .collect(Collectors.toList()); }看到RequestMappingInfo的内容后你就能确认路径、方法、参数条件到底注册成了什么样。生产环境不要暴露这种接口本地调试用一下非常高效。7. 几个真实踩坑案例从现象到根因7.1 接口突然 405Allow 头是最好的侦察兵有一次前端同事反馈“同样的接口之前是 POST现在变成了 405”。我一开始以为是网关问题后来用curl打了请求看到响应头里有Allow: GET, OPTIONS。这说明后端确实把接口改成 GET 了。顺着代码历史一查发现有人把PostMapping改成了GetMapping但前端没同步。这个案例的教训是405 不等于“没有接口”而是“这个路径上有接口但不接受你当前的方法”。排查时一定要看Allow头它会列出所有允许的方法非常直观。7.2 接口 404但路径看起来没问题另一个案例是控制台能精确匹配到路径但接口返回 404。最终发现是params条件引起的。接口写成GetMapping(value /search, params v1) public Result searchV1(RequestParam String q) { ... }前端请求的是GET /search?qhello没有带v1于是 Spring 认为这个映射不匹配又没有其他映射直接 404。从业务角度我们希望的是“没带版本号就用默认版本”但从路由角度Spring 不这么理解。解决方式有两种要么给方法补一个不依赖params的映射要么把版本判断逻辑放到方法内部而不是声明在路由条件里。我更推荐后者因为路由条件越多接口的可预测性越差。7.3 新增 produces 后接口变 406还有一个案例接口原本不指定produces前端正常访问。后来为了统一响应格式给方法加了produces application/json;charsetUTF-8结果某些客户端开始收到 406。原因在于这些客户端发送的Accept头是*/*或者只声明了text/html而服务端只看Accept与produces的兼容性。匹配不上就返回 406。这种问题的解法通常有两类一类是把produces放宽为支持多种类型另一类是在网关或统一响应层做内容协商。总之produces一旦声明它就成了路由的一部分而不是“我想返回 JSON”的注释。最后再分享一点经验我现在的习惯是先尽量少在GetMapping上叠加params和headers这类条件能用普通参数解决的就用参数解决只有在做多版本共存、A/B 分流这类明确需要“同一个 URL 不同语义”的时候才动用路由条件。另外每当新增接口或调整映射我会顺手用curl -i看一眼状态码和响应头确认路由真的按预期工作。GetMapping本身不难难的是把它放到 Spring 的匹配框架里理解。希望这篇能帮你少踩几个坑。
