在Java Web开发里Spring MVC的注解可能是我们每天打交道最多的东西。从最早的Controller到后来的RestController从RequestParam到RequestBody这些注解让代码从繁琐的XML配置里解放出来也让路由、参数绑定、数据校验这些事变得跟写普通方法一样自然。我最早接触SpringMVC还是3.x时代那时候配置文件一大堆后来4.x、5.x一步步演进注解机制越来越完善。这篇文章不是把官方文档抄一遍而是从一个实际开发者的角度把这些常见注解的用法、背后的原理、以及那些最容易踩的坑一次性说透。不管你是刚入门Spring的新手还是已经写过一段时间业务的同学希望都能从中找到点有价值的东西。1. SpringMVC注解体系概览与设计思路1.1 为什么SpringMVC用注解替代XML配置很多刚入行的同学可能没见过SpringMVC 2.5之前的项目长什么样。那时候每个接口都要在spring-mvc.xml里写一大段bean配置一个HandlerMapping、一个HandlerAdapter再加上一堆property去指定控制器类代码量极大不说改一个URL映射还得去XML里翻半天。后来注解出现之后Controller加上RequestMapping往方法上一标路由器就自动注册了开发效率完全是质变。但注解不是简单地省掉了配置代码它本质上是一种声明式编程。它的好处有三个第一信息局部化路由、参数、校验这些和接口相关的元数据直接写在方法旁边读代码的时候一眼就能看到第二类型安全比如RequestParam(id) Integer id容器在绑定的时候如果类型不匹配直接抛异常比XML里字符串拼接靠谱得多第三组合能力强一个注解可以被多个注解元标注比如RestController其实就是Controller加ResponseBody的组合这种组合很符合面向对象的复用思想。1.2 注解的分类与核心功能划分我把SpringMVC常见的注解分成了五类这样理解起来会清晰很多。第一类是请求映射注解负责把HTTP请求映射到处理方法上典型代表是RequestMapping、GetMapping、PostMapping第二类是参数绑定注解负责把请求里的参数绑定到方法的入参上比如RequestParam、PathVariable、RequestBody第三类是响应处理注解负责处理返回值比如ResponseBody、RestController第四类是数据访问与事务注解比如Transactional虽然它不是MVC模块直接提供的但业务接口里几乎离不开第五类是缓存与通用能力注解比如Cacheable、EnableCaching以及SpringBoot里那些简化配置的注解。为什么要这么分类因为搞清楚了分类你就能预判注解大概在哪个环节生效。比如请求生命周期大概是这样请求进来 → 拦截器预处理 → HandlerMapping找到对应方法 → HandlerAdapter执行参数绑定 → 调用方法 → 处理返回值 → 拦截器后处理 → 响应出去。参数绑定类的注解就是在执行方法之前起作用响应处理类的注解就是在方法执行之后起作用理解了这条主线后面看任何注解都不会乱。2. 请求映射注解详解2.1 RequestMapping及其变体的使用RequestMapping是SpringMVC里最核心的注解它可以加在类上也可以加在方法上。加在类上时它相当于定义了一个命名空间前缀比如RequestMapping(/user)然后方法上的RequestMapping(/list)最终的访问路径就是/user/list。这个设计规范了分层避免不同模块的URL互相冲突。它在方法级别有几个常用属性value指定路径method指定请求方式params用来限定请求参数headers用来限定请求头。比如RequestMapping(value /query, method RequestMethod.GET, params type1)意味着只有当请求路径是/query、请求方式是GET、且包含type1这个参数时这个方法才会被命中。这种写法在早期版本里很常见但现在基本都被组合注解取代了。不过要注意一个坑RequestMapping默认匹配所有请求方式。如果你不指定methodPOST请求也能进来。这在开放接口的时候很危险因为你的方法可能做了敏感操作却能被一个简单的GET请求触发。所以凡是涉及数据修改的接口一定要明确指定请求方式。2.2 RESTful风格下的GetMapping、PostMapping等从Spring 4.3开始官方推出了一组组合注解GetMapping、PostMapping、PutMapping、DeleteMapping、PatchMapping。它们本质上是RequestMapping的变体各自绑定了对应的HTTP方法。比如GetMapping就是RequestMapping(method RequestMethod.GET)的缩写。这组注解最大的价值是让代码语义更清晰。看到GetMapping就知道这是一个查 
长河君 · 2026/9/15 20:38:25 · 阅读 1.2k SpringMVC注解实战：从@Controller到@RequestBody的核心用法与原理
在Java Web开发里Spring MVC的注解可能是我们每天打交道最多的东西。从最早的Controller到后来的RestController从RequestParam到RequestBody这些注解让代码从繁琐的XML配置里解放出来也让路由、参数绑定、数据校验这些事变得跟写普通方法一样自然。我最早接触SpringMVC还是3.x时代那时候配置文件一大堆后来4.x、5.x一步步演进注解机制越来越完善。这篇文章不是把官方文档抄一遍而是从一个实际开发者的角度把这些常见注解的用法、背后的原理、以及那些最容易踩的坑一次性说透。不管你是刚入门Spring的新手还是已经写过一段时间业务的同学希望都能从中找到点有价值的东西。1. SpringMVC注解体系概览与设计思路1.1 为什么SpringMVC用注解替代XML配置很多刚入行的同学可能没见过SpringMVC 2.5之前的项目长什么样。那时候每个接口都要在spring-mvc.xml里写一大段bean配置一个HandlerMapping、一个HandlerAdapter再加上一堆property去指定控制器类代码量极大不说改一个URL映射还得去XML里翻半天。后来注解出现之后Controller加上RequestMapping往方法上一标路由器就自动注册了开发效率完全是质变。但注解不是简单地省掉了配置代码它本质上是一种声明式编程。它的好处有三个第一信息局部化路由、参数、校验这些和接口相关的元数据直接写在方法旁边读代码的时候一眼就能看到第二类型安全比如RequestParam(id) Integer id容器在绑定的时候如果类型不匹配直接抛异常比XML里字符串拼接靠谱得多第三组合能力强一个注解可以被多个注解元标注比如RestController其实就是Controller加ResponseBody的组合这种组合很符合面向对象的复用思想。1.2 注解的分类与核心功能划分我把SpringMVC常见的注解分成了五类这样理解起来会清晰很多。第一类是请求映射注解负责把HTTP请求映射到处理方法上典型代表是RequestMapping、GetMapping、PostMapping第二类是参数绑定注解负责把请求里的参数绑定到方法的入参上比如RequestParam、PathVariable、RequestBody第三类是响应处理注解负责处理返回值比如ResponseBody、RestController第四类是数据访问与事务注解比如Transactional虽然它不是MVC模块直接提供的但业务接口里几乎离不开第五类是缓存与通用能力注解比如Cacheable、EnableCaching以及SpringBoot里那些简化配置的注解。为什么要这么分类因为搞清楚了分类你就能预判注解大概在哪个环节生效。比如请求生命周期大概是这样请求进来 → 拦截器预处理 → HandlerMapping找到对应方法 → HandlerAdapter执行参数绑定 → 调用方法 → 处理返回值 → 拦截器后处理 → 响应出去。参数绑定类的注解就是在执行方法之前起作用响应处理类的注解就是在方法执行之后起作用理解了这条主线后面看任何注解都不会乱。2. 请求映射注解详解2.1 RequestMapping及其变体的使用RequestMapping是SpringMVC里最核心的注解它可以加在类上也可以加在方法上。加在类上时它相当于定义了一个命名空间前缀比如RequestMapping(/user)然后方法上的RequestMapping(/list)最终的访问路径就是/user/list。这个设计规范了分层避免不同模块的URL互相冲突。它在方法级别有几个常用属性value指定路径method指定请求方式params用来限定请求参数headers用来限定请求头。比如RequestMapping(value /query, method RequestMethod.GET, params type1)意味着只有当请求路径是/query、请求方式是GET、且包含type1这个参数时这个方法才会被命中。这种写法在早期版本里很常见但现在基本都被组合注解取代了。不过要注意一个坑RequestMapping默认匹配所有请求方式。如果你不指定methodPOST请求也能进来。这在开放接口的时候很危险因为你的方法可能做了敏感操作却能被一个简单的GET请求触发。所以凡是涉及数据修改的接口一定要明确指定请求方式。2.2 RESTful风格下的GetMapping、PostMapping等从Spring 4.3开始官方推出了一组组合注解GetMapping、PostMapping、PutMapping、DeleteMapping、PatchMapping。它们本质上是RequestMapping的变体各自绑定了对应的HTTP方法。比如GetMapping就是RequestMapping(method RequestMethod.GET)的缩写。这组注解最大的价值是让代码语义更清晰。看到GetMapping就知道这是一个查