SpringBoot企业级实战项目—云禾外卖—SpringBoot常用注解解析

苍穹外卖

范围：sky-common + sky-pojo + sky-server 全部 86 个 Java 文件

实际用到 24 种注解，分 8 大类整理

---

0. 速查总表

注解	来源	核心作用	使用格式（位置 + 参数）
@Data	Lombok	编译期自动生成 getter/setter/toString/equals/hashCode，消除实体类模板代码	标注在类上；无必填参数
@NoArgsConstructor	Lombok	生成无参构造方法	标注在类 上；无必填参数；常与@AllArgsConstructor成对出现
@AllArgsConstructor	Lombok	生成全参构造方法	标注在类 上；无必填参数；使用后默认无参构造会失效，必须配合@NoArgsConstructor
@Builder	Lombok	生成建造者模式，支持链式调用构建对象	标注在类上；无必填参数；建议配合构造器注解一起使用
@Slf4j	Lombok	自动生成日志对象 log，无需手动声明 Logger	标注在类 上；无必填参数；类内直接调用 log.info() 等方法
@SpringBootApplication	Spring Boot	启动类标记，三合一注解：配置类 + 自动装配 + 组件扫描	标注在项目启动类上；无必填参数；全局唯一
@EnableTransactionManagement	Spring	开启注解式事务管理，使 @Transactional 注解生效	标注在启动类 / 配置类上；无必填参数
@Configuration	Spring	标记该类为配置类，等价于传统 XML 配置文件	标注在类 上；无必填参数；通常配合 @Bean 一起使用
@Bean	Spring	将方法的返回值注册为 Spring IoC 容器中的 Bean	标注在方法上；无必填参数；用于注册第三方 Jar 中的类，方法返回值为目标对象
@Component	Spring	通用组件注解，将类交给 Spring IoC 容器管理	标注在类上；无必填参数；不属于标准三层架构的通用类使用
@Service	Spring	业务层组件注解，是 @Component 的业务层语义化别名	标注在业务层实现类上；无必填参数
@Autowired	Spring	按类型自动依赖注入，从容器中匹配对应 Bean 并赋值	标注在成员变量 / 构造方法 /setter 方法上；无必填参数；默认按类型匹配
@RestController	Spring MVC	REST 风格控制器，方法返回值直接序列化为 JSON 写入响应体	标注在控制层类 上；无必填参数；等价于 @Controller + @ResponseBody
@RequestMapping	Spring MVC	配置 URL 请求映射路径	标注在类 / 方法 上；必填参数 value/path 指定 URL 路径；类上为全局前缀，方法上为子路径
@PostMapping	Spring MVC	映射 POST 类型的 HTTP 请求	标注在方法 上；必填参数 value 指定路径；是 @RequestMapping(method = POST) 的简写
@RequestBody	Spring MVC	将请求体中的 JSON 自动反序列化为 Java 对象	标注在方法参数上；无必填参数；配合 POST 请求使用
@RestControllerAdvice	Spring MVC	全局异常处理增强，统一拦截所有 Controller 抛出的异常	标注在异常处理类上；无必填参数
@ExceptionHandler	Spring MVC	指定当前方法捕获处理的异常类型	标注在异常处理方法上；必填参数为异常的 Class 类型
@ConfigurationProperties	Spring Boot	批量绑定 yml 配置中指定前缀的配置项，映射为 Java 对象	标注在类 上；必填参数 prefix 指定配置前缀；需配合 @Component 使用
@Mapper	MyBatis	标记接口为 MyBatis 映射接口，运行时自动生成代理实现类	标注在Mapper 接口上；无必填参数
@Select	MyBatis	注解式编写 SQL 查询语句	标注在Mapper 接口方法 上；必填参数 value 为 SQL 语句；用 #{字段名} 做预编译占位符
@JsonFormat	Jackson	JSON 序列化 / 反序列化时，统一日期格式转换	标注在日期类型字段 上；常用参数 pattern 指定格式、timezone 指定时区；用于请求 / 响应体 JSON
@DateTimeFormat	Spring	URL 参数 / 表单提交时，统一日期格式转换	标注在日期类型字段 / 方法参数 上；必填参数 pattern 指定格式；用于 GET 请求参数
@ApiModel	Swagger	给实体类 / DTO 添加接口文档描述	标注在DTO / 实体类 上；常用参数 description 添加类说明
@ApiModelProperty	Swagger	给类的字段添加接口文档描述	标注在成员变量 上；常用参数 value 添加字段说明

1. Lombok 注解 ------ POJO 四件套 + 日志

1.1 @Data（用了 55 处，全场最多）

作用 ：编译期自动生成 getter、setter、toString()、equals()、hashCode()，彻底干掉模板代码。

项目用法 （sky-pojo/entity/Employee.java）：

@Data
public class Employee {
    private Long id;
    private String username;
    private String name;
    private String password;
    // 不用写任何 getter/setter，直接 employee.getUsername() 就能用
}

---

1.2 @NoArgsConstructor / @AllArgsConstructor（30+31 处）

作用：分别生成无参构造器和全参构造器。

