@ControllerAdvice 是 Spring Boot 中用于统一处理 Controller 层异常、模型属性和请求参数的核心注解；支持 @ExceptionHandler 统一异常响应、@ModelAttribute 注入公共数据、@InitBinder 预处理参数，并可通过 assignableTypes 和 @Order 精确控制作用范围与执行顺序。

@ControllerAdvice 是 Spring Boot 中用于统一处理 Controller 层逻辑的核心注解，主要解决异常处理、数据预绑定和模型属性共享三类问题。它不是写在某个 Controller 里，而是独立成类，自动作用于所有 @Controller 或 @RestController 方法，避免重复代码。

统一处理异常（最常用）

用 @RestControllerAdvice（推荐前后端分离项目）或 @ControllerAdvice 配合 @ExceptionHandler，捕获并格式化返回异常信息。

• 优先捕获具体异常，如 NullPointerException、IllegalArgumentException，再兜底处理 Exception
• 方法返回值建议用统一结构（如 Result<T>），生产环境不要暴露堆栈详情
• 加 @ResponseStatus 可直接设置 HTTP 状态码，比如 400、500

为所有接口注入公共模型数据

用 @ModelAttribute 注解方法，让每个 Controller 接口都能自动获得预设的参数或对象。

Java Maven Common

Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。

下载

• 方法返回 Map、对象或基本类型，会自动加入 Model
• 可指定 name 属性自定义 key，例如 @ModelAttribute(name = "userInfo")
• 适合放通用配置、用户登录态、系统版本等前端可能需要的只读信息

统一绑定和校验请求参数

用 @InitBinder 预处理请求参数，比如日期格式转换、字符串 trim、全局参数过滤等。

• 方法参数必须是 WebDataBinder 类型
• 可注册自定义 PropertyEditor 或 Converter，例如把 "2026-10-10" 自动转为 LocalDate
• 避免在每个 Controller 里重复写 binder.registerCustomEditor(...)

使用注意点

这个注解本质是 Spring 的 Bean，所以要确保类能被组件扫描到（通常放在主启动类同包或子包下）。

• 若只对部分 Controller 生效，可用 assignableTypes 属性限定目标类，例如 @ControllerAdvice(assignableTypes = {LoginController.class})
• 多个 @ControllerAdvice 类按类名排序执行，顺序敏感时可加 @Order 控制优先级
• @RestControllerAdvice = @ControllerAdvice + @ResponseBody，返回 JSON 更简洁，无需每个方法加注解