核心控制器注解

这些注解用于定义一个类作为请求处理器（即 Controller）。

@Controller

• 作用: 将一个普通的 Java 类声明为 Spring MVC 的控制器，Spring 容器会扫描并管理这个类的实例。
• 位置: 类上方。
• 特点: 它本身是一个 @Component，因此可以被 Spring 容器扫描并注册为 Bean，它通常与 @RequestMapping 结合使用。

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
@Controller
public class HelloController {
    @RequestMapping("/hello")
    public String sayHello() {
        return "hello"; // 返回视图名，视图解析器会解析为 /WEB-INF/views/hello.jsp
    }
}

@RestController

• 作用: 这是 @Controller 和 @ResponseBody 的组合注解，从 Spring 4.0 开始引入，专门用于开发 RESTful API。
• 位置: 类上方。
• 特点: 标记了此注解的 Controller 中所有方法的返回值都会直接作为 HTTP 响应体返回，而不是解析为视图名，非常适合前后端分离的项目。

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class UserController {
    @GetMapping("/api/users/1")
    public User getUser() {
        // 这个返回的对象会被自动转换成 JSON 或 XML 格式
        return new User(1L, "张三", "zhangsan@example.com");
    }
}
// User 是一个简单的 POJO
class User {
    private Long id;
    private String name;
    private String email;
    // 构造器、Getter 和 Setter...
}

请求映射注解

这些注解用于将 HTTP 请求映射到 Controller 的具体方法上。

@RequestMapping

• 作用: 将 HTTP 请求映射到 Controller 的处理方法上，它可以作用在类和方法上。
• 位置: 类或方法上方。
• 常用属性:
  • value (或 path): 请求的 URL 路径。
  • method: 指定支持的 HTTP 方法 (如 RequestMethod.GET, RequestMethod.POST)。
  • params: 指定请求中必须包含的参数。
  • headers: 指定请求中必须包含的 Header。
  • consumes: 指定请求的 Content-Type (如 application/json)。
  • produces: 指定返回的 Content-Type (如 application/json)。

// 作用在类上，相当于所有方法路径的前缀
@Controller
@RequestMapping("/admin")
public class AdminController {
    // 匹配 GET 请求 /admin/dashboard
    @RequestMapping(value = "/dashboard", method = RequestMethod.GET)
    public String dashboard() {
        return "admin/dashboard";
    }
    // 匹配 POST 请求 /admin/user，且必须有 id 参数
    @RequestMapping(value = "/user", method = RequestMethod.POST, params = "id")
    public String addUser() {
        return "redirect:/admin/users";
    }
}

@GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping

• 作用: 它们是 @RequestMapping 的简化形式，专门用于指定 HTTP 方法，从 Spring 4.3 开始引入，使代码更简洁、更具可读性。
• 位置: 方法上方。
• 特点: 只能用于方法上，不能用于类上（除非与类上的 @RequestMapping 组合）。

@RestController
@RequestMapping("/api/products")
public class ProductController {
    // 等同于 @RequestMapping(value = "/list", method = RequestMethod.GET)
    @GetMapping("/list")
    public List<Product> listProducts() {
        // ...
        return productService.findAll();
    }
    // 等同于 @RequestMapping(value = "/create", method = RequestMethod.POST)
    @PostMapping("/create")
    public String createProduct(@RequestBody Product product) {
        // ...
        productService.save(product);
        return "Product created successfully";
    }
}

请求参数绑定注解

这些注解用于将 HTTP 请求中的参数、路径变量、请求头等信息绑定到方法的参数上。

@RequestParam

• 作用: 将请求参数绑定到方法参数上。
• 位置: 方法参数前。
• 常用属性:
  • value: 请求参数的名称。
  • required: 参数是否必须，默认为 true。
  • defaultValue: 参数的默认值。

@GetMapping("/search")
public String search(
    @RequestParam("q") String keyword,      // 绑定 q 参数到 keyword
    @RequestParam(value = "page", defaultValue = "1") int page, // 绑定 page 参数，默认为1
    @RequestParam(value = "size", required = false) Integer size // 绑定 size 参数，非必须
) {
    // ...
    return "search results for " + keyword + " on page " + page;
}
// 请求示例: /search?q=spring&page=2

@PathVariable

• 作用: 将 URL 中的路径变量绑定到方法参数上，常用于 RESTful 风格的 URL。
• 位置: 方法参数前。
• 常用属性:
  • value: 路径变量的名称。

@GetMapping("/users/{id}")
public String getUserById(@PathVariable("id") Long userId) {
    // ...
    return "User details for ID: " + userId;
}
// 请求示例: /users/123
// userId 的值将是 123L

@RequestBody

• 作用: 将 HTTP 请求的体（body）绑定到方法参数上，通常用于接收 JSON 或 XML 数据。
• 位置: 方法参数前。
• 特点: Spring 会使用 HttpMessageConverter (如 MappingJackson2HttpMessageConverter) 将请求体自动转换成 Java 对象。

@PostMapping("/users")
public String createUser(@RequestBody User user) {
    // ...
    userService.save(user);
    return "User created: " + user.getName();
}
// 请求体示例 (JSON):
// {
//   "name": "李四",
//   "email": "lisi@example.com"
// }
// user 参数将是一个包含 name 和 email 的 User 对象。

