Java 常用注解扩展对比

Java 常用注解扩展对比

一、@Controller 与 @RestController 对比

对比维度	@Controller	@RestController
定义	Spring MVC 的基础控制器注解	@Controller + @ResponseBody 的组合注解
返回值处理	返回视图名称（需配合视图解析器）	直接返回 JSON/XML 数据（自动添加 @ResponseBody）
适用场景	传统 MVC 架构（如 JSP/Thymeleaf 页面渲染）	RESTful API 开发（前后端分离场景）
HTTP 响应头	Content-Type: text/html（默认）	Content-Type: application/json（默认）

// @Controller 示例
@Controller
public class WebCtrl {
    @GetMapping("/page")
    public String page() {
        return "index"; // 返回视图名
    }
}

// @RestController 示例
@RestController
public class ApiCtrl {
    @GetMapping("/data")
    public User data() {
        return userService.findUser(); // 自动转 JSON
    }
}

二、使用 @Data 与 不使用 @Data 对比

对比维度	使用 @Data	不使用 @Data
代码量	自动生成以下方法：所有字段的 getter/setter、toString()、equals()/hashCode()	需手动编写所有方法
维护性	字段增减时无需修改方法	字段变更需同步修改相关方法
继承关系处理	需显式添加 @EqualsAndHashCode(callSuper=true) 包含父类字段	手动编写时可直接控制是否包含父类字段
框架兼容性	依赖 Lombok 插件（需 IDE 支持）	无额外依赖

注意事项：

1. 使用 @Data 时，若类有继承关系，需添加 @EqualsAndHashCode(callSuper=true)
2. 某些场景（如 JPA 实体类）需显式定义无参构造器（通过 @NoArgsConstructor）

三、使用 @TableName 与 不使用 @TableName 对比

对比维度	使用 @TableName	不使用 @TableName
表名映射规则	显式指定数据库表名（如 @TableName("sys_user")）	按 MyBatis-Plus 默认规则映射：类名驼峰转下划线（如 SysUser → sys_user）
适用场景	1. 表名含特殊字符（如 user-info） 2. 类名与表名无对应关系	类名与表名严格遵循驼峰转下划线规则
全局配置覆盖	优先级高于全局配置	可通过配置文件统一设置表名前缀：mybatis-plus.global-config.db-config.table-prefix=sys_

// 使用 @TableName
@Data
@TableName("sys_user")
public class User {
    private Long id;
    private String name;
}

// 不使用 @TableName
@Data
public class SysUser {
    private Long id;
    private String name;
}

注意事项：

1. 表名包含 SQL 关键字时需转义：@TableName("order")
2. 分表场景可通过动态表名处理器（TableNameHandler）实现

四、依赖注入注解对比

注解对	核心区别	使用场景
@Autowired vs @Resource	- @Autowired（Spring）按类型注入 - @Resource（JSR-250）按名称注入	明确指定 Bean 名称时用 @Resource，优先使用构造器注入时用 @Autowired
@Primary vs @Qualifier	- @Primary 标记首选 Bean - @Qualifier 指定具体 Bean 名称	存在多个相同类型 Bean 时，优先使用 @Primary，需精确控制时用 @Qualifier

// @Autowired + @Qualifier
@Autowired
@Qualifier("mysqlDataSource")
private DataSource dataSource;

// @Resource
@Resource(name = "oracleDataSource")
private DataSource dataSource;

五、Spring MVC 参数绑定注解对比

注解对	核心区别	使用场景
@RequestParam vs @PathVariable	- @RequestParam 获取 URL 参数 - @PathVariable 获取 URI 模板变量	RESTful 风格 URL 用 @PathVariable，传统表单参数用 @RequestParam
@ModelAttribute vs @RequestBody	- @ModelAttribute 绑定 Form 表单数据 - @RequestBody 绑定 JSON 请求体	表单提交用 @ModelAttribute，API 接口传输复杂对象用 @RequestBody

// PathVariable
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    ...
}

// RequestBody
@PostMapping("/users")
public ResponseEntity<?> createUser(@RequestBody UserDTO userDTO) {
    ...
}

六、JPA/Hibernate 映射注解对比

注解对	核心区别	使用场景
@Entity vs @Table	- @Entity 声明 JPA 实体类 - @Table 指定数据库表名	类名与表名不一致时使用 @Table
@Column vs @Transient	- @Column 映射数据库列 - @Transient 标记非持久化字段	字段需要特殊列名或类型时用 @Column，临时计算字段用 @Transient
@OneToMany vs @ManyToOne	- 定义一对多/多对一关系	根据业务关系方向选择（部门 - 员工：部门用 @OneToMany，员工用 @ManyToOne）

