当前位置： 首页 > news >正文

Web层注解

news 2025/6/26 14:34:43
注解名称所属模块功能描述引入年份版本是否推荐使用分类
@RequestParamspring-webmvcHTTP请求参数绑定到方法参数2004Spring 1.0推荐参数绑定
@PathVariablespring-webmvc提取 URI 中的路径变量2009Spring 3.0推荐参数绑定
@RequestBodyspring-webmvc将请求体反序列化为对象（如 JSON/XML）2009Spring 3.0推荐参数绑定
@CookieValuespring-webmvc获取 Cookie 值2009Spring 3.0推荐参数绑定
@RequestHeaderspring-webmvc获取请求头信息2009Spring 3.0推荐参数绑定
@MatrixVariablespring-webmvc支持 URL 矩阵变量解析2013Spring 3.2推荐（RESTful API 可选）参数绑定
@RequestMappingspring-webmvc映射 HTTP 请求到控制器方法（支持所有 HTTP 方法）2004Spring 1.0推荐（但建议优先使用更具体的注解）请求映射
@GetMappingspring-webmvc映射 HTTP GET 请求2015Spring 4.3推荐（语义清晰）请求映射
@PostMappingspring-webmvc映射 HTTP POST 请求2015Spring 4.3推荐请求映射
@PutMappingspring-webmvc映射 HTTP PUT 请求2015Spring 4.3推荐请求映射
@PatchMappingspring-webmvc映射 HTTP PATCH 请求2015Spring 4.3推荐请求映射
@DeleteMappingspring-webmvc映射 HTTP DELETE 请求2015Spring 4.3推荐请求映射
@ResponseStatusspring-webmvc设置 HTTP 响应状态码2009Spring 3.0推荐返回处理
@ResponseBodyspring-webmvc将返回值序列化为响应体（如 JSON/XML）2009Spring 3.0推荐（常用于 REST 控制器）返回处理
@InitBinderspring-webmvc初始化 WebDataBinder，用于自定义数据绑定2004Spring 1.0推荐（用于参数格式化）全局处理与异常
@ExceptionHandlerspring-webmvc处理控制器内的异常2009Spring 3.0推荐（配合 @ControllerAdvice 使用）全局处理与异常
@ControllerAdvicespring-webmvc全局异常处理和数据绑定2013Spring 3.2推荐全局处理与异常
@SessionAttributesspring-webmvc在会话中存储模型属性2004Spring 1.0不推荐（Spring Boot 中不推荐使用）其他功能
@CrossOriginspring-webmvc启用跨域请求支持2015Spring 4.2推荐（开发环境可用，生产建议配置 CORS Filter）其他功能

参数绑定

[Q&A] @RequestParam 引入背景
在早期的 Java Web 开发中（如使用 Servlet API），开发者需要通过 HttpServletRequest 手动获取请求参数：

String name = request.getParameter("name");

为了提升开发效率和代码可读性，Spring 在其 Web 模块中引入了 @RequestParam 注解，使得控制器方法可以直接声明参数并自动绑定请求值。

[Q&A] @PathVariable 引入背景
在 RESTful 风格的 Web API 设计中，URL 通常包含具有语义的路径变量（Path Variable），例如：

/products/456/details → 代表资源 ID 或其他关键信息

在 Spring 3.0 之前，开发者需要通过 HttpServletRequest 手动解析路径变量，为了解决这些问题，Spring 在 3.0 版本 中引入了 @PathVariable 注解，使得控制器方法可以直接声明路径变量作为方法参数，并由框架自动完成绑定。

[Q&A] @RequestBody 引入背景
在 Spring 3.0 之前，开发者如果想从请求体中读取数据（例如处理 POST 请求中的 JSON 数据），需要手动操作 HttpServletRequest 的输入流，并使用第三方库（如 Jackson、Gson）进行反序列化：

BufferedReader reader = request.getReader();
String json = reader.readLine();
User user = new ObjectMapper().readValue(json, User.class);

为了简化这一过程，提高开发效率和可维护性，Spring 在 3.0 版本 中引入了 @RequestBody 注解，配合 HttpMessageConverter 接口，实现了自动将请求体内容转换为 Java 对象的能力。

[Q&A] @CookieValue 引入背景
在 Web 开发中，Cookie 是客户端与服务端之间维持状态的一种常见机制，在早期的 Servlet 开发中，开发者需要手动从 HttpServletRequest 获取 Cookie，并遍历查找目标 Cookie 值：

