2024最新超详细SpringMvc常用注解总结

SpringMVC常用注解

控制器（Controller）相关注解：

1.@Controller

@Controller 注解用于标识一个类为 Spring MVC 的控制器，它能够处理用户的请求并返回相应的视图或数据。通常与 @RequestMapping 注解一起使用，以定义请求的处理方法和映射路径。

2.@RestController

@RestController 是 Spring MVC 中的一个注解，结合了 @Controller 和 @ResponseBody 的功能，用于定义 RESTful 风格的控制器。它通常用于返回 JSON 或 XML 格式的数据，而不是直接渲染视图。@Controller 负责接收请求并将其分发到相应的处理方法，而 @ResponseBody 负责将处理方法的返回值转换为指定格式的响应数据。

 1.使用示例

@RestController
public class HelloRestController {@GetMapping("/hello")public String hello() {return "Hello, welcome to RESTful Controller!";}
}

 @RestController 标注了 HelloController 类，使其成为一个 RESTful 风格的控制器。方法返回的字符串会直接作为 HTTP 响应体的内容返回给客户端，而不会被视图解析器处理。

2.响应格式

@ResponseBody 通常用于返回复杂对象或集合，Spring MVC 会自动将其转换为 JSON 或 XML 格式的响应数据。示例：

@RestController
public class UserController {@GetMapping("/users")public List<User> getUsers() {List<User> users = new ArrayList<>();users.add(new User(1, "Alice"));users.add(new User(2, "Bob"));return users;}static class User {private int id;private String name;// Constructor, getters and setters// 省略构造函数、getter和setter方法}
}

在这个示例中，UserController 返回了一个包含用户信息的列表，Spring MVC 会自动将其转换为 JSON 格式的响应数据。  

请求映射相关注解

1.@RequestMapping

@RequestMapping 是 Spring MVC 中用于映射 HTTP 请求到具体处理方法的注解。它可以用在类级别或方法级别，用来指定请求的 URL 路径、HTTP 方法以及其他请求条件。

使用方式：

1.类级别的@RequestMapping：

在类级别使用 @RequestMapping 可以定义处理器类的根请求映射。例如：

@RestController
@RequestMapping("/api")
public class ApiController {}

上面的例子中，@RestController 声明了这是一个 REST 控制器，而 @RequestMapping("/api") 则指定了这个控制器处理的根路径为 /api。

2.方法级别的@RequestMapping：

在方法级别使用 @RequestMapping 可以进一步定义具体请求路径和请求方法。例如：

@RestController
@RequestMapping("/api")
public class ApiController {@RequestMapping(value = "/hello", method = RequestMethod.GET)public String helloGet() {return "Hello GET!";}@RequestMapping(value = "/hello", method = RequestMethod.POST)public String helloPost() {return "Hello POST!";}
}

上面的例子中，helloGet() 方法处理 /api/hello 的 GET 请求，而 helloPost() 方法处理同样路径的 POST 请求。通过 value 属性指定路径，通过 method 属性指定 HTTP 方法。 

2.@GetMapping @PostMapping @PutMapping@DeleteMapping

当使用Spring MVC构建Web应用程序时，可以使用以下注解来处理不同类型的HTTP请求： @GetMapping、@PostMapping、@PutMapping和@DeleteMapping。这些注解分别对应HTTP方法GET、POST、PUT和DELETE，并使得编写和阅读控制器方法更加直观和语义化。

在实际开发中，选择合适的HTTP方法注解（如 @GetMapping、@PostMapping、@PutMapping、@DeleteMapping）取决于你的业务需求和RESTful API设计原则。

1. GET请求 (@GetMapping):

   • 用途: 用于从服务器获取资源或数据。
   • 示例: 获取资源列表、获取单个资源的详情。
   • 特点: GET请求应该是幂等的，即重复调用多次不会造成状态变更或副作用。

2. POST请求 (@PostMapping):

   • 用途: 用于在服务器上创建新资源。
   • 示例: 创建新的资源、提交表单数据。
   • 特点: POST请求可能会引起服务器状态的变更，每次提交可能产生不同的结果。

3. PUT请求 (@PutMapping):