为什么必须配着用（重要）：

• Java 规则：一旦手写了任何构造器，JVM 就不再送默认无参构造
• @AllArgsConstructor 算 "手写了构造器"
• Spring 反序列化（@RequestBody 转 POJO）必须有无参构造，缺了直接炸
• 所以写全参就必须补 @NoArgsConstructor，两个一起写才安全

项目用法：

@Data
@NoArgsConstructor      // 反序列化需要（@RequestBody / MyBatis 映射）
@AllArgsConstructor     // 快速构造完整对象
public class Category { ... }

---

1.3 @Builder（28 处）

作用：生成建造者，支持链式调用构造对象。

项目用法：

Employee emp = Employee.builder()
        .username("admin")
        .name("管理员")
        .build();

好处：可读性高、参数多也不容易传错顺序、可选参数可以只设部分字段。

---

1.4 @Slf4j（6 处：启动类 / Controller / Service / 拦截器 / 配置类 / 工具类）

作用 ：自动生成 private static final Logger log = LoggerFactory.getLogger(X.class);，类里直接用 log.info(...)。

项目用法 （SkyApplication.java）：

@Slf4j
public class SkyApplication {
    public static void main(String[] args) {
        SpringApplication.run(SkyApplication.class, args);
        log.info("server started");   // 直接用 log，不用手动声明
    }
}

---

2. Spring 核心注解

2.1 @SpringBootApplication（1 处，启动类）

作用 ：三合一 ------ @Configuration（配置类）+ @EnableAutoConfiguration（自动装配）+ @ComponentScan（扫描 com.sky 包下所有组件）。

项目用法 （SkyApplication.java）：

@SpringBootApplication
@EnableTransactionManagement   // 开启注解方式的事务管理
@Slf4j
public class SkyApplication { ... }

注 ：@EnableTransactionManagement 让 @Transactional 注解生效；Spring Boot 2.x 之后默认已开启，写出来是为了语义明确（教学项目里特意写上）。

---

2.2 @Component / @Service（5+1 处）

作用 ：都表示 "把这个类交给 Spring IoC 容器管理"，@Service 是 @Component 在业务层 的语义化别名。同理还有 @Repository（数据层）、@Controller（Web 层）。

项目用法：

@Service                      // EmployeeServiceImpl ------ 业务层
public class EmployeeServiceImpl implements EmployeeService { ... }

@Component                    // JwtTokenAdminInterceptor ------ 不属于三层，用通用注解
public class JwtTokenAdminInterceptor implements HandlerInterceptor { ... }

---

2.3 @Autowired（5 处）

作用：自动按类型（byType）从容器中找到匹配的 Bean 注入进来；接口类型会自动注入其实现类对象。

项目用法 （EmployeeController.java）：

@Autowired   // 注入 EmployeeService 的实现类 EmployeeServiceImpl
private EmployeeService employeeService;
@Autowired   // 注入配置类对象，读取 application.yml 里 sky.jwt 的配置
private JwtProperties jwtProperties;

---

2.4 @Configuration + @Bean（各 1 处）

作用：

• @Configuration 标记这是个配置类，相当于一个 XML 配置文件
• @Bean 标记在方法上，方法返回值 会被注册进 IoC 容器（专门用于引入第三方 jar 里的类，因为你没法在别人源码上加 @Component）

项目用法 （WebMvcConfiguration.java）：

@Configuration
public class WebMvcConfiguration extends WebMvcConfigurationSupport {
    @Bean   // Docket 是 springfox 的类，加不了注解，只能用 @Bean 注册
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder().title("苍穹外卖项目接口文档").build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

记忆点 ：自己写的类 → @Component；第三方 jar 里的类 → @Bean。

---

3. Web 层注解

3.1 @RestController + @RequestMapping（EmployeeController.java）

作用：

• @RestController = @Controller + @ResponseBody：方法返回值直接序列化成 JSON 写进响应体，不再跳转视图
• @RequestMapping("/admin/employee")：给整个类所有接口统一加 URL 前缀

@RestController
@RequestMapping("/admin/employee")   // 本类所有接口都以这个为前缀
public class EmployeeController { ... }

3.2 @PostMapping + @RequestBody

作用：

• @PostMapping("/login")：把 POST 请求映射到方法，完整路径 = 类前缀 + 方法路径 = /admin/employee/login
• @RequestBody：把请求体的 JSON 自动反序列化成 DTO 对象

@PostMapping("/login")
public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO) {
    // 前端发 {"username":"admin","password":"123456"}
    // → 自动变成 employeeLoginDTO.getUsername() 可用
}

同族注解 （本项目暂未用到，后续模块会出现）：@GetMapping / @PutMapping / @DeleteMapping，以及取参数用的 @PathVariable、@RequestParam。

---

4. 全局异常处理：@RestControllerAdvice + @ExceptionHandler

项目用法 （handler/GlobalExceptionHandler.java）：

