springboot我们项目中的常见注解

一、启动与配置类

注解	干什么	项目里常见位置
@SpringBootApplication	启动类，等于 @Configuration + @EnableAutoConfiguration + @ComponentScan	Application.java
@Configuration	声明配置类	config/ 包
@Bean	向容器注册对象	配置类里
@ConfigurationProperties	绑定 application.yml 配置	XxxProperties.java
@EnableConfigurationProperties	启用配置属性类	配置类 / 启动类
@PropertySource	加载额外配置文件	少数多环境项目
@Import	手动导入配置	自定义 starter、多模块
@ConditionalOnProperty	按配置开关决定是否生效	自动配置、功能开关
@Profile	按环境启用（dev/test/prod）	配置类、Bean

@SpringBootApplication
public class App { ... }

@Configuration
@ConfigurationProperties(prefix = "app.order")
public class OrderProperties {
    private int timeout;
}

二、组件注册（分层最常用）

注解	干什么	区别
@Component	通用组件	工具类、通用逻辑
@Service	业务层	service/
@Repository	数据访问层	dao/、repository/
@Controller	传统 MVC 控制器	返回页面时用
@RestController	REST 接口	controller/，= @Controller + @ResponseBody

项目里 90% 的分层就是这四个：

Controller → Service → Repository
@RestController  @Service  @Repository

三、依赖注入（天天写）

注解	干什么	项目建议
@Autowired	自动注入	老项目很多，3.x 更推荐构造器注入
@Resource	按名称注入	国内项目很常见
@Qualifier	指定注入哪个 Bean	同类型多个实现时
@Value	注入单个配置值	简单配置
@Primary	多个实现时默认用这个	策略模式、默认数据源

@RestController
@RequiredArgsConstructor  // Lombok 构造器注入，项目里很常见
public class UserController {
    private final UserService userService;
}

四、Web 接口（Controller 层核心）

注解	干什么
@RequestMapping	映射路径（类/方法）
@GetMapping	GET
@PostMapping	POST
@PutMapping	PUT
@DeleteMapping	DELETE
@PatchMapping	PATCH
@RequestBody	接收 JSON 请求体
@RequestParam	接收 query 参数 ?id=1
@PathVariable	接收路径参数 /user/{id}
@RequestHeader	接收请求头
@ResponseBody	返回 JSON（@RestController 已自带）
@ResponseStatus	指定 HTTP 状态码
@CrossOrigin	跨域（小项目常用，大项目一般放网关/Security）
@Valid / @Validated	开启参数校验
@RestControllerAdvice	全局异常处理
@ExceptionHandler	处理某类异常

@RestController
@RequestMapping("/api/users")
public class UserController {
    @GetMapping("/{id}")
    public UserDTO get(@PathVariable Long id) { ... }
    @PostMapping
    public UserDTO create(@RequestBody @Valid CreateUserReq req) { ... }
}

五、参数校验（接口层很常见）

注解	干什么
@NotNull	不能为 null
@NotBlank	字符串不能为空
@NotEmpty	集合/数组不能为空
@Size	长度限制
@Min / @Max	数值范围
@Email	邮箱格式
@Pattern	正则

public record CreateUserReq(
    @NotBlank String name,
    @Email String email
) {}

Spring Boot 3.x 里这些是 jakarta.validation，不是 javax.validation。

六、数据库 / JPA（后台项目极常见）

注解	干什么
@Entity	实体类
@Table	表名
@Id	主键
@GeneratedValue	主键生成策略
@Column	字段映射
@OneToMany / @ManyToOne 等	关联关系
@Transactional	事务
@Query	自定义 SQL/JPQL
@Modifying	更新/删除语句
@EnableJpaRepositories	启用 JPA 仓库

@Entity
@Table(name = "sys_user")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
}


@Service
public class UserService {
    @Transactional(rollbackFor = Exception.class)
    public void save(User user) { ... }
}

七、Spring Security（3.x 项目必备）

注解	干什么
@EnableWebSecurity	启用 Security
@PreAuthorize	方法级权限，如 hasRole('ADMIN')
@PostAuthorize	方法执行后鉴权
@Secured	角色控制（较老）

@PreAuthorize("hasAuthority('user:delete')")
@DeleteMapping("/{id}")
public void delete(@PathVariable Long id) { ... }

八、定时任务 / 异步

注解	干什么
@EnableScheduling	开启定时任务
@Scheduled	cron / fixedRate 定时执行
@EnableAsync	开启异步
@Async	异步方法

@Scheduled(cron = "0 0 2 * * ?")
public void syncData() { ... }
@Async
public void sendMail() { ... }

九、缓存 / 消息 / 外部调用

注解	干什么
@EnableCaching	开启缓存
@Cacheable	查询缓存
@CacheEvict	删除缓存
@KafkaListener	消费 Kafka
@RabbitListener	消费 RabbitMQ
@HttpExchange	声明式 HTTP 客户端（Boot 3 常用）
@GetExchange / @PostExchange	配合 @HttpExchange

---

十、测试类常见

注解	干什么
@SpringBootTest	启动完整上下文
@WebMvcTest	只测 Controller
@DataJpaTest	只测 JPA
@MockBean	注入 Mock 对象
@Autowired	注入测试依赖
@Testcontainers	容器化集成测试
@ServiceConnection	自动连接测试容器（Boot 3.1+）

---

十一、一个典型项目里「天天见」的 Top 20

如果只记最常用的，一般是这些：

@SpringBootApplication

@Configuration

@Bean

@Service

@RestController

@Autowired / 构造器注入

@GetMapping / @PostMapping

@RequestBody

@RequestParam

@PathVariable

@Valid

@Transactional

@Entity

@Repository

@Value

@ConfigurationProperties

@RestControllerAdvice

@ExceptionHandler

@Scheduled

---

十二、按目录对照（方便你对项目结构）

src/main/java/com/xxx/

├── XxxApplication.java @SpringBootApplication

├── controller/ @RestController, @GetMapping...

├── service/ @Service, @Transactional

├── repository/ @Repository 或 JpaRepository 接口

├── entity/ @Entity, @Table, @Id

├── config/ @Configuration, @Bean

├── properties/ @ConfigurationProperties

├── dto/req/ @NotBlank, @Email...

├── exception/ @RestControllerAdvice, @ExceptionHandler

└── job/ @Scheduled

---