Spring MVC 的常用注解

一、控制器相关注解

@Controller

@Controller注解用于标记一个类为 Spring MVC 的控制器。在 Spring MVC 框架里，控制器扮演着关键角色，负责接收 HTTP 请求并返回响应。当一个类被@Controller注解标记后，Spring 容器会自动识别并将其纳入管理。例如：

@Controller
public class UserController {// 控制器方法将在这里定义
}

@RestController

@RestController是一个组合注解，它融合了@Controller和@ResponseBody的功能。与传统的@Controller不同，@RestController专门用于构建 RESTful Web 服务。在使用@RestController注解的类中，所有方法的返回值会直接作为响应体返回给客户端，无需再进行视图解析。这使得开发 RESTful 接口变得异常简洁高效，例如：

@RestController
public class UserRestController {@GetMapping("/users/{id}")public User getUserById(@PathVariable Long id) {// 从数据库或其他数据源获取用户信息User user = userService.getUserById(id);return user;}
}

@RequestMapping

@RequestMapping是 Spring MVC 中用于映射 Web 请求到特定处理器方法的核心注解。它可以作用于类级别和方法级别。在类级别使用时，定义了该控制器的基础路径；在方法级别使用时，则定义了具体的 URL 模式映射。例如：

@Controller
@RequestMapping("/users")
public class UserController {@RequestMapping(value = "/{id}", method = RequestMethod.GET)public String getUserById(@PathVariable Long id, Model model) {User user = userService.getUserById(id);model.addAttribute("user", user);return "userDetails";}
}

在上述示例中，@RequestMapping("/users")定义了UserController的基础路径为/users，而@RequestMapping(value = "/{id}", method = RequestMethod.GET)则映射了一个 GET 请求到getUserById方法，路径为/users/{id}。

@GetMapping、@PostMapping、@PutMapping、@DeleteMapping、@PatchMapping

这些注解分别对应 HTTP 的 GET、POST、PUT、DELETE、PATCH 请求方法，是@RequestMapping的快捷方式。它们使得代码更加清晰易读，明确表示了方法所处理的请求类型。例如：

@RestController
@RequestMapping("/products")
public class ProductController {@GetMapping("/{id}")public Product getProductById(@PathVariable Long id) {return productService.getProductById(id);}@PostMappingpublic Product createProduct(@RequestBody Product product) {return productService.createProduct(product);}@PutMapping("/{id}")public Product updateProduct(@PathVariable Long id, @RequestBody Product product) {return productService.updateProduct(id, product);}@DeleteMapping("/{id}")public void deleteProduct(@PathVariable Long id) {productService.deleteProduct(id);}
}

二、请求参数绑定注解

@RequestParam

@RequestParam注解用于将 HTTP 请求中的参数绑定到控制器方法的参数上。它适用于 GET 和 POST 请求中的查询参数或表单字段。例如：

@Controller
@RequestMapping("/search")
public class SearchController {@GetMappingpublic String searchProducts(@RequestParam String keyword, Model model) {List<Product> products = productService.searchProducts(keyword);model.addAttribute("products", products);return "searchResults";}
}

在这个例子中，@RequestParam String keyword将请求中的keyword参数绑定到searchProducts方法的keyword参数上。

@PathVariable

@PathVariable注解用于从 URI 模板中提取变量，并将其绑定到方法参数上，常用于 RESTful 风格的 URL 设计。例如：

@RestController
@RequestMapping("/orders")
public class OrderController {@GetMapping("/{orderId}")public Order getOrderById(@PathVariable Long orderId) {return orderService.getOrderById(orderId);}
}

在上述代码中，@PathVariable Long orderId从/orders/{orderId}这样的 URL 路径中提取orderId变量，并将其传递给getOrderById方法。

@RequestBody

@RequestBody注解用于将 HTTP 请求体的内容反序列化成 Java 对象，通常与 JSON 或 XML 格式的数据一起使用。在处理 POST 或 PUT 请求时，当请求体中包含复杂数据结构时，@RequestBody注解尤为重要。例如：

@RestController
@RequestMapping("/users")
public class UserController {@PostMappingpublic User createUser(@RequestBody User user) {return userService.createUser(user);}
}

这里，客户端发送的 JSON 格式的用户信息会被自动反序列化为User对象，并传递给createUser方法。

@RequestHeader

@RequestHeader注解用于获取 HTTP 请求头信息并绑定到方法参数上。例如，要获取请求中的Authorization头信息：

@Controller
@RequestMapping("/protected")
public class ProtectedController {@GetMappingpublic String getProtectedResource(@RequestHeader String Authorization) {// 根据授权信息进行业务处理return "protectedResource";}
}

@CookieValue

@CookieValue注解用于获取 Cookie 值并绑定到方法参数上。例如：

@Controller
@RequestMapping("/user")
public class UserProfileController {@GetMappingpublic String getUserProfile(@CookieValue("JSESSIONID") String sessionId) {// 根据会话ID获取用户信息return "userProfile";}
}

三、返回值处理注解

@ResponseBody

@ResponseBody注解表示该方法的返回结果应直接写入 HTTP 响应体中，而不是解析为视图名。在构建 RESTful 服务时，它常与@RestController一起使用。例如：

@Controller
public class JsonController {@ResponseBody@GetMapping("/data")public List<DataObject> getData() {return dataService.getData();}
}

@ModelAttribute

@ModelAttribute注解有两个主要用途：一是将数据添加到模型中，供视图使用；二是用于方法参数，接收来自表单提交的数据并绑定到对象上。例如：

@Controller
@RequestMapping("/form")
public class FormController {@GetMappingpublic String showForm(Model model) {model.addAttribute("user", new User());return "form";}@PostMappingpublic String submitForm(@ModelAttribute User user) {userService.saveUser(user);return "redirect:/success";}
}

在上述代码中，@ModelAttribute User user在submitForm方法中接收表单提交的数据，并自动绑定到User对象上。

四、数据验证注解

@Valid 和 @Validated

@Valid和@Validated注解用于触发 JSR - 303/JSR - 380（Bean Validation API）的验证机制，确保传入的数据符合预定义的规则。@Valid通常直接用于方法参数上，而@Validated可以用于类、方法和参数上，并且支持分组验证。例如：

@RestController
@RequestMapping("/users")
public class UserController {@PostMappingpublic User createUser(@Valid @RequestBody User user) {return userService.createUser(user);}
}

@Size、@Min、@Max、@NotNull、@Email 等

这些是具体的验证注解，用于对字段进行约束检查。例如，使用@Size注解限制字符串长度：

public class User {@NotNullprivate String username;@Size(min = 6, max = 20)private String password;@Emailprivate String email;// 省略getter和setter方法
}

在这个User类中，username字段不能为空，password字段长度必须在 6 到 20 之间，email字段必须符合邮箱格式。

五、拦截器和异常处理注解

@ExceptionHandler

@ExceptionHandler注解用于定义全局异常处理方法，可以捕获并处理特定类型的异常。例如：

@ControllerAdvice
public class GlobalExceptionHandler {@ExceptionHandler(NotFoundException.class)public ResponseEntity<String> handleNotFoundException(NotFoundException ex) {return ResponseEntity.status(HttpStatus.NOT_FOUND).body("Resource not found: " + ex.getMessage());}
}

@ControllerAdvice

@ControllerAdvice注解用于定义全局的异常处理逻辑或数据绑定逻辑，可以应用于所有控制器。它使得代码中的异常处理更加集中和统一，提高了代码的可维护性。

六、其他常用注解

@SessionAttributes

@SessionAttributes注解用于指定哪些模型属性应该存储在 HTTP 会话中，以便跨多个请求保持状态。

@Controller
@SessionAttributes("user")
public class UserSessionController {@GetMapping("/login")public String login(Model model) {model.addAttribute("user", new User());return "login";}@PostMapping("/login")public String doLogin(@ModelAttribute User user, SessionStatus sessionStatus) {if (userService.validateUser(user)) {sessionStatus.setComplete();return "redirect:/home";} else {return "login";}}
}

@CrossOrigin

@CrossOrigin注解用于启用跨域资源共享（CORS），允许前端应用从不同源访问后端 API。在前后端分离的项目中，该注解非常有用。例如：

@RestController
@RequestMapping("/api")
@CrossOrigin(origins = "http://localhost:3000")
public class ApiController {// API方法定义
}

在上述代码中，@CrossOrigin(origins = "http://localhost:3000")允许来自http://localhost:3000的前端应用访问该控制器的 API。

       Spring MVC 中的这些常用注解为开发者提供了强大而灵活的工具，极大地简化了 Web 应用程序的开发过程。通过合理使用这些注解，我们能够更加高效地构建功能丰富、易于维护的 Web 应用。