Java 项目开发常用注解速查表整理时间2026-07-10涵盖Java 标准注解、Spring/Spring Boot、JPA、校验、Lombok 等一、Java 标准注解JDK 内置注解作用Override表示方法重写了父类方法Deprecated标记方法/类已过时编译器会发出警告SuppressWarnings抑制编译器警告FunctionalInterface标记函数式接口Java 8SafeVarargs抑制可变参数泛型警告二、Spring 核心注解2.1 组件声明注解说明使用场景Component通用组件不属于以下三类的普通 BeanService业务逻辑层Service 类Repository数据访问层DAO/Mapper 类自动转换异常ControllerWeb 控制器返回视图MVC 控制器RestControllerREST API 控制器返回 JSON/XML等价于Controller ResponseBody2.2 依赖注入注解说明Autowired按类型自动注入Spring 专属Qualifier(beanName)配合Autowired按名称注入Resource(namebeanName)JSR-250 标准按名称注入Value(${app.name})注入配置文件中的属性值InjectJSR-330 标准类似Autowired2.3 配置类注解说明Configuration声明当前类为配置类Bean在配置类中手动声明 BeanComponentScan(com.example)指定组件扫描路径Import导入其他配置类PropertySource(classpath:app.properties)加载外部属性文件ConfigurationProperties(prefixapp)批量绑定配置前缀到 POJO2.4 Web 请求映射注解说明RequestMapping(/api)通用请求映射可指定 methodGetMapping(/users)GET 请求PostMapping(/users)POST 请求PutMapping(/users/{id})PUT 请求DeleteMapping(/users/{id})DELETE 请求PatchMapping(/users/{id})PATCH 请求2.5 请求参数绑定注解说明RequestParam(name)获取 URL 查询参数?namexxxPathVariable(id)获取 URL 路径参数/users/{id}RequestBody获取请求体JSON → 对象ResponseBody将返回值转为 JSON/XMLRequestHeader获取请求头CookieValue获取 Cookie 值ModelAttribute绑定表单数据到对象2.6 事务与 AOP注解说明Transactional声明式事务管理Transactional(readOnlytrue)只读事务优化查询性能Aspect声明切面类Before/After/Around切面通知类型Pointcut定义切点表达式2.7 异常处理注解说明ExceptionHandler(Exception.class)处理特定异常ControllerAdvice/RestControllerAdvice全局异常处理/数据绑定三、Spring Boot 专用注解注解说明SpringBootApplication组合注解 Configuration EnableAutoConfiguration ComponentScanEnableAutoConfiguration启用自动配置SpringBootTestSpring Boot 集成测试AutoConfigureMockMvc自动配置 MockMvc 用于测试TestPropertySource测试时覆盖配置属性Profile(dev)指定当前环境配置ConditionalOnProperty根据配置属性条件装配ConditionalOnClass根据类存在条件装配ConditionalOnMissingBean当缺少指定 Bean 时才装配EnableCaching开启缓存支持EnableAsync开启异步方法支持EnableScheduling开启定时任务支持Scheduled(cron0 0 * * * ?)定时任务表达式Async异步执行方法Cacheable(users)方法结果缓存CacheEvict(users)清除缓存四、JPA / 数据持久层注解注解说明Entity声明 JPA 实体类Table(namet_user)指定数据库表名Id声明主键字段GeneratedValue(strategyGenerationType.IDENTITY)主键生成策略Column(nameuser_name, nullablefalse)字段映射配置Transient字段不持久化到数据库Temporal(TemporalType.TIMESTAMP)日期类型映射Enumerated(EnumType.STRING)枚举映射为字符串OneToOne/OneToMany/ManyToOne/ManyToMany关联映射JoinColumn(namedept_id)外键关联字段MappedSuperclass父类映射子类继承字段主键生成策略策略说明GenerationType.AUTO自动选择GenerationType.IDENTITY数据库自增MySQLGenerationType.SEQUENCE数据库序列Oracle/PostgreSQLGenerationType.TABLE使用序列表GenerationType.UUIDUUID 生成五、Bean Validation 数据校验注解注解说明示例NotNull值不能为 nullNotNull private String name;NotEmpty不能为 null 且长度 0集合/字符串NotEmpty private ListString list;NotBlank不能为 null 且去除空白后长度 0NotBlank private String name;Size(min2, max20)长度/大小范围Size(min2, max20) 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(integer5, fraction2)整数位和小数位限制Pattern(regexp^[a-zA-Z0-9]$)正则匹配Email邮箱格式校验Email private String email;Future/Past未来 / 过去日期Future private Date expireDate;AssertTrue/AssertFalse必须为 true / falseValid级联校验嵌套对象Valid private Address address;校验使用方式// Controller 层触发校验PostMapping(/users)publicResponseEntity?createUser(ValidRequestBodyUserDTOuser){// ...}// 分组校验publicResponseEntity?updateUser(Validated(UpdateGroup.class)RequestBodyUserDTOuser){// ...}六、Lombok 注解减少样板代码注解说明Data组合注解 Getter Setter ToString EqualsAndHashCode RequiredArgsConstructorGetter/Setter自动生成 getter/setterToString自动生成 toStringEqualsAndHashCode自动生成 equals 和 hashCodeNoArgsConstructor无参构造器AllArgsConstructor全参构造器RequiredArgsConstructor为 final 字段生成构造器Builder建造者模式Slf4j自动生成private static final Logger logLog4j2使用 Log4j2Value不可变对象final getter无 setterNonNull参数/字段非空校验Cleanup自动关闭资源try-with-resourcesSneakyThrows隐式抛出受检异常七、Spring Security 安全注解注解说明EnableWebSecurity启用 Web 安全配置PreAuthorize(hasRole(ADMIN))方法执行前权限校验PostAuthorize(returnObject.owner authentication.name)方法执行后权限校验Secured(ROLE_ADMIN)基于角色的方法安全RolesAllowed(ADMIN)JSR-250 标准角色控制PermitAll/DenyAll允许/拒绝所有访问AuthenticationPrincipal获取当前认证用户EnableGlobalMethodSecurity(prePostEnabledtrue)启用方法级安全注解八、Swagger / OpenAPI 文档注解SpringDoc OpenAPI 3推荐注解说明Tag(name用户管理, description用户相关接口)API 分组标签Operation(summary获取用户, description根据ID获取用户信息)接口说明Parameter(nameid, description用户ID)参数说明ApiResponse(responseCode200, 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 替换真实 BeanSpyBean创建 Spy BeanAutoConfigureMockMvc自动配置 MockMvcTest(JUnit 5)测试方法BeforeEach/AfterEach每个测试前后执行BeforeAll/AfterAll所有测试前后执行需 staticDisplayName(描述)测试显示名称ParameterizedTest参数化测试ValueSource(strings{a,b})参数来源Disabled禁用测试十、其他常用注解注解来源说明CrossOrigin(origins*)Spring跨域配置RequestScope/SessionScopeSpring请求/会话作用域LazySpring延迟初始化PrimarySpring优先使用该 BeanOrder(1)Spring指定执行顺序EventListenerSpring监听应用事件RetryableSpring Retry方法失败时重试RecoverSpring Retry重试耗尽后的恢复方法Timed/CountedMicrometer指标监控KafkaListenerSpring KafkaKafka 消息监听RabbitListenerSpring AMQPRabbitMQ 消息监听FeignClient(service-name)OpenFeign声明式 HTTP 客户端LoadBalancedSpring Cloud负载均衡 RestTemplateEnableCircuitBreakerSpring Cloud启用熔断器HystrixCommandHystrix熔断降级SentinelResourceAlibaba Sentinel流量控制DubboService/DubboReferenceApache DubboDubbo 服务暴露/引用附录快速记忆口诀组件三层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本文档持续更新建议结合官方文档使用。