@Entity
@Table(name = "departments")
public class Department {
    @OneToMany(mappedBy = "department")
    private List<Employee> employees;
}

@Entity
public class Employee {
    @ManyToOne
    @JoinColumn(name = "dept_id")
    private Department department;
}

七、Spring Boot 配置注解对比

注解对	核心区别	使用场景
@Value vs @ConfigurationProperties	- @Value 注入单个属性 - @ConfigurationProperties 批量绑定属性	简单配置用 @Value，复杂配置对象用 @ConfigurationProperties
@Profile vs @Conditional	- @Profile 按环境激活配置 - @Conditional 按条件创建 Bean	多环境配置用 @Profile，动态装配逻辑用 @Conditional

# application.yml
app:
  security:
    enabled: true
    timeout: 300

@Configuration
@ConfigurationProperties(prefix = "app.security")
public class SecurityConfig {
    private boolean enabled;
    private int timeout;
    // getters/setters
}

八、Lombok 注解对比

注解对	核心区别	使用场景
@Data vs @Value	- @Data 生成可变对象 - @Value 生成不可变对象（final 字段）	需要修改字段值时用 @Data，只读数据传输对象用 @Value
@Builder vs @AllArgsConstructor	- @Builder 支持链式构建 - @AllArgsConstructor 生成全参构造器	复杂对象构建用 @Builder，依赖注入全参构造用 @AllArgsConstructor

@Value
@Builder
public class ImmutablePoint {
    private final int x;
    private final int y;
}
// 使用 ImmutablePoint point = ImmutablePoint.builder().x(10).y(20).build();

九、事务管理注解对比

注解对	核心区别	使用场景
@Transactional vs @Modifying	- @Transactional 声明事务边界 - @Modifying 标记 DML 操作	服务层方法用 @Transactional，JPA 更新查询用 @Modifying

@Service
public class UserService {
    @Transactional
    public void updateUser(User user) {
        userRepository.save(user);
    }
}

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    @Modifying
    @Query("UPDATE User u SET u.name = ?1 WHERE u.id = ?2")
    int updateNameById(String name, Long id);
}

十、测试相关注解对比

注解对	核心区别	使用场景
@Mock vs @MockBean	- @Mock（Mockito）创建模拟对象 - @MockBean（Spring Boot Test）替换 Spring 容器中的 Bean	单元测试用 @Mock，集成测试用 @MockBean
@SpringBootTest vs @WebMvcTest	- @SpringBootTest 加载完整上下文 - @WebMvcTest 仅加载 Web 层组件	全集成测试用 @SpringBootTest，控制层隔离测试用 @WebMvcTest

// 全集成测试
@SpringBootTest
class UserServiceIntegrationTest {
    @Autowired
    private UserService userService;
}

// 控制层测试
@WebMvcTest(UserController.class)
class UserControllerTest {
    @MockBean
    private UserService userService;
    @Autowired
    private MockMvc mockMvc;
}

综合对比总结表

功能场景	推荐注解组合	典型应用
REST API 开发	@RestController + @RequestBody + @Valid	前后端分离接口开发
JPA 实体映射	@Entity + @Table + @Column + @OneToMany	数据库表结构映射
配置管理	@ConfigurationProperties + @Profile	多环境配置切换
测试覆盖	@SpringBootTest + @MockBean + @DataJpaTest（按需选择）	分层测试策略
依赖注入	构造器注入优先，@Autowired + @Qualifier	避免循环依赖

最佳实践建议

1. 分层使用 严格遵循 Controller→Service→Repository 分层架构，避免跨层注解混用。
2. 注解最小化
   • 优先使用框架提供的组合注解（如 @RestController 代替 @Controller+@ResponseBody）
   • 避免重复注解（如同时使用 @Component 和 @Service）
3. Lombok 规范
   • 实体类统一使用 @Data + @Builder
   • 禁用无约束的 @AllArgsConstructor
4. 事务控制
   • Service 层统一声明 @Transactional(readOnly = true)
   • 写操作显式指定 @Transactional(rollbackFor = Exception.class)
5. 测试隔离
   • 单元测试使用 Mockito + JUnit5
   • 集成测试按需选择 @WebMvcTest 或 @DataJpaTest

通过系统化的注解对比与组合使用，可显著提高代码规范性和团队协作效率。建议结合 SonarLint 等代码质量管理工具，确保注解使用的合理性与一致性。