Java 项目开发常用注解速查表
Java 项目开发常用注解速查表
整理时间：2026-07-10
涵盖：Java 标准注解、Spring/Spring Boot、JPA、校验、Lombok 等
一、Java 标准注解（JDK 内置）
| 注解 | 作用 |
|---|---|
@Override | 表示方法重写了父类方法 |
@Deprecated | 标记方法/类已过时，编译器会发出警告 |
@SuppressWarnings | 抑制编译器警告 |
@FunctionalInterface | 标记函数式接口（Java 8+） |
@SafeVarargs | 抑制可变参数泛型警告 |
二、Spring 核心注解
2.1 组件声明
| 注解 | 说明 | 使用场景 |
|---|---|---|
@Component | 通用组件 | 不属于以下三类的普通 Bean |
@Service | 业务逻辑层 | Service 类 |
@Repository | 数据访问层 | DAO/Mapper 类，自动转换异常 |
@Controller | Web 控制器（返回视图） | MVC 控制器 |
@RestController | REST API 控制器 | 返回 JSON/XML，等价于@Controller + @ResponseBody |
2.2 依赖注入
| 注解 | 说明 |
|---|---|
@Autowired | 按类型自动注入（Spring 专属） |
@Qualifier("beanName") | 配合@Autowired按名称注入 |
@Resource(name="beanName") | JSR-250 标准，按名称注入 |
@Value("${app.name}") | 注入配置文件中的属性值 |
@Inject | JSR-330 标准，类似@Autowired |
2.3 配置类
| 注解 | 说明 |
|---|---|
@Configuration | 声明当前类为配置类 |
@Bean | 在配置类中手动声明 Bean |
@ComponentScan("com.example") | 指定组件扫描路径 |
@Import | 导入其他配置类 |
@PropertySource("classpath:app.properties") | 加载外部属性文件 |
@ConfigurationProperties(prefix="app") | 批量绑定配置前缀到 POJO |
2.4 Web 请求映射
| 注解 | 说明 |
|---|---|
@RequestMapping("/api") | 通用请求映射（可指定 method） |
@GetMapping("/users") | GET 请求 |
@PostMapping("/users") | POST 请求 |
@PutMapping("/users/{id}") | PUT 请求 |
@DeleteMapping("/users/{id}") | DELETE 请求 |
@PatchMapping("/users/{id}") | PATCH 请求 |
2.5 请求参数绑定
| 注解 | 说明 |
|---|---|
@RequestParam("name") | 获取 URL 查询参数?name=xxx |
@PathVariable("id") | 获取 URL 路径参数/users/{id} |
@RequestBody | 获取请求体（JSON → 对象） |
@ResponseBody | 将返回值转为 JSON/XML |
@RequestHeader | 获取请求头 |
@CookieValue | 获取 Cookie 值 |
@ModelAttribute | 绑定表单数据到对象 |
2.6 事务与 AOP
| 注解 | 说明 |
|---|---|
@Transactional | 声明式事务管理 |
@Transactional(readOnly=true) | 只读事务，优化查询性能 |
@Aspect | 声明切面类 |
@Before/@After/@Around | 切面通知类型 |
@Pointcut | 定义切点表达式 |
2.7 异常处理
| 注解 | 说明 |
|---|---|
@ExceptionHandler(Exception.class) | 处理特定异常 |
@ControllerAdvice/@RestControllerAdvice | 全局异常处理/数据绑定 |
三、Spring Boot 专用注解
| 注解 | 说明 |
|---|---|
@SpringBootApplication | 组合注解 =@Configuration + @EnableAutoConfiguration + @ComponentScan |
@EnableAutoConfiguration | 启用自动配置 |
@SpringBootTest | Spring Boot 集成测试 |
@AutoConfigureMockMvc | 自动配置 MockMvc 用于测试 |
@TestPropertySource | 测试时覆盖配置属性 |
@Profile("dev") | 指定当前环境配置 |
@ConditionalOnProperty | 根据配置属性条件装配 |
@ConditionalOnClass | 根据类存在条件装配 |
@ConditionalOnMissingBean | 当缺少指定 Bean 时才装配 |
@EnableCaching | 开启缓存支持 |
@EnableAsync | 开启异步方法支持 |
@EnableScheduling | 开启定时任务支持 |
@Scheduled(cron="0 0 * * * ?") | 定时任务表达式 |
@Async | 异步执行方法 |
@Cacheable("users") | 方法结果缓存 |
@CacheEvict("users") | 清除缓存 |
四、JPA / 数据持久层注解
| 注解 | 说明 |
|---|---|
@Entity | 声明 JPA 实体类 |
@Table(name="t_user") | 指定数据库表名 |
@Id | 声明主键字段 |
@GeneratedValue(strategy=GenerationType.IDENTITY) | 主键生成策略 |
@Column(name="user_name", nullable=false) | 字段映射配置 |
@Transient | 字段不持久化到数据库 |
@Temporal(TemporalType.TIMESTAMP) | 日期类型映射 |
@Enumerated(EnumType.STRING) | 枚举映射为字符串 |
@OneToOne/@OneToMany/@ManyToOne/@ManyToMany | 关联映射 |
@JoinColumn(name="dept_id") | 外键关联字段 |
@MappedSuperclass | 父类映射，子类继承字段 |
主键生成策略
| 策略 | 说明 |
|---|---|
GenerationType.AUTO | 自动选择 |
GenerationType.IDENTITY | 数据库自增（MySQL） |
GenerationType.SEQUENCE | 数据库序列（Oracle/PostgreSQL） |
GenerationType.TABLE | 使用序列表 |
GenerationType.UUID | UUID 生成 |
五、Bean Validation 数据校验注解
| 注解 | 说明 | 示例 |
|---|---|---|
@NotNull | 值不能为 null | @NotNull private String name; |
@NotEmpty | 不能为 null 且长度 > 0（集合/字符串） | @NotEmpty private List<String> list; |
@NotBlank | 不能为 null 且去除空白后长度 > 0 | @NotBlank private String name; |
@Size(min=2, max=20) | 长度/大小范围 | @Size(min=2, max=20) private String name; |
@Min(1)/@Max(100) | 数值范围 | @Min(1) private int age; |
@Positive/@Negative | 正数 / 负数 | @Positive private BigDecimal price; |
@PositiveOrZero/@NegativeOrZero | 非负 / 非正 | |
@DecimalMin("0.01")/@DecimalMax("999.99") | 小数范围 | |
@Digits(integer=5, fraction=2) | 整数位和小数位限制 | |
@Pattern(regexp="^[a-zA-Z0-9]+$") | 正则匹配 | |
@Email | 邮箱格式校验 | @Email private String email; |
@Future/@Past | 未来 / 过去日期 | @Future private Date expireDate; |
@AssertTrue/@AssertFalse | 必须为 true / false | |
@Valid | 级联校验嵌套对象 | @Valid private Address address; |
校验使用方式
// Controller 层触发校验@PostMapping("/users")publicResponseEntity<?>createUser(@Valid@RequestBodyUserDTOuser){// ...}// 分组校验publicResponseEntity<?>updateUser(@Validated(UpdateGroup.class)@RequestBodyUserDTOuser){// ...}六、Lombok 注解（减少样板代码）
| 注解 | 说明 |
|---|---|
@Data | 组合注解 =@Getter + @Setter + @ToString + @EqualsAndHashCode + @RequiredArgsConstructor |
@Getter/@Setter | 自动生成 getter/setter |
@ToString | 自动生成 toString |
@EqualsAndHashCode | 自动生成 equals 和 hashCode |
@NoArgsConstructor | 无参构造器 |
@AllArgsConstructor | 全参构造器 |
@RequiredArgsConstructor | 为 final 字段生成构造器 |
@Builder | 建造者模式 |
@Slf4j | 自动生成private static final Logger log |
@Log4j2 | 使用 Log4j2 |
@Value | 不可变对象（final + getter，无 setter） |
@NonNull | 参数/字段非空校验 |
@Cleanup | 自动关闭资源（try-with-resources） |
@SneakyThrows | 隐式抛出受检异常 |
七、Spring Security 安全注解
| 注解 | 说明 |
|---|---|
@EnableWebSecurity | 启用 Web 安全配置 |
@PreAuthorize("hasRole('ADMIN')") | 方法执行前权限校验 |
@PostAuthorize("returnObject.owner == authentication.name") | 方法执行后权限校验 |
@Secured("ROLE_ADMIN") | 基于角色的方法安全 |
@RolesAllowed("ADMIN") | JSR-250 标准角色控制 |
@PermitAll/@DenyAll | 允许/拒绝所有访问 |
@AuthenticationPrincipal | 获取当前认证用户 |
@EnableGlobalMethodSecurity(prePostEnabled=true) | 启用方法级安全注解 |
八、Swagger / OpenAPI 文档注解
SpringDoc OpenAPI 3（推荐）
| 注解 | 说明 |
|---|---|
@Tag(name="用户管理", description="用户相关接口") | API 分组标签 |
@Operation(summary="获取用户", description="根据ID获取用户信息") | 接口说明 |
@Parameter(name="id", description="用户ID") | 参数说明 |
@ApiResponse(responseCode="200", description="成功") | 响应说明 |
@Schema(description="用户实体", example="{}") | 模型描述 |
@Hidden | 隐藏该接口/字段 |
Swagger 2（旧版）
| 注解 | 说明 |
|---|---|
@Api(tags="用户管理") | 控制器描述 |
@ApiOperation("获取用户") | 接口描述 |
@ApiParam("用户ID") | 参数描述 |
@ApiModel("用户实体") | 模型描述 |
@ApiModelProperty("用户名") | 属性描述 |
@ApiIgnore | 忽略该接口 |
九、测试相关注解
| 注解 | 说明 |
|---|---|
@SpringBootTest | 加载完整 Spring 上下文测试 |
@WebMvcTest(Controller.class) | 仅测试 Web 层 |
@DataJpaTest | 仅测试 JPA 层 |
@MockBean | 创建 Mock Bean 替换真实 Bean |
@SpyBean | 创建 Spy Bean |
@AutoConfigureMockMvc | 自动配置 MockMvc |
@Test(JUnit 5) | 测试方法 |
@BeforeEach/@AfterEach | 每个测试前后执行 |
@BeforeAll/@AfterAll | 所有测试前后执行（需 static） |
@DisplayName("描述") | 测试显示名称 |
@ParameterizedTest | 参数化测试 |
@ValueSource(strings={"a","b"}) | 参数来源 |
@Disabled | 禁用测试 |
十、其他常用注解
| 注解 | 来源 | 说明 |
|---|---|---|
@CrossOrigin(origins="*") | Spring | 跨域配置 |
@RequestScope/@SessionScope | Spring | 请求/会话作用域 |
@Lazy | Spring | 延迟初始化 |
@Primary | Spring | 优先使用该 Bean |
@Order(1) | Spring | 指定执行顺序 |
@EventListener | Spring | 监听应用事件 |
@Retryable | Spring Retry | 方法失败时重试 |
@Recover | Spring Retry | 重试耗尽后的恢复方法 |
@Timed/@Counted | Micrometer | 指标监控 |
@KafkaListener | Spring Kafka | Kafka 消息监听 |
@RabbitListener | Spring AMQP | RabbitMQ 消息监听 |
@FeignClient("service-name") | OpenFeign | 声明式 HTTP 客户端 |
@LoadBalanced | Spring Cloud | 负载均衡 RestTemplate |
@EnableCircuitBreaker | Spring Cloud | 启用熔断器 |
@HystrixCommand | Hystrix | 熔断降级 |
@SentinelResource | Alibaba Sentinel | 流量控制 |
@DubboService/@DubboReference | Apache Dubbo | Dubbo 服务暴露/引用 |
附录：快速记忆口诀
组件三层：Service、Repository、Controller 注入三种：Autowired、Resource、Inject Web 映射：Get/Post/Put/Delete/Patch 参数绑定：Param、PathVariable、RequestBody 事务管理：Transactional 校验非空：NotNull、NotEmpty、NotBlank Lombok 神器：Data、Slf4j、Builder Boot 入口：SpringBootApplication本文档持续更新，建议结合官方文档使用。