reggie-annotations

瑞吉外卖项目注解总结

整理了项目中实际出现的所有注解，按功能分组，标注了作用和什么时候用。

---

一、Lombok（实体/公共类通用）

注解	作用	什么时候用
@Data	自动生成 getter、setter、toString、equals、hashCode、构造器	任何 POJO 类（Entity、DTO、VO、R、Properties 配置类）都能用，消除样板代码
@Slf4j	自动注入 log 对象，直接写 log.info()	任何需要打印日志的类，Controller / Service / Filter / 配置类都常用

项目位置：所有的 Entity、DTO、R<T>、AliyunSmsProperties → @Data；Controller / Service / Filter / Config → @Slf4j

---

二、Spring Boot 核心（启动类）

注解	作用	什么时候用
@SpringBootApplication	组合注解：@Configuration + @EnableAutoConfiguration + @ComponentScan，标识主启动类	每个 Spring Boot 项目的入口类，且只能有一个
@ServletComponentScan	扫描 @WebFilter、@WebServlet、@WebListener 原生 Servlet 注解	项目中使用了 @WebFilter 做过滤器时，必须在启动类开启扫描
@EnableTransactionManagement	开启声明式事务注解 @Transactional	当项目使用 @Transactional 管理事务时，启动类加上它才能生效

项目位置：ReggieApplication.java

---

三、Configuration & Bean 管理

注解	作用	什么时候用
@Configuration	标识一个类为配置类，替代 XML 配置文件	需要注册多个 @Bean 或重写框架方法时（如 WebMvcConfig、MybatisPlusConfig、阿里云短信配置）
@Bean	将方法返回值注册为 Spring 容器管理的 Bean	需要手动实例化第三方对象交给 Spring 管理（如 MybatisPlusInterceptor、阿里云 Client）
@Component	将类注册为 Spring 普通组件	工具类、自动填充处理器等非三层（Controller/Service/Mapper）的组件
@ConditionalOnMissingBean	当容器中没有该类型 Bean 时才创建	防止重复创建 Bean，通常跟在 @Bean 上面做兜底保护
@ConfigurationProperties(prefix = "xxx")	将 yaml 中以某前缀开头的属性批量绑定到 POJO 字段	自定义配置参数较多时（如 aliyun.sms.endpoint、aliyun.sms.signName 等）
@EnableConfigurationProperties(Xxx.class)	启用 @ConfigurationProperties 绑定的类的注册	在有 @Configuration 的类上配合使用，让配置类生效
@Value("${xxx:default}")	注入 yaml 中单个属性的值	只需要取一个配置值时（如 reggie.path），比写一个完整的 @ConfigurationProperties 类更轻量

项目位置：

• @Configuration → WebMvcConfig、MybatisPlusConfig、AliyunSMSConfiguration
• @Bean → MybatisPlusConfig.mybatisPlusInterceptor()、AliyunSMSConfiguration.aliyunSmsClient()
• @Component → MyMetaObjectHandler
• @ConfigurationProperties → AliyunSmsProperties
• @EnableConfigurationProperties → AliyunSMSConfiguration
• @Value → CommonController.basePath

---

四、Controller 层（请求映射）

注解	作用	什么时候用
@RestController	@Controller + @ResponseBody，类中所有方法默认返回 JSON	后端提供 RESTful JSON API 时，每个 Controller 都用它
@RequestMapping("/xxx")	定义类级别的请求 URL 前缀，method 可省略	一个模块的所有接口共享同一个路径前缀（如 /employee、/dish、/category）
@GetMapping	处理 GET 请求	查询类操作（分页查询、单个查询、页面回显）
@PostMapping	处理 POST 请求	新增操作（新增员工、新增菜品、登录、提交订单、上传文件）
@PutMapping	处理 PUT 请求	修改操作（修改员工信息、修改菜品、更新套餐、设置默认地址）
@DeleteMapping	处理 DELETE 请求	删除操作（删除菜品、清空购物车）
@PathVariable	将 URL 模板中的 {id} 绑定到方法参数	接口需要从 URL 中获取资源 ID 时（如 /dish/{dishId}、/employee/{id}）
@RequestBody	将请求体中的 JSON 字符串反序列化为 Java 对象	POST/PUT 请求，前端传复杂 JSON 结构时（新增员工、新增菜品、下单等）
@RequestParam	将 URL 查询参数或表单参数绑定到方法参数	批量操作传 ID 列表（如 @RequestParam List<Long> ids），或显式指明参数名时
@ResponseBody	将方法返回值直接写入 HTTP 响应体（JSON）	@RestController 已包含，通常不需要单独写；但它可以配合 @ControllerAdvice 用在异常处理器上