@RequestHeader

• 作用: 将请求头信息绑定到方法参数上。
• 位置: 方法参数前。
• 常用属性:
  • value: 请求头的名称。

@GetMapping("/info")
public String getInfo(@RequestHeader("User-Agent") String userAgent,
                      @RequestHeader(value = "Accept-Encoding", required = false) String acceptEncoding) {
    // ...
    return "Your browser is: " + userAgent;
}

@CookieValue

• 作用: 将 Cookie 中的值绑定到方法参数上。
• 位置: 方法参数前。
• 常用属性:
  • value: Cookie 的名称。

@GetMapping("/welcome")
public String welcome(@CookieValue("JSESSIONID") String sessionId) {
    // ...
    return "Welcome! Your session ID is: " + sessionId;
}

响应处理注解

@ResponseBody

• 作用: 将方法的返回值直接作为 HTTP 响应体返回，而不是进行视图解析。
• 位置: 方法或类上（@RestController 已包含此注解）。
• 特点: 通常返回 JSON、XML 或纯文本数据，Spring 同样会使用 HttpMessageConverter 进行转换。

@Controller
public class DataController {
    @GetMapping("/data")
    @ResponseBody  // 返回的 "Hello World" 字符串将直接作为响应体
    public String getData() {
        return "Hello World";
    }
}

@ResponseStatus

• 作用: 在方法执行后，设置 HTTP 响应状态码。
• 位置: 方法或异常处理类上。
• 常用属性:
  • value: HTTP 状态码 (如 HttpStatus.CREATED)。

@PostMapping("/users")
@ResponseStatus(HttpStatus.CREATED) // 返回 201 Created 状态码
public User createUser(@RequestBody User user) {
    // ...
    return userService.save(user);
}

异常处理注解

@ExceptionHandler

• 作用: 定义一个方法来处理 Controller 中抛出的特定类型的异常。
• 位置: 方法上，通常放在 @ControllerAdvice 注解的类中。
• 特点: 实现了全局异常处理，避免了在代码中写大量的 try-catch。

import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.servlet.ModelAndView;
@ControllerAdvice
public class GlobalExceptionHandler {
    // 处理所有 IllegalArgumentException
    @ExceptionHandler(IllegalArgumentException.class)
    public ModelAndView handleIllegalArgument(IllegalArgumentException ex) {
        ModelAndView mav = new ModelAndView("error"); // 跳转到错误页面
        mav.addObject("errorMsg", ex.getMessage());
        return mav;
    }
    // 处理所有其他异常
    @ExceptionHandler(Exception.class)
    public ModelAndView handleAllException(Exception ex) {
        ModelAndView mav = new ModelAndView("error");
        mav.addObject("errorMsg", "系统发生未知错误，请联系管理员");
        return mav;
    }
}

其他重要注解

@ModelAttribute

• 作用: 有两个主要用途：
  1. 放在方法上: 在请求处理方法执行之前，先执行此方法，并将方法的返回值存入 Model 对象中，常用于准备表单数据。
  2. 放在参数上: 从 Model 中获取数据并绑定到方法参数上。

@Controller
@RequestMapping("/profile")
public class ProfileController {
    // 在所有 /profile/* 请求处理之前执行
    @ModelAttribute("currentUser")
    public User getCurrentUser() {
        // 模拟从 Session 或数据库获取当前登录用户
        return userService.findCurrentUser();
    }
    @GetMapping
    public String showProfile(@ModelAttribute("currentUser") User user) {
        // user 参数已经被填充
        return "profile";
    }
}

@SessionAttributes

• 作用: 将 Model 中的数据暂存到 HttpSession 中，多个请求之间可以共享。
• 位置: 类上。

@Controller
@SessionAttributes("user") // 将名为 "user" 的模型属性存入 Session
public class LoginController {
    @GetMapping("/login")
    public String loginForm(Model model) {
        model.addAttribute("user", new User()); // 将 User 对象存入 Model
        return "login";
    }
    @PostMapping("/login")
    public String login(@ModelAttribute User user, Model model) {
        // 验证逻辑...
        if (user.isValid()) {
            model.addAttribute("user", user); // 存入 Model，由于 @SessionAttributes，它也会被存入 Session
            return "redirect:/home";
        }
        return "login";
    }
}

@ControllerAdvice 和 @RestControllerAdvice

• 作用: 定义一个全局的控制器增强类，可以用于：
  • @ExceptionHandler: 全局异常处理。
  • @InitBinder: 全局数据绑定。
  • @ModelAttribute: 全局数据预处理。

// 全局异常处理 + 全局数据预处理
@ControllerAdvice
public class GlobalControllerAdvice {
    // 异常处理... (同上)
    // 全局数据预处理
    @InitBinder
    public void initBinder(WebDataBinder binder) {
        // 禁止绑定 id 字段，防止恶意用户通过 POST 请求修改 ID
        binder.setDisallowedFields("id");
    }
    // 全局数据预处理
    @ModelAttribute("websiteName")
    public String websiteName() {
        return "我的网站";
    }
}

掌握这些注解是使用 Spring MVC 进行 Web 开发的基础，它们共同构成了一个声明式、灵活且强大的 Web 框架。