【Java 常用注解学习笔记1】——Java 常用注解全解析：从基础到实战

Java 常用注解全解析：从基础到实战

---

一、引言

Java 注解（Annotation）是现代化开发中提升代码简洁性、可维护性和与框架集成的重要工具。本文系统化梳理主流框架（Spring、MyBatis-Plus、Swagger 等）的核心注解，通过分类解析、代码示例与最佳实践，帮助开发者精准掌握注解的应用场景与技巧。

---

二、Lombok 注解

1. 代码简化注解

注解	作用	示例	注意事项
@Data	生成 getter/setter/toString/equals/hashCode	@Data public class User { ... }	继承场景需搭配 @EqualsAndHashCode(callSuper=true)
@Accessors(chain=true)	链式调用 setter 方法	user.setName("A").setAge(20);	FastJSON 反序列化兼容性问题
@Builder	建造者模式	User.builder().name("A").build();	复杂对象慎用

2. 构造器与不可变对象

@Value // 生成全参构造器 + final 字段
public class Point {
    int x;
    int y;
}
@NoArgsConstructor // 无参构造器
@AllArgsConstructor // 全参构造器
public class User { ... }

---

三、MyBatis-Plus 注解

1. 数据库映射

注解	作用	示例
@TableName	指定表名	@TableName("sys_user")
@TableId	主键策略	@TableId(type = IdType.AUTO)
@TableField	字段映射	@TableField("user_name")
@Version	乐观锁控制	@Version private Integer version;

2. 动态表名与多数据源

// 动态表名处理器
public class DynamicTableNameHandler implements TableNameHandler {
    @Override
    public String dynamicTableName(String sql, String tableName) {
        return getCurrentYearTable(tableName);
    }
}

---

四、Swagger 注解

1. API 文档生成

注解	作用	示例
@Api	控制器分组描述	@Api(tags = "用户管理")
@ApiOperation	接口方法描述	@ApiOperation("根据ID查询用户")
@ApiModel	数据模型描述	@ApiModel("用户实体")
@ApiModelProperty	字段描述	@ApiModelProperty("用户名")

2. 生产环境优化

# 关闭Swagger
springfox:
  swagger:
    enabled: false

---

五、Spring 核心注解

1. 组件与依赖注入

注解	作用	示例
@Component	通用组件标记	@Component public class Util {}
@Autowired	按类型注入	@Autowired private UserService service;
@Primary	优先注入的Bean	@Primary @Bean public DataSource ds() {}
@Profile	环境隔离	@Profile("dev")

2. 构造器注入最佳实践

@Service
public class UserService {
    private final UserDao dao;
    @Autowired // 构造器注入（推荐）
    public UserService(UserDao dao) { this.dao = dao; }
}

---

六、Spring MVC 注解

1. 控制器与请求映射

注解	作用	示例
@RestController	REST 控制器（自动 JSON 序列化）	@RestController public class UserApi {}
@GetMapping	GET 请求映射	@GetMapping("/users/{id}")
@PostMapping	POST 请求映射	@PostMapping("/users")
@RequestBody	绑定请求体	public void save(@RequestBody User user)

2. 参数绑定与校验

@GetMapping("/search")
public List<User> search(
    @RequestParam(defaultValue = "1") int page,
    @PathVariable Long id,
    @Valid @ModelAttribute UserQuery query) { ... }

---

七、Spring Boot 配置注解

1. 配置管理

注解	作用	示例
@SpringBootApplication	主启动类	@SpringBootApplication public class App {}
@ConfigurationProperties	批量绑定配置	@ConfigurationProperties(prefix="app")
@Value	注入单个配置项	@Value("${app.timeout}") private int timeout;

2. 条件装配

@Bean
@ConditionalOnClass(RedisClient.class) // 类路径存在时生效
@ConditionalOnProperty(name = "cache.enabled") // 配置开启时生效
public CacheService cacheService() { ... }

---

八、JPA/Hibernate 注解

1. 实体映射

注解	作用	示例
@Entity	声明 JPA 实体	@Entity public class User {}
@GeneratedValue	主键生成策略	@GeneratedValue(strategy=IDENTITY)
@OneToMany	一对多关系	@OneToMany(mappedBy = "user")
@Transactional	声明式事务	@Transactional(rollbackFor=Exception.class)

2. 乐观锁与审计

@Version // 乐观锁
private Integer version;
@CreatedDate // 自动填充创建时间
private LocalDateTime createTime;

---

九、校验注解（JSR 380）

1. 常用校验规则

注解	作用	示例
@NotBlank	字符串非空（含非空格）	@NotBlank private String name;
@Positive	正整数校验	@Positive private Integer age;
@Pattern	正则校验	@Pattern(regexp = "^1[3-9]\\d{9}$")

2. 自定义校验器

@Target(FIELD)
@Retention(RUNTIME)
@Constraint(validatedBy = PhoneValidator.class)
public @interface Phone {
    String message() default "手机号格式错误";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

---

十、最佳实践与常见问题

1. 分层规范

   • Controller 层：@Valid 校验 + @RestController
   • Service 层：@Transactional 事务控制
   • DAO 层：@Repository + MyBatis-Plus/JPA 注解

2. Lombok 使用建议

   • 实体类：@Data + @Builder
   • 避免滥用 @AllArgsConstructor

3. API 文档维护

   • 使用 @ApiIgnore 隐藏内部接口
   • 生产环境通过配置关闭 Swagger

4. 事务管理

   • 只读操作：@Transactional(readOnly = true)
   • 明确指定回滚异常：rollbackFor = Exception.class

---

结语

合理使用注解能大幅提升开发效率与代码质量，但需结合项目需求与团队规范。建议在深入理解原理的基础上，灵活选择注解组合，避免过度设计。