企业官网建设流程全解析

写Controller的时候，参数获取这关是绕不过去的，@RequestParam、@PathVariable这几个注解平时都在用，可真要细问一句"什么时候该用哪个、为什么这接口里前端漏传了个参数就直接400"，不少老开发都得愣一下。我见过太多同事在@RequestParam和@PathVariable之间来回试探，也见过因为没配required = false导致前端一漏传就报错的惨案。这篇文章就把Spring MVC里请求参数获取的六个核心注解逐个拆开讲透，包含每个注解的底层逻辑、参数属性、典型场景和踩坑记录。内容适合刚接触Spring Boot的读者，也适合那些写了一阵子Controller但没系统梳理过这些注解的同学，希望能帮你们一次性把这几个注解串起来。

1. 六个注解的定位与整体拆解

1.1 先从HTTP请求的结构看参数从哪里来

要理解这几个注解，得先回到HTTP请求本身。一个标准的HTTP请求可以简单拆成三块：请求行、请求头、请求体。

请求行里有URL路径和查询参数，比如/user/123?name=zhangsan&page=1，这里的123是路径的一部分，而name和page是Query String，它们分别对应@PathVariable和@RequestParam的取值来源。请求头就是那些Content-Type、Authorization、User-Agent之类的键值对，对应@RequestHeader。请求体则是POST/PUT请求里携带的实体内容，最常见的是JSON字符串，对应@RequestBody。至于@CookieValue和@RequestAttribute，情况特殊一点：Cookie可以看作请求头里Cookie字段的一部分，有独立注解处理；而@RequestAttribute拿的其实不是前端直接传的原始参数，而是服务端在请求处理过程中往request域里塞进去的对象。

这样说可能有点干，我直接把这六个注解的来源和典型场景整理成一张表：

1.2 为什么Spring需要这么多参数注解

有读者可能会问：既然我用HttpServletRequest也能拿参数，为什么Spring还要搞这么多注解？说句实话，Spring MVC本质上是在Servlet API之上做了一层抽象，把"从request里手动取值、做类型转换、判空"这些重复劳动封装成了注解驱动的方式。这样做的好处是你只需要关心"参数叫什么名字、什么类型、是不是必传"，剩下的解析、转换、绑定都由框架完成。

但这些注解之所以分得这么细，根本原因在于数据的来源不同。你不能用@RequestParam去拿路径里的{id}，也不能用@PathVariable去拿Query String里的page，因为它们的解析策略完全不同。理解这一点，后面很多问题就好办了：看到注解就知道数据从哪里来，遇到接不到参数的问题时，第一反应可以判断是不是取错了来源。这也是我写这篇文章的初衷——把这六个注解当成一个完整体系来看，而不是死记硬背每个注解的用法。

2. @RequestParam详解：最常用的参数注解

2.1 基本用法与参数名映射

@RequestParam应该是最常用的一个参数注解，它负责从请求的Query String或者表单体里取值。平时写接口，后端接口定义为/user/list?page=1&size=10，Controller方法里就可以这样写：

@GetMapping("/user/list") public Result listUsers( @RequestParam("page") Integer page, @RequestParam("size") Integer size) { return userService.listUsers(page, size); }

这里有个容易被忽视的点：@RequestParam里的value值必须跟前端传的参数名保持一致，如果不一致，参数就接不到。比如前端传的是pageNum，后端写的是@RequestParam("page")，那Spring会认为page是必填参数，结果前端没传，直接报400。

为了避免这种问题，我个人的习惯是后端接口参数名和前端字段名尽量统一，同时如果只是简单类型参数，其实不写@RequestParam也能绑定上。Spring MVC默认对简单类型参数做了参数名匹配，即使方法签名里只写Integer page，Spring也会自动去Query String里找page。但这里有个陷阱：一旦你写了@RequestParam，就必须显式处理required属性，因为注解的required默认是true。所以我的建议是：如果用注解，就明确写出来；如果不用注解，也要清楚它的默认行为是什么。

@RequestParam还有几个属性值得说一下。name和value是等价的别名，都是指定参数名；required控制是否必填，默认true；defaultValue设置默认值，一旦设置了默认值，required默认就变成了false。这三个属性在写接口时基本都会用到，尤其是非必填参数的场景，下一节专门展开讲。

2.2 非必填参数的正确配置：required=false 与 defaultValue

搜"requestparam 非必填"的人很多，说明这确实是高频痛点。先说结论：想让一个请求参数不是必传项，写法是@RequestParam(value = "keyword", required = false) String keyword。就这么简单，但实际项目里踩坑的细节远不止这一行。