   • 用途: 用于更新服务器上的资源。
   • 示例: 更新已有资源的信息、全量更新资源。
   • 特点: PUT请求应该是幂等的，即多次提交相同的数据不会产生不同的结果，通常用于完全替换资源。

4. DELETE请求 (@DeleteMapping):

   • 用途: 用于删除服务器上的资源。
   • 示例: 删除指定的资源、清理不需要的数据。
   • 特点: DELETE请求应该是幂等的，即多次删除同一个资源应该具有相同的结果。

选择合适的方法注解时，需要考虑以下几点：

• RESTful API设计原则: 遵循RESTful API的设计规范，合理使用GET、POST、PUT、DELETE方法来对资源进行操作。
• 幂等性: GET和DELETE请求本身就是幂等的，而POST和PUT请求需要设计成幂等操作，以确保多次操作不会导致意外的副作用。
• 安全性: 敏感操作如删除资源通常使用DELETE请求，而不是GET请求，以防止意外操作。
• 请求体: POST和PUT请求通常需要请求体（@RequestBody），用于传递参数和数据。

@RestController
@RequestMapping("/api/products")
public class ProductController {// GET请求示例：获取所有产品列表@GetMapping("/list")public ResponseEntity<List<Product>> listProducts() {List<Product> productList = productService.getAllProducts();return ResponseEntity.ok(productList);}// GET请求示例：根据ID获取产品详情@GetMapping("/{id}")public ResponseEntity<Product> getProductById(@PathVariable Long id) {Product product = productService.getProductById(id);if (product != null) {return ResponseEntity.ok(product);} else {return ResponseEntity.notFound().build();}}// POST请求示例：创建新产品@PostMapping("/create")public ResponseEntity<String> createProduct(@RequestBody Product product) {productService.createProduct(product);return ResponseEntity.ok("Product created successfully");}// PUT请求示例：更新产品信息@PutMapping("/update/{id}")public ResponseEntity<String> updateProduct(@PathVariable Long id, @RequestBody Product updatedProduct) {boolean updated = productService.updateProduct(id, updatedProduct);if (updated) {return ResponseEntity.ok("Product updated successfully");} else {return ResponseEntity.notFound().build();}}// DELETE请求示例：删除产品@DeleteMapping("/delete/{id}")public ResponseEntity<String> deleteProduct(@PathVariable Long id) {boolean deleted = productService.deleteProduct(id);if (deleted) {return ResponseEntity.ok("Product deleted successfully");} else {return ResponseEntity.notFound().build();}}// 业务逻辑可以替换为真实的服务方法实现private ProductService productService;public ProductController(ProductService productService) {this.productService = productService;}
}

参数处理注解：

1.@RequestParam

在Web开发中，@RequestParam 注解用于从HTTP请求中获取请求参数的值。具体来说，它可以用来获取URL查询参数或表单提交的参数值。

使用方式：

1.基本用法：

@GetMapping("/example")
public ResponseEntity<String> handleRequest(@RequestParam("date") String date) {// 处理逻辑，使用从请求中获取的 date 参数值return ResponseEntity.ok("Received date parameter: " + date);
}