Cookie[] cookies = request.getCookies();
if (cookies != null) {for (Cookie cookie : cookies) {if ("auth_token".equals(cookie.getName())) {String token = cookie.getValue();// 使用 token...}}
}

为了解决这些问题，Spring 在 3.0 版本中引入了 @CookieValue 注解，使得控制器方法可以直接声明要获取的 Cookie 名称，并由框架自动注入对应的值。

[Q&A] @RequestHeader引入背景
在传统的 Web 开发中，HTTP 请求头（Request Headers）是客户端与服务端通信的重要组成部分，常用于传递元信息，在 Spring 3.0 之前，开发者需要手动从 HttpServletRequest 中获取请求头信息：

String contentType = request.getHeader("Content-Type");

为了解决这些问题，Spring 在 3.0 版本中引入了 @RequestHeader 注解，使得控制器方法可以直接声明要获取的请求头名称，并由框架自动注入对应的值。

[Q&A] @MatrixVariable 引入背景
HTTP URI 中的 Matrix 参数是什么？
Matrix参数是一种在 URI 路径段中嵌入键值对的方式。它不是查询参数（Query Parameters），而是直接出现在路径段中，格式如下：

/bookstore;color=red;price=100

color=red 和 price=100 是两个 Matrix 参数。它们属于路径段 /bookstore，而不是整个 URL 的查询字符串。
在没有 @MatrixVariable 之前，开发者需要手动解析 URI 或使用 HttpServletRequest 获取原始 URI 并拆分路径段，代码复杂且容易出错。

String uri = request.getRequestURI();
// 手动解析 matrix 参数...

请求映射

[Q&A] @RequestMapping 引入背景
在 Spring 2.5 之前，开发者通常通过以下方式处理 HTTP 请求：
1、实现 Controller 接口（如 AbstractController、SimpleFormController 等）

public class HelloController implements Controller {public ModelAndView handleRequest(HttpServletRequest request, HttpServletResponse response) {// 处理逻辑}
}

2、在 XML 配置文件中定义 URL 映射关系

<bean name="/hello.htm" class="com.example.HelloController"/>

为了解决上述问题，Spring Framework 2.5 引入了基于注解的控制器编程模型，其中 @RequestMapping 是最核心的注解之一。

[Q&A] @GetMapping @PostMapping @PutMapping @DeleteMapping @PatchMapping 引入背景
在 Spring 4.3 之前，开发者需要使用 @RequestMapping 并指定 method = RequestMethod.XXX 来限制请求方法：

@RequestMapping(value = "/users", method = RequestMethod.GET)
public String listUsers() {return "user-list";
}

为了解决这些问题，Spring Framework 4.3 引入了这些专门的注解，使代码更加语义化和简洁。

注解适用场景是否常用所属模块功能引入年份版本是否推荐使用返回状态码（常规）返回值介绍（默认行为）
@GetMapping查询资源✔️ 高频使用spring-webmvc映射 HTTP GET 请求2015Spring 4.3✔️ 推荐（语义清晰）200 OK（成功查询）通常返回 JSON/XML 或视图渲染结果（视配置而定）
@PostMapping创建资源✔️ 高频使用spring-webmvc映射 HTTP POST 请求2015Spring 4.3✔️ 推荐201 Created（成功创建）可返回新增资源详情（如 ID、完整数据）
@PutMapping全量更新✔️ 中高频spring-webmvc映射 HTTP PUT 请求2015Spring 4.3✔️ 推荐200 OK（更新成功）/ 204 No Content（无内容返回）返回更新后完整资源或空（按需设计）
@PatchMapping部分更新⚠️ 视需求而定spring-webmvc映射 HTTP PATCH 请求2015Spring 4.3✔️ 推荐（需 REST 规范场景）200 OK（更新成功）通常返回部分更新后的资源片段或状态确认
@DeleteMapping删除资源✔️ 高频使用spring-webmvc映射 HTTP DELETE 请求2015Spring 4.3✔️ 推荐204 No Content（删除成功，无内容返回）一般无返回体（或返回删除确认消息）

返回处理

[Q&A] @ResponseStatus 引入背景
在传统的 MVC 应用中，通常只关注页面跳转或简单的成功/失败响应，HTTP 状态码的作用并不突出。但随着 RESTful API 的普及，客户端（如前端、移动端）越来越依赖于明确的 HTTP 状态码来判断请求结果，例如：
200 OK：成功获取资源
201 Created：资源创建成功
404 Not Found：资源不存在
500 Internal Server Error：服务端异常
因此，Spring 需要一种更清晰的方式来为每个控制器方法指定返回的状态码。
在没有 @ResponseStatus 之前，开发者需要通过 HttpServletResponse 或 ResponseEntity 手动设置状态码，这会增加代码复杂度，降低可读性。

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {return new ResponseEntity<>(userService.save(user), HttpStatus.CREATED);
}

而使用 @ResponseStatus 可以将状态码语义直接绑定到方法上，提升代码简洁性和可维护性。

[Q&A] @ResponseBody 引入背景
在传统的 Spring MVC 应用中，控制器方法通常返回的是视图名称（如 JSP 页面），例如：

@GetMapping("/users")
public String listUsers(Model model) {model.addAttribute("users", userService.findAll());return "userList"; // 返回视图名
}

但随着前端框架（如 Vue、React、Angular）的发展，前端和后端逐渐分离，后端只需提供数据接口（JSON 格式），不再负责页面渲染。在没有 @ResponseBody 之前，开发者需要手动将对象转为 JSON 字符串并写入 HttpServletResponse：

@GetMapping("/users")
public void getAllUsers(HttpServletResponse response) throws IOException {List<User> users = userService.findAll();String json = new ObjectMapper().writeValueAsString(users);response.getWriter().write(json);
}

这种方式繁琐且容易出错，所以引入了 @ResponseBody。
@ResponseBody 告诉 Spring：“这个方法返回的数据不是视图名，而是直接写入 HTTP 响应体的内容。”
Spring 会根据客户端请求头中的 Accept 内容选择合适的 HttpMessageConverter（如 Jackson 来处理数据格式，比如：
application/json → Jackson
application/xml → JAXB 或 Jackson XML 扩展

全局处理与异常

[Q&A] @InitBinder 引入背景
@InitBinder 是为了解决：Spring 自动绑定参数时，有些数据你希望它“按你的规则”来处理，而不是 Spring 默认的方式。比如：
1、把 “2024-03-15” 转成 Date 类型
2、不允许绑定 isAdmin 字段
3、给这个对象加一个验证器（比如检查 name 是否为空）

[Q&A] @ExceptionHandler 引入背景
在没有 @ExceptionHandler 之前，开发者通常会在每个控制器方法中使用 try-catch 来处理异常：

@GetMapping("/user/{id}")
public String getUser(@PathVariable Long id, Model model) {try {User user = userService.findById(id);model.addAttribute("user", user);return "user-detail";} catch (UserNotFoundException ex) {model.addAttribute("error", "用户不存在");return "error-page";}
}

典型用法

spring-webmvc @RequestParam 典型用法
spring-webmvc @PathVariable 典型用法
spring-webmvc @RequestBody 典型用法
spring-webmvc @CookieValue 典型用法
spring-webmvc @RequestHeader 典型用法
spring-webmvc @MatrixVariable 典型用法
spring-webmvc @RequestMapping @GetMapping @PostMapping @PutMapping @DeleteMapping @PatchMapping 典型用法
spring-webmvc @ResponseStatus 典型用法
spring-webmvc @ResponseBody 典型用法
spring-webmvc @InitBinder 典型用法

http://www.lryc.cn/news/575200.html

相关文章：

  • python学习笔记（深度学习）
  • FPGA基础 -- Verilog 格雷码（Gray Code）计数器设计与原理解析
  • 【网站内容安全检测】之3：获取所有外部域名访问后图像
  • ABP VNext + Ocelot API 网关：微服务统一入口与安全策略
  • Boosting：从理论到实践——集成学习中的偏差征服者
  • webman 利用tcp 做服务端 对接物联网
  • 机器学习×第十五卷：集成学习下篇——她开始构建每一轮更接近你的贴靠路径(XGBoost)
  • 基于STM32的个人健康助手的设计
  • Containerd 容器技术
  • 基于Hp感染的慢性胃炎居家管理小程序的设计与实现（消息震动）
  • LVS-DR负载均衡群集深度实践：高性能架构设计与排障指南
  • 鸿蒙OpenHarmony[Disassembler反汇编工具]ArkTS运编译工具链
  • vue3递归组件的使用
  • LVS-NAT负载均衡群集实战：原理、部署与问题排查
  • Vue计算属性与监视属性
  • 机器人 “离线觉醒” ？ 摆脱人类“控制”！Google DeepMind 优化 AI 让机器人断网不断智！
  • spring项目启动sheel脚本
  • 如何打造Apache Top-Level开源时序数据库IoTDB
  • 北斗导航 | 基于CNN-LSTM-PSO算法的接收机自主完好性监测算法
  • 服务器开放端口如何设置，本地内网开通应用端口让外网访问连接步骤
  • Fisco Bcos学习 - 控制台搭建和基本使用
  • 在ASP.NET Core WebApi中使用标识框架（Identity)
  • 网络安全漏洞扫描是什么？如何识别目标进行扫描？
  • 通用 Excel 导出功能设计与实现：动态列选择与灵活配置
  • 国道观察者手记
  • React + Umi（Umijs/Max） 搭建项目及配置
  • 大学专业科普 | 物联网、自动化和人工智能
  • 多服务器IP白名单配置(使用redis stream实现)
  • 神经网络的运作方式类比讲解
  • 【EI会议征稿】东北大学主办第三届机器视觉、图像处理与影像技术国际会议（MVIPIT 2025）