第一个坑，也是最常见的：默认情况下required是true。你写@RequestParam("page") Integer page，前端访问接口时没传page这个参数，Spring会直接抛出MissingServletRequestParameterException，表现给客户端的就是400 Bad Request。很多联调冲突就是这么来的——前端说参数可传可不传，后端忘了加required=false，两边对不上。

第二个坑，required=false配合基础类型的问题。如果你写的是@RequestParam(value = "age", required = false) int age，前端没传age，Spring会把null赋给int类型的变量，Java的自动拆箱机制会抛NPE。虽然Spring在处理参数绑定的时候报错的时机有差异，但实际环境里用int承接可空参数，在后续代码里使用时就可能随时炸。所以非必填参数，我建议一律用包装类型：Integer age，这样参数缺失时得到的是null，你在业务代码里就能正常判空。

第三个坑是defaultValue的妙用。很多场景下，非必填参数其实都有默认值，比如分页的page默认1、size默认10。这时候不需要写required=false，直接写@RequestParam(value = "page", defaultValue = "1") Integer page即可。注意，一旦设置了defaultValue，required会变成false，就算前端不传page，Spring也拿“1”去转换类型，再也不用担心NPE和400。我在实际项目里几乎所有的分页参数都是这么写的，代码简洁，逻辑还稳。

再看一个容易忽略的点：required=false时，如果前端传了参数但传的是空字符串，这个参数得到的是空串，不是null。比如keyword=，Spring不会因为字符串为空就把值置成null，而是给一个空字符串。如果你的业务逻辑里按null去判空，可能会漏掉空串的情况。建议在业务层或者参数校验阶段统一处理空字符串。

2.3 用Map批量接收参数与多值参数

有些接口参数比较多，或者参数列表不固定，这时候一个参数写一个注解会很痛苦。Spring允许你用Map来接收所有Query String参数：

