当前位置：首页 > article >正文

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

article 2025/2/25 14:39:31

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 {};
}

十、最佳实践与常见问题

分层规范
- Controller 层：@Valid 校验 + @RestController
- Service 层：@Transactional 事务控制
- DAO 层：@Repository + MyBatis-Plus/JPA 注解
Lombok 使用建议
- 实体类：@Data + @Builder
- 避免滥用 @AllArgsConstructor
API 文档维护
- 使用 @ApiIgnore 隐藏内部接口
- 生产环境通过配置关闭 Swagger
事务管理
- 只读操作：@Transactional(readOnly = true)
- 明确指定回滚异常：rollbackFor = Exception.class