 > @RequestParam("date") 表示从请求中获取名为 "date" 的参数的值，并将其赋给方法中的 date 参数。

2.可选参数:

@GetMapping("/example")
public ResponseEntity<String> handleRequest(@RequestParam(value = "date", required = false) String date) {if (date != null) {// 处理逻辑，使用从请求中获取的 date 参数值return ResponseEntity.ok("Received date parameter: " + date);} else {return ResponseEntity.badRequest().body("Date parameter is required");}
}

 > 在这个例子中，通过设置 required = false，使得 date 参数变为可选的。如果请求中没有提供 date 参数，方法可以根据需要处理这种情况。

3.默认值：

@GetMapping("/example")
public ResponseEntity<String> handleRequest(@RequestParam(value = "date", defaultValue = "20240101") String date) {// 处理逻辑，使用从请求中获取的 date 参数值；如果请求中没有提供该参数，则使用默认值 "20240627"return ResponseEntity.ok("Received date parameter: " + date);
}

 >  在这个例子中，通过 defaultValue = "20240627" 设置了一个默认值，如果请求中没有提供 date 参数，将使用默认值。

4.多个参数：

@GetMapping("/example")
public ResponseEntity<String> handleRequest(@RequestParam("date") String date,@RequestParam("type") String type) {// 处理逻辑，使用从请求中获取的 date 和 type 参数值return ResponseEntity.ok("Received date parameter: " + date + ", type parameter: " + type);
}

>  这个例子展示了如何同时获取多个参数值，每个 @RequestParam 对应请求中的一个参数。

2.@PathVariable

用于从URI模板中提取变量值并将其绑定到处理方法的参数中。

1.用法

@PathVariable 可以用于方法参数，表示方法参数的值来自于请求URI中的某个部分。

可以指定参数名称，也可以省略，默认情况下会自动匹配同名参数。

可以通过required属性来指定该参数是否为必需。

2.示例

@RestController
@RequestMapping("/users")
public class UserController {@GetMapping("/{id}")public ResponseEntity<User> getUserById(@PathVariable("id") Long userId) {// 根据用户ID获取用户信息的逻辑User user = userService.findById(userId);return ResponseEntity.ok(user);}
}

在这个例子中，@PathVariable("id") 将URL路径中的id部分提取出来并赋值给userId参数，例如，/users/123 会将123作为userId的值。 

 3.默认参数名称

@RestController
@RequestMapping("/products")
public class ProductController {@GetMapping("/{productId}")public ResponseEntity<Product> getProductById(@PathVariable Long productId) {// 根据产品ID获取产品信息的逻辑Product product = productService.findById(productId);return ResponseEntity.ok(product);}
}

在这个例子中，@PathVariable 注解中没有指定参数名称，Spring会自动匹配路径变量和方法参数名称，{productId} 会被绑定到 productId 参数上。 

4.多个 @PathVariable

@RestController
@RequestMapping("/orders")
public class OrderController {@GetMapping("/{orderId}/items/{itemId}")public ResponseEntity<Item> getOrderItem(@PathVariable("orderId") Long orderId, @PathVariable("itemId") Long itemId) {// 根据订单ID和项目ID获取项目信息的逻辑Item item = orderService.findItemByOrderIdAndItemId(orderId, itemId);return ResponseEntity.ok(item);}
}

在这个例子中，有两个@PathVariable注解，它们从URI路径中提取orderId和itemId，例如，/orders/123/items/456 会将 123 作为 orderId 的值，将 456 作为 itemId 的值。

5.可选参数

默认情况下，@PathVariable 是必需的。如果路径变量是可选的，可以使用 required 属性：

@RestController
@RequestMapping("/files")
public class FileController {@GetMapping("/{directory}/{filename}")public ResponseEntity<String> getFile(@PathVariable("directory") String directory,@PathVariable(value = "filename", required = false) String filename) {// 处理逻辑if (filename != null) {return ResponseEntity.ok("Received file: " + directory + "/" + filename);} else {return ResponseEntity.ok("Received directory: " + directory);}}
}

 在这个例子中，filename 是一个可选参数，若未提供filename路径变量，则该参数值为null。

3.@RequestBody

@RequestBody 是Spring MVC中的一个注解，用于将HTTP请求体中的内容绑定到方法的参数上。它通常用于处理POST、PUT等请求方法，以便从请求体中获取JSON、XML或其他格式的数据，并将其转换为Java对象。

 用法

• @RequestBody 注解用于告诉Spring MVC，将请求体的内容转换为方法参数所需的对象。
• Spring MVC使用HttpMessageConverter进行数据转换，例如，使用MappingJackson2HttpMessageConverter来处理JSON数据。
• 适用于POST、PUT、DELETE等请求方法。

 1.基本用法：

@RestController
@RequestMapping("/users")
public class UserController {@PostMapping("/create")public ResponseEntity<User> createUser(@RequestBody User user) {// 处理逻辑，保存用户信息userService.save(user);return ResponseEntity.ok(user);}
}

 在这个例子中，@RequestBody 注解将请求体中的JSON数据转换为User对象，并传递给createUser方法。

 2.接受复杂对象：

@RestController
@RequestMapping("/orders")
public class OrderController {@PostMapping("/submit")public ResponseEntity<Order> submitOrder(@RequestBody Order order) {// 处理逻辑，保存订单信息orderService.save(order);return ResponseEntity.ok(order);}
}

在这个例子中，@RequestBody 注解将请求体中的JSON数据转换为Order对象。请求体可能包含嵌套的对象，如订单项（OrderItem）等，Spring会自动处理这些复杂对象的转换。 

3.处理XML数据

如果请求体包含XML数据，可以通过配置HttpMessageConverter来处理：

@RestController
@RequestMapping("/products")
public class ProductController {@PostMapping("/add")public ResponseEntity<Product> addProduct(@RequestBody Product product) {// 处理逻辑，保存产品信息productService.save(product);return ResponseEntity.ok(product);}
}

 在这个例子中，假设配置了适当的HttpMessageConverter（如MappingJackson2XmlHttpMessageConverter），Spring会将请求体中的XML数据转换为Product对象。

4.结合验证注解

import javax.validation.Valid;@RestController
@RequestMapping("/customers")
public class CustomerController {@PostMapping("/register")public ResponseEntity<Customer> registerCustomer(@Valid @RequestBody Customer customer) {// 处理逻辑，保存客户信息customerService.save(customer);return ResponseEntity.ok(customer);}
}

在这个例子中，@Valid 注解用于验证Customer对象中的字段。如果验证失败，Spring会抛出验证异常并返回相应的错误信息。

5.处理列表数据

@RestController
@RequestMapping("/items")
public class ItemController {@PostMapping("/batchAdd")public ResponseEntity<List<Item>> addItems(@RequestBody List<Item> items) {// 处理逻辑，保存多个项目信息itemService.saveAll(items);return ResponseEntity.ok(items);}
}

在这个例子中，@RequestBody 注解将请求体中的JSON数组数据转换为List<Item>对象。 

4.@RequestHeader

@RequestHeader 是 Spring MVC 中的一个注解，用于将 HTTP 请求头中的信息绑定到方法的参数上。它允许开发者从请求头中获取特定的信息，如认证信息、内容类型等。

 1.基本用法

@RestController
@RequestMapping("/books")
public class BookController {@GetMapping("/info")public ResponseEntity<String> getBookInfo(@RequestHeader("User-Agent") String userAgent) {// 处理逻辑，根据 User-Agent 获取书籍信息return ResponseEntity.ok("User-Agent header: " + userAgent);}
}

 在这个例子中，@RequestHeader("User-Agent") 将请求头中名为 "User-Agent" 的值绑定到方法参数 userAgent 上。

2.可选的请求头参数

@RestController
@RequestMapping("/orders")
public class OrderController {@GetMapping("/status")public ResponseEntity<String> getOrderStatus(@RequestHeader(value = "Authorization", required = false) String authorization) {if (authorization != null) {// 处理逻辑，根据 Authorization 获取订单状态return ResponseEntity.ok("Authorization header: " + authorization);} else {return ResponseEntity.badRequest().body("Authorization header is not present");}}
}

在这个例子中，@RequestHeader(value = "Authorization", required = false) 允许 authorization 参数是可选的。如果请求中没有提供 "Authorization" 请求头，方法可以根据需要处理这种情况。

3.默认值

@RestController
@RequestMapping("/products")
public class ProductController {@GetMapping("/info")public ResponseEntity<String> getProductInfo(@RequestHeader(value = "Accept-Language", defaultValue = "en-US") String acceptLanguage) {// 处理逻辑，根据 Accept-Language 获取产品信息；如果请求中没有提供该请求头，则使用默认值 "en-US"return ResponseEntity.ok("Accept-Language header: " + acceptLanguage);}
}

 在这个例子中，@RequestHeader(value = "Accept-Language", defaultValue = "en-US") 设置了默认值为 "en-US"。如果请求中没有提供 "Accept-Language" 请求头，将使用默认值。

4.处理多个请求头

@RestController
@RequestMapping("/items")
public class ItemController {@GetMapping("/details")public ResponseEntity<String> getItemDetails(@RequestHeader("Accept") String acceptHeader,@RequestHeader("Cache-Control") String cacheControlHeader) {// 处理逻辑，根据 Accept 和 Cache-Control 获取商品详细信息return ResponseEntity.ok("Accept header: " + acceptHeader + ", Cache-Control header: " + cacheControlHeader);}
}

 在这个例子中，@RequestHeader 注解可以多次使用，将不同请求头的值绑定到方法的不同参数上。

其他常用注解

1.@ResponseBody

@ResponseBody 是Spring框架中的一个注解，通常用于控制器方法上，用于指示方法的返回值应该直接作为HTTP响应正文（ResponseBody）返回，而不是通过视图解析器进行渲染。它可以用于RESTful API开发中，特别是返回JSON或XML格式的数据。

1.作用

1.将对象直接作为响应体返回: 当方法使用 @ResponseBody 注解后，Spring框架会将方法的返回值，如Java对象或集合，转换为指定格式（如JSON/XML）的响应数据，并直接写入HTTP响应

2.简化开发: 省去了手动设置响应头、编码数据等操作，简化了开发流程。

3.支持多种数据格式: 支持返回JSON、XML等多种数据格式，根据请求头中的Accept属性进行内容协商。

 2.示例

@Controller
@RequestMapping("/users")
public class UserController {@GetMapping("/{id}")@ResponseBodypublic User getUserById(@PathVariable Long id) {// 假设这里从数据库或其他地方获取了用户对象User user = userRepository.findById(id);return user; // 返回的User对象将自动转换为JSON格式}
}

 当访问 /users/{id} 路径时，控制器会根据id查询用户，并直接将用户对象转换为JSON格式返回给客户端，而不需要额外的视图解析器或模板引擎来处理。

2.@ResponseStatus

@ResponseStatus 是Spring框架中的一个注解，用于将特定的HTTP状态码应用到控制器方法或异常处理器方法上。它允许开发者明确指定当特定条件满足时应该返回的HTTP状态码，从而控制HTTP响应的状态。

1.作用

1.指定成功或失败的HTTP状态码: 可以将成功或失败的情况与相应的HTTP状态码关联起来，使得API的设计更加规范和符合RESTful风格。

2.简化异常处理: 可以将特定异常与适当的HTTP状态码关联，从而简化异常处理过程。

 2.示例

@Controller
@RequestMapping("/books")
public class BookController {@GetMapping("/{id}")@ResponseStatus(HttpStatus.OK)public ResponseEntity<Book> getBookById(@PathVariable Long id) {// 假设根据id查询书籍Book book = bookService.findById(id);if (book != null) {return ResponseEntity.ok(book);} else {throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Book not found");}}
}

 在这个例子中，@ResponseStatus(HttpStatus.OK) 指示当成功找到书籍时，返回HTTP状态码200（OK）。如果没有找到书籍，则抛出 ResponseStatusException 异常，这将触发Spring默认的异常处理机制，返回HTTP状态码404（NOT FOUND）。

在异常处理器方法中使用 @ResponseStatus

@ControllerAdvice
public class GlobalExceptionHandler {@ResponseStatus(HttpStatus.BAD_REQUEST)@ExceptionHandler(MethodArgumentNotValidException.class)public ResponseEntity<Object> handleValidationException(MethodArgumentNotValidException ex) {// 处理方法参数验证异常，并返回适当的响应Map<String, Object> body = new HashMap<>();body.put("timestamp", LocalDateTime.now());body.put("message", "Validation error");// 添加其他自定义的错误信息return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(body);}
}

在这个例子中，@ExceptionHandler(MethodArgumentNotValidException.class) 捕获了 MethodArgumentNotValidException 异常，然后通过 @ResponseStatus(HttpStatus.BAD_REQUEST) 指示当发生这种异常时，应返回HTTP状态码400（BAD REQUEST）。同时，使用 ResponseEntity 构建了一个包含错误信息的响应体。