@GetMapping("/search") public Result search(@RequestParam Map<String, String> params) { String keyword = params.get("keyword"); Integer page = Integer.parseInt(params.getOrDefault("page", "1")); // ... }

这种方式适合参数动态变化的管理后台列表查询，尤其是筛选条件多的场景，不用频繁改接口签名。但要注意，Map接收到的值全是String类型，页面字段返回的是什么字符串，这里拿到的就是什么字符串，需要自己去转换。而且Map方式拿不到那些没有值的参数，比如前端传了?keyword=，Map里会有key，但value是空串；如果前端压根没传，Map里就没有这个key。

还有一种多值场景：复选框或多选的筛选条件，前端会传多个同名参数，比如?tag=java&tag=spring&tag=mysql。这时候可以用List接收：

@GetMapping("/filter") public Result filter(@RequestParam("tag") List<String> tags) { // tags = ["java", "spring", "mysql"] }

这里我提示一句：如果前端传的是逗号拼接的字符串，比如?tags=java,spring,mysql，就不能直接用List接收，得先接String再自己split。这两种传法前端和后端要事先约定好，不然很容易出现"我传了数组你看不到"的情况。我一般建议前端多选就传多个同名参数，语义清晰，Spring解析方便；如果参数值本身包含逗号，就千万不能用逗号拼接的方案。

3. @PathVariable与RESTful风格参数

3.1 路径变量的基本用法与匹配规则

RESTful风格的接口把资源标识放在URL路径里，比如/user/123表示查询id为123的用户，这个123就是路径变量。在Spring里用@PathVariable获取：

@GetMapping("/user/{id}") public Result getUser(@PathVariable("id") Long id) { return userService.getUserById(id); }

前端访问/user/123，Spring会把路径模板{id}对应的实际值123取出来，绑定到方法参数id上。注意，这里有个非常值得强调的区别：/user/123里的123是路径的一部分，不是Query String，所以用@RequestParam是取不到的。很多人刚接触Spring时经常会写@GetMapping("/user/{id}")配一个@RequestParam("id") Long id，结果发现无论如何都接不到，就是这个原因。

路径变量还支持多个，比如订单详情加操作记录的写法：

@GetMapping("/order/{orderId}/item/{itemId}") public Result getOrderItem( @PathVariable("orderId") Long orderId, @PathVariable("itemId") Long itemId) { // ... }

Spring的路径模板也支持正则匹配。比如只想匹配纯数字的id，可以写@GetMapping("/order/{orderId:[0-9]+}")，这样如果前端传/order/abc，请求根本进不了这个方法，会落到404（如果没有其他匹配的Mapping的话）。这个特性在接口设计进阶时可以派上用场，但用的时候注意别写太复杂的正则，不然维护起来头疼。

3.2 @PathVariable和@RequestParam到底该怎么选

这是我从答疑群里看到提问频率最高的问题之一："这两个注解长得挺像，到底啥时候用哪个？"我的经验就一句话：资源的唯一标识放路径里，条件筛选放Query参数里。

举个例子，GET /user/123是获取某个具体用户，这个123是资源的ID，天然适合@PathVariable；而GET /user?age=18&city=beijing是筛选符合条件的用户列表，这些筛选条件不该塞进路径里，应该用@RequestParam。如果一个资源存在从属关系，比如GET /user/123/orders?status=paid，那么123是资源定位，status是过滤条件，两个注解就会在同一个方法里出现。

再从URL设计的角度看，路径参数表示"你要找的是谁"，查询参数表示"你要按什么条件找"。这个语义一旦明确，不仅代码写起来清晰，前端对接、接口文档生成也自然顺畅。我自己在review代码时，看到@GetMapping("/user/{id}")配@RequestParam("id")会直接打回，因为这是典型的"把RESTful语义搞混了"。别觉得这是小事，接口的路径设计就是团队接口规范的底层，越早理顺，后面维护越省心。

路径变量在参数命名上我还想多一句：如果Controller类上标注了@RequestMapping("/user")，方法上的路径不要写成@GetMapping("/user/{id}")，留给方法的路径应该只是/{id}。这个和参数注解关系不大，但确实是我审查代码时常见的问题。

4. @RequestHeader与@CookieValue：元数据与状态参数

4.1 @RequestHeader获取请求头信息的典型场景

请求头里其实藏了大量客户端信息，比如Authorization携带令牌，User-Agent标识浏览器/客户端类型，Accept-Language表示语言偏好，X-Request-Id可能用于链路追踪。这些信息虽然不是业务主参数，但在鉴权、日志、国际化里都很重要。用@RequestHeader拿请求头的写法如下：

@GetMapping("/profile") public Result profile( @RequestHeader(value = "Authorization", required = false) String token, @RequestHeader("User-Agent") String userAgent) { // ... }

和@RequestParam一样，@RequestHeader也有required和defaultValue属性。比如某个网关服务可能不发X-Request-Id，但日志系统又希望有唯一标识，就可以这样写：

@RequestHeader(value = "X-Request-Id", defaultValue = "unknown") String requestId

这样即使请求头里没有这个值，代码也不会报错，日志里也能有兜底内容。

如果请求头太多，不想一个个写参数，可以用HttpHeaders类型或者Map<String, String>接收所有请求头：

@GetMapping("/debug/headers") public Result debugHeaders(@RequestHeader HttpHeaders headers) { headers.forEach((key, value) -> log.info("{}: {}", key, value)); // ... }

HttpHeaders本质上是个multi-value的结构，方法和参数直接返回的是第一个值还是集合，取决于你声明的类型。我在实际开发里比较推荐按需取单个Header，而不是一锅端，因为让接口显式声明依赖哪些请求头，接口的可读性和自文档性都会好很多。

4.2 @CookieValue获取Cookie，以及它和@RequestHeader的边界

Cookie本质上是请求头Cookie字段的一部分，格式是key=value; key2=value2，Spring单独提供@CookieValue注解，省去你自己解析字符串的麻烦：

@GetMapping("/cart") public Result getCart(@CookieValue(value = "sessionId", required = false) String sessionId) { // ... }

常见的场景是登录态：用户登录之后，服务端下发一个Cookie，比如SESSION或者user_token，后续请求带上它，后端在拦截器里解析出用户信息。直接在Controller里用@CookieValue取某个Cookie值比较省事，相当于把request.getCookies()的遍历过程交给了框架。

但这里我得提醒一句：如果你想拿到Cookie的所有属性（比如domain、path、maxAge），用@CookieValue就无能为力了，只能老老实实用HttpServletRequest去遍历：

Cookie[] cookies = request.getCookies(); for (Cookie cookie : cookies) { if ("sessionId".equals(cookie.getName())) { // cookie.getValue() / cookie.getMaxAge() / cookie.getPath() } }

另外一个容易被坑的点是Cookie的作用域。如果Cookie设置了Path=/admin，那前端在/api路径下请求时不会携带它，后端自然取不到。遇到"昨天还能登录取到Cookie，今天突然拿不到"的情况，别只查后端代码，先看浏览器Application面板里Cookie的Domain和Path对不对，再谈代码。

@CookieValue和@RequestHeader的边界问题，说透了就一句话：把Cookie当参数用，就用@CookieValue；把整个请求头当元数据，或者要取非Cookie的头，就用@RequestHeader。两者都支持required和defaultValue，用法上是一致的。

5. @RequestBody接收请求体：JSON参数的核心通道

5.1 基本用法与消息转换器的工作原理

@RequestBody用于把HTTP请求体里的内容绑定到方法参数对象上，最典型的就是前端POST一个JSON对象，后端用DTO直接接收：

@PostMapping("/user") public Result createUser(@RequestBody UserDTO user) { return userService.createUser(user); }

前端请求长这样：

POST /user Content-Type: application/json { "name": "张三", "age": 25, "email": "zhangsan@example.com" }

Spring收到请求后，会根据请求头里的Content-Type找到对应的HttpMessageConverter，把JSON字符串反序列化成UserDTO对象。这里的关键点就来了：Content-Type必须是application/json（或者是Spring配置里消息转换器支持的MIME类型），才能触发MappingJackson2HttpMessageConverter来解析。如果前端提交时没设置Content-Type，默认可能是application/x-www-form-urlencoded，那@RequestBody就读不到JSON内容，接口要么拿到一个全是null的对象，要么直接报错。

所以写接口文档时，我特别强调要写明"请求体格式为JSON，Content-Type为application/json"。很多前后端联调问题都出在请求头错误，而不是代码逻辑错误。

5.2 @RequestBody和@RequestParam如何分工与合作

这两个注解的字面意思都有"参数"两个字，实际上它们的工作区域完全不同。@RequestParam处理的是请求行里的Query参数和表单字段，@RequestBody处理的是整个请求体的负载内容。在同一个接口里，它们可以共存：

@PostMapping("/user/{id}") public Result updateUser( @PathVariable("id") Long id, @RequestParam(value = "notify", required = false) Boolean notify, @RequestBody UserDTO user) { // ... }

这种混用的场景在RESTful接口里挺常见的：id定位资源，notify是操作选项，user是更新数据实体。但要注意：一个请求只能有一个body，所以一个方法里只能有一个@RequestBody参数。如果写两个@RequestBody参数，Spring会直接报错，因为两个参数都想去绑定同一个请求体，无法区分。

还有一点容易踩的坑：GET请求带body。HTTP规范对GET请求体没有严格禁止，但很多客户端（包括一些老旧proxy）在发送GET请求时会直接丢弃body。所以如果你的接口设计是GET方法且用了@RequestBody，在某些环境下可能程序能写，但前端实际发出去的数据会被网络链路丢掉，导致莫名其妙的参数为空。这种设计本身就不推荐，能改POST就改POST，改不了就改用Query参数，别跟底层行为较劲。

在实际项目里，@RequestBody还经常和@Validated、@Valid配合做参数校验：

@PostMapping("/user") public Result createUser(@Validated @RequestBody UserDTO user) { // 校验不通过时会抛出 MethodArgumentNotValidException }

DTO字段上加@NotBlank、@Email、@Size等注解，Spring在参数绑定后自动触发校验，省掉一大段手写判空的代码。这块算是@RequestBody的黄金搭档，强烈建议每个接口都加上。

5.3 用Map或JsonNode接收动态JSON结构

有些时候，前端的JSON结构是动态的，比如配置下发、事件上报这类接口，你不能为每一种结构都定义一个DTO。这种情况下可以用Map<String, Object>或者Jackson的JsonNode来接：

@PostMapping("/event") public Result receiveEvent(@RequestBody Map<String, Object> payload) { String eventType = (String) payload.get("type"); Object data = payload.get("data"); // ... }

用Map的方式灵活，接收方可以根据自己的需求动态取字段。但灵活是有代价的：你失去了类型安全和编译期检查，字段拼写错了只有在运行期才会暴露。所以我建议，动态结构的接口要额外做好日志记录和字段校验，至少保证既能发现问题，也能辅助排查问题。

用JsonNode的话，类型处理会更灵活一些，可以直接调用.get("name").asText()，也可以判断节点是否存在再决定后续逻辑。但JsonNode对很多业务团队来说不太常见，增加了代码阅读成本。具体选哪种，看团队习惯吧，我自己的项目里更倾向Map，因为大多数动态JSON的取参逻辑相对简单，Map的API也更通用。

还有个经验：前端传JSON数组的场景，比如批量添加用户，可以直接@RequestBody List<UserDTO> users，Spring会正确反序列化成List。这个写法比你包一层{"list": [...]}再取list字段要优雅得多，接口语义也更直观。

6. @RequestAttribute：被低估的请求域参数

6.1 基本用法与数据来源：request.setAttribute

@RequestAttribute这个注解在业务代码里用的频率不算高，很多人对它很陌生。它的作用是从request域中取属性值，也就是那些通过request.setAttribute("key", value)设置的值。注意，这个值是服务端代码在请求处理过程中塞进去的，不是前端直接传的原始参数。基本用法：

@GetMapping("/profile") public Result profile(@RequestAttribute("loginUserId") Long loginUserId) { // ... }

看到这里你可能会有疑问：前端能不能通过某个方式往request attribute里塞值？@RequestParam接的是URL参数，@RequestBody接的是JSON，那前端传个名字叫loginUserId的参数，能不能用@RequestAttribute收到？答案是不能。request attribute只存在于服务端请求对象的生命周期里，是服务器内部共享数据的方式，和HTTP报文的传输内容没有直接关系。这一点是区分它和@RequestParam的关键。

那它在实际项目里有什么用呢？最经典的场景是配合拦截器或过滤器，把解析好的用户信息、权限信息塞进request域，然后Controller里直接取用。比如JWT鉴权拦截器：

@Component public class AuthInterceptor implements HandlerInterceptor { @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { // 从前端请求头里取token并解析出用户ID String token = request.getHeader("Authorization"); Long userId = parseToken(token); request.setAttribute("loginUserId", userId); return true; } }

Controller里再用@RequestAttribute("loginUserId") Long loginUserId直接获取，省去重复解析token的逻辑。这个设计的好处是：鉴权和业务逻辑解耦，业务方法不用关心token从哪来、怎么解析，只需要声明"我需要当前登录用户ID"即可。

6.2 为什么前端参数传不进@RequestAttribute

我猜肯定有人试过用@RequestAttribute去接前端传的参数，结果发现永远是null。原因前面说过，request attribute和HTTP报文内容不是一回事。@RequestAttribute对应的取值来源是HttpServletRequest.getAttribute()，而@RequestParam对应的是getParameter()，这两个方法的数据来源完全不同。

Servlet规范里，getAttribute()返回的是服务端通过setAttribute()设置的对象，一般在请求处理过程中由过滤器、监听器或拦截器写入；而getParameter()返回的是HTTP请求参数，来自于Query String或表单体。从安全角度理解一下：request attribute是服务端内部的"临时变量"，前端无法也绝不应该控制它，否则权限验证就形同虚设了。

实战中另外一个常见误区是把@RequestAttribute和@ModelAttribute搞混。@ModelAttribute主要用于表单对象绑定和模型数据准备，用途是数据绑定和视图渲染，而@RequestAttribute只是简单地从request域中取值。两者设计目标不同，不要混着用。

如果你在过滤器里写了request.setAttribute("startTime", System.currentTimeMillis())，想通过@RequestAttribute("startTime") Long startTime在Controller里拿执行耗时，这种用法是可行的，也比较适合做接口耗时监控。但如果是想拿用户传的业务参数，那就走错了方向，赶紧换@RequestParam或@RequestBody吧。

7. 常见问题与排查技巧实录

7.1 400 Bad Request：八成是required没配置

接口联调时最让人崩溃的就是"前端说没问题，后端说报400"。就我观察到的项目经验，Spring MVC接口报400，最常见的场景就是请求里缺了必选参数，好好排查一下，十有八九是@RequestParam、@RequestHeader等注解没配置required = false。这里说的"缺参数"包括：参数名拼错、参数漏传、参数名大小写不一致。

排查思路我建议按三步走。第一步，看后端日志有没有MissingServletRequestParameterException或MissingRequestHeaderException等字样，Spring的默认日志会打印出具体是哪个参数缺失。第二步，对照接口定义和前端实际请求，用接口调试工具（Postman、Apifox都行）看URL上带的名字和后端注解里的参数名是否一致。第三步，如果日志不清晰，打开Spring MVC的日志级别到DEBUG，能看到更详细的参数绑定过程。这三步走完，绝大多数400问题都能定位。

很多人遇到400会习惯性说"这是前端问题"，但我会建议后端自己也把接口用工具跑一遍。一个成熟的接口开发流程，应该是在接口文档里明确标注哪些参数必填、哪些选填、默认值是什么。这样前端联调时有据可查，后端也不用一次次解释"你少传了参数"。

7.2 参数接的到但值是null：排查来源与类型问题

和400正好相反，有一种情况是接口正常进入方法，但业务参数是null。这时候问题往往出在四个环节。第一，@PathVariable参数名和路径模板里的占位符不一致，比如模板是{id}，参数写的是@PathVariable("userId") Long id，那返回值自然拿不到。第二，@RequestParam的value值拼错，比如前端传user_name，后端写username，当然接不到。第三，类型转换失败，比如前端传了age=abc，Spring底层会尝试把字符串转成Integer，转换失败时可能抛出MethodArgumentTypeMismatchException，表现可能是400或者接口直接报500。第四，参数来源对不上，比如数据在Query参数里，你用@RequestBody去接，结果自然就是null。

这类问题我的排查习惯是把接口请求原样打日志，至少把request.getRequestURI()和request.getQueryString()打出来，再看方法参数绑定前后的结果。在Spring Boot里配置好日志，对排查参数问题帮助极大。很多"它怎么可能是null"的灵异事件，最后都能在原始请求里找到答案。

7.3 Content-Type配置错误导致的@RequestBody异状

@RequestBody拿不到数据，首要怀疑对象一定是请求的Content-Type。如果你用的工具是Postman，确实很方便：Body选项卡里选raw，格式选JSON，工具会自动设置Content-Type: application/json。但前后端联调时，如果前端把数据以JSON字符串丢给了body，而请求头没有设置Content-Type，很多浏览器和HTTP客户端会默认走application/x-www-form-urlencoded，这时候@RequestBody就找不到能用的HttpMessageConverter，后果通常是415 Unsupported Media Type或者参数绑定的对象里全是null。

解决这类问题，在后端可以加一层兜底校验：服务端在进入业务逻辑之前，校验Content-Type，不是预期的类型就直接返回友好的错误提示。但更根本的还是把接口文档写清楚，明确告知调用方："此接口只接受application/json格式的请求体"。如果你的接口同时需要文件上传和JSON数据，会涉及@RequestPart和@RequestParam("file") MultipartFile的组合，这是另一个话题，但思路还是一样的：数据源在哪，就用哪个注解去接。

7.4 多个注解混用时的注意事项

实际项目中一个接口方法里混用多个参数注解是很常见的，比如路径里俩变量、Query里有分页参数、body里又带JSON对象。这种情况下要注意几个规则：第一，@RequestBody只能有一个；第二，参数顺序不是问题，Spring会根据注解类型自动绑定；第三，合理控制参数数量，超过四个以上我建议把Query参数封装成对象参数。不过这里我得澄清一句：Spring MVC对自定义对象参数会自动做字段级数据绑定，对象参数和上面的几个注解并不冲突，它只是简化了多个@RequestParam的写法。

另一个我实际见过的坑是：方法签名里同时写了@RequestParam("userName") String userName和@RequestBody UserDTO user，结果前端把userName放进了JSON body里，而不是Query里，导致userName这类参数始终是null。前后端各说各话，最后一看，对接口语义的理解出了偏差。解决这类问题的核心其实不在于注解怎么配，而在于接口文档对齐。参数放在哪一层、数据源是什么，必须在设计阶段定清楚。

7.5 关于参数注解的团队规范建议

最后分享一点团队协作的经验。代码review阶段，我一般会重点检查几个和参数注解相关的习惯：一是非必填是否显式标注required = false或defaultValue，避免其他开发误以为必填；二是参数命名是否和前端字段一致，不一致的要加注释；三是接口文档和代码同步更新，尤其是参数增减时。这几点看着都是小事，但实际上能省下大量联调和排查的时间。

另外，如果你的团队接口有全局的响应包装和异常处理，一定要把参数绑定异常统一拦截并转化成可读的提示，不要直接抛一堆Spring内部异常结构给前端。@RestControllerAdvice配合@ExceptionHandler处理MissingServletRequestParameterException、MethodArgumentTypeMismatchException、HttpMessageNotReadableException，这是大项目的标配。

我个人实际用下来最深的体会就是：参数注解本身不难，难的是理解每个注解背后的数据来源和边界。把HTTP请求当成一条流水线，路径参数、查询参数、请求头、Cookie、body、request attribute各占一个工位，任何参数都一定能找到它对应的工位。搞清这件事，写Controller时会顺畅很多，排查问题时也能少走弯路。