@RestControllerAdvice    // 全局拦截所有 Controller 抛出的异常
@Slf4j
public class GlobalExceptionHandler {
    @ExceptionHandler    // 参数类型 BaseException → 专门捕获这类异常
    public Result exceptionHandler(BaseException ex) {
        log.error("异常信息：{}", ex.getMessage());
        return Result.error(ex.getMessage());   // 统一格式返回错误
    }
}

好处 ：业务代码里直接 throw new PasswordErrorException("密码错误")，不需要每个方法都 try-catch，前端拿到的错误格式也统一。

---

5. 配置绑定组合拳：@Component + @ConfigurationProperties（3 处）

作用 ：把 application.yml 中某一段配置批量映射成一个 Java 对象。

项目用法 （sky-common/properties/JwtProperties.java）：

@Component                                  // 交给 Spring 管理
@ConfigurationProperties(prefix = "sky.jwt") // 绑定 yml 的 sky.jwt 段
@Data
public class JwtProperties {
    private String adminSecretKey;   // ← sky.jwt.admin-secret-key
    private long adminTtl;           // ← sky.jwt.admin-ttl
    private String adminTokenName;   // ← sky.jwt.admin-token-name
}

对应 application.yml：

sky:
  jwt:
    admin-secret-key: itcast
    admin-ttl: 7200000
    admin-token-name: token

记忆点 ：松散绑定 ------ yml 里的 admin-secret-key（短横线）自动映射到 adminSecretKey（驼峰）。@Value("${sky.jwt.admin-secret-key}") 只能一个一个取，@ConfigurationProperties 一次绑定一整段，前缀统一、字段多时必用它。

项目里同样套路的还有：AliOssProperties（sky.alioss）、WeChatProperties（sky.wechat`）。

---

6. MyBatis 注解

6.1 @Mapper

作用 ：标记接口为 MyBatis 的映射接口，运行时 MyBatis 会自动生成代理实现类并注入 Spring 容器，不用写 impl。

@Mapper
public interface EmployeeMapper {
    @Select("select * from employee where username = #{username}")
    Employee getByUsername(String username);
}

6.2 @Select / @Insert / @Update / @Delete

作用 ：注解方式直接写 SQL，#{} 是预编译占位符（防 SQL 注入）。

取舍 ：简单 SQL 用注解；动态 SQL（<if> <foreach>）只能用 XML。本项目后期复杂查询都会转到 resources/mapper/*.xml。

---

7. 日期格式化：@JsonFormat vs @DateTimeFormat

	@JsonFormat	@DateTimeFormat
框架	Jackson	Spring
处理的是	请求体 JSON ↔ Java 对象	URL 参数 / 表单 ↔ Java 对象
典型场景	POST 的 @RequestBody	GET 的 query string

项目用法：

// sky-pojo/dto/OrdersSubmitDTO.java ------ JSON 请求体里的日期
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss")
private LocalDateTime orderTime;

// sky-pojo/dto/OrdersPageQueryDTO.java ------ URL 参数里的日期（分页查询 ?beginTime=...）
@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
private LocalDateTime beginTime;

---

8. Swagger 接口文档：@ApiModel / @ApiModelProperty

作用 ：给 knife4j /swagger 接口文档（/doc.html）的模型和字段写说明，纯文档用途，不影响逻辑。

项目用法 （EmployeeLoginDTO.java）：

@ApiModel(description = "员工登录时传递的数据模型")
@Data
public class EmployeeLoginDTO {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

---

9. 组合套路总结

场景	组合	项目例子
POJO 四件套	@Data + @Builder + @NoArgsConstructor + @AllArgsConstructor	所有 entity / DTO / VO
启动类	@SpringBootApplication + @EnableTransactionManagement + @Slf4j	SkyApplication
控制器	@RestController + @RequestMapping("前缀") + @Slf4j + 方法上 @PostMapping + @RequestBody	EmployeeController
业务层	@Service + @Autowired 注入 Mapper	EmployeeServiceImpl
数据层	@Mapper（接口）+ @Select 简单 SQL	EmployeeMapper
配置类	@Configuration + @Bean（第三方对象）	WebMvcConfiguration
配置绑定	@Component + @ConfigurationProperties(prefix) + @Data	JwtProperties / WeChatProperties / AliOssProperties
拦截器 / 工具	@Component + @Slf4j + @Autowired	JwtTokenAdminInterceptor
全局异常	@RestControllerAdvice + @ExceptionHandler	GlobalExceptionHandler
模型文档	@ApiModel + @ApiModelProperty	EmployeeLoginDTO / EmployeeLoginVO

---

附：注解数量分布（按使用文件数）

@Data               ██████████████████████ 55
@AllArgsConstructor ███████████████████████ 31
@NoArgsConstructor  ██████████████████████ 30
@Builder            ███████████████████ 28
@Slf4j              ███ 6
@Component          ███ 5
@Autowired          ███ 5
@ConfigurationProperties █ 3
@ApiModel/@ApiModelProperty █ 2
其余（各1处）        @SpringBootApplication @EnableTransactionManagement
                    @Configuration @Bean @RestController @RequestMapping
                    @PostMapping @RestControllerAdvice @ExceptionHandler
                    @Mapper @Select @Service
                    @JsonFormat @DateTimeFormat