项目位置：所有的 Controller 类 + GlobalExceptionHandler

---

五、Service 层

注解	作用	什么时候用
@Service	标识 Service 实现类为 Spring Bean（业务层组件）	每个 Service 实现类都要加，让 Spring 扫描并注入
@Transactional	声明式事务：方法内所有数据库操作要么全成功要么全回滚	操作涉及多张表，必须保证数据一致性时（新增菜品+口味、下单、批量删除）
@Autowired	按类型注入 Spring Bean（Spring 原生）	最常用的依赖注入方式，Service/Controller 中注入其他 Bean
@Resource	按名称注入 Spring Bean（JSR-250 标准）	功能与 @Autowired 类似，按名称注入更明确，配置类中常用
@Lazy	延迟初始化，解决循环依赖	两个 Service 互相注入时（如 DishServiceImpl ↔ CategoryServiceImpl），在其中一个上加 @Lazy 打破循环

项目位置：所有 ServiceImpl 类

---

六、MyBatis-Plus（持久层）

注解	作用	什么时候用
@Mapper	标识 Mapper 接口，让 MyBatis 扫描到它	每个 Mapper 接口都要加（项目中没有使用 @MapperScan，而是逐个加 @Mapper）
@TableField(fill = FieldFill.INSERT)	插入时自动填充该字段	实体字段需要自动填充值时（如 createTime、createUser），配合 MetaObjectHandler 实现
@TableField(fill = FieldFill.INSERT_UPDATE)	插入和更新时都自动填充该字段	实体字段需要每次变更都自动维护时（如 updateTime、updateUser）

项目位置：

• @Mapper → 所有 *Mapper.java 接口
• @TableField → 所有 Entity 类中的 createTime、updateTime、createUser、updateUser 字段

---

七、过滤器

注解	作用	什么时候用
@WebFilter(filterName = "xxx", urlPatterns = "/*")	声明一个过滤器，拦截指定 URL 模式	需要做统一的请求预处理（登录校验、编码设置、日志记录、跨域处理等）

注意：@WebFilter 是 Servlet 3.0 原生注解，需要在启动类上加 @ServletComponentScan 才能被扫描到。

项目位置：LoginCheckFilter

---

八、异常处理

注解	作用	什么时候用
@ControllerAdvice(annotations = {RestController.class, Controller.class})	全局增强所有 Controller，可以指定只对特定注解生效	统一处理所有 Controller 抛出的异常，避免到处写 try-catch
@ExceptionHandler(XxxException.class)	标识方法用于处理指定类型的异常	针对不同异常类型写不同的处理逻辑（如 SQL 约束异常、自定义业务异常）

项目位置：GlobalExceptionHandler

---

九、Java 标准

注解	作用	什么时候用
@Override	标识方法重写父类或接口方法	任何重写父类/接口方法时都要加，编译器会帮你检查签名是否正确

项目位置：MetaObjectHandler、LoginCheckFilter、WebMvcConfig、所有 ServiceImpl 等

---

十、作用对象速查

类级别   → @SpringBootApplication / @Configuration / @Component / @Service
             @RestController / @ControllerAdvice / @WebFilter / @ConfigurationProperties
             类上面的 @Mapper / @Data / @Slf4j

方法级别  → @Bean / @GetMapping / @PostMapping / @PutMapping / @DeleteMapping
             @Transactional / @ExceptionHandler / @Override

参数级别  → @RequestBody / @PathVariable / @RequestParam / @Value / @Autowired / @Resource

字段级别  → @Autowired / @Resource / @Value / @TableField