位置：文档库 > Java > Spring 最常用的 7 大类注解，史上最强整理！

Spring 最常用的 7 大类注解，史上最强整理！

阮文灵上传于 2021-11-06 15:21

《Spring 最常用的 7 大类注解，史上最强整理！》

Spring 框架作为 Java 生态中最核心的组件之一，其注解驱动的开发模式极大简化了企业级应用的开发流程。从依赖注入到事务管理，从 Web 层到持久层，注解已经成为 Spring 生态中不可或缺的元数据载体。本文系统梳理 Spring 框架中最常用的 7 大类核心注解，涵盖 Bean 管理、Web 开发、数据访问、事务控制等关键场景，为开发者提供一份可随时查阅的实用指南。

一、核心容器注解（IoC/DI）

Spring 的核心是依赖注入容器，以下注解构成了 IoC 容器的基础设施：

1.1 @Component 及其衍生注解

作为 Spring 组件的元注解，@Component 是所有自定义 Bean 的根注解，其衍生注解包括：

@Service // 业务逻辑层组件
@Repository // 数据访问层组件
@Controller // Web 控制器组件
@RestController // RESTful 控制器组件（Spring 4+）

这些注解不仅标记类为 Spring 管理的 Bean，还通过语义化区分不同层次的组件。例如：

@Service
public class OrderServiceImpl implements OrderService {
    @Autowired
    private OrderRepository orderRepository;
    // 业务逻辑实现
}

1.2 @Autowired 与依赖注入

@Autowired 是 Spring 提供的最强大的依赖注入注解，支持三种注入方式：

字段注入（不推荐，测试困难）
构造器注入（推荐，Spring 4.3+ 可省略注解）
Setter 方法注入

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

1.3 @Qualifier 与多实例选择

当存在多个同类型 Bean 时，@Qualifier 可精确指定注入对象：

@Configuration
public class AppConfig {
    @Bean("primaryDataSource")
    public DataSource primaryDataSource() { ... }
    
    @Bean("secondaryDataSource")
    public DataSource secondaryDataSource() { ... }
}

@Service
public class DataService {
    @Autowired
    @Qualifier("primaryDataSource")
    private DataSource dataSource;
}

二、Web 层注解（MVC）

Spring MVC 提供了完整的 Web 开发注解体系，以下是最常用的核心注解：

2.1 @Controller 与 @RestController

@Controller 标记传统 MVC 控制器，返回视图名称；@RestController 是 @Controller 与 @ResponseBody 的组合，专为 REST API 设计：

@RestController
@RequestMapping("/api/users")
public class UserController {
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

2.2 请求映射注解

Spring 4.3+ 简化了请求映射注解体系：

@RequestMapping：基础请求映射（可指定方法、路径、参数等）
@GetMapping / @PostMapping / @PutMapping / @DeleteMapping：HTTP 方法专用注解
@PathVariable：获取 URL 路径变量
@RequestParam：获取查询参数
@RequestBody：将请求体绑定到方法参数

@PostMapping
public ResponseEntity createUser(@RequestBody @Valid UserDto userDto) {
    User savedUser = userService.save(userDto);
    return ResponseEntity.created(URI.create("/users/" + savedUser.getId()))
                         .body(savedUser);
}

2.3 异常处理注解

@ControllerAdvice 与 @ExceptionHandler 组合实现全局异常处理：

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity handleNotFound(ResourceNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                             .body(new ErrorResponse(ex.getMessage()));
    }
}

三、数据访问注解（JDBC/JPA）

Spring Data 提供了强大的数据访问抽象，以下注解简化了持久层开发：

3.1 @Repository 与异常转换

@Repository 不仅标记 DAO 组件，还自动将持久化异常转换为 Spring 的 DataAccessException：

@Repository
public class JpaUserRepository implements UserRepository {
    @PersistenceContext
    private EntityManager entityManager;
    
    @Override
    public Optional findByEmail(String email) {
        try {
            return Optional.ofNullable(entityManager.createQuery(
                "SELECT u FROM User u WHERE u.email = :email", User.class)
                .setParameter("email", email)
                .getSingleResult());
        } catch (NoResultException e) {
            return Optional.empty();
        }
    }
}

3.2 Spring Data JPA 注解

Spring Data JPA 通过方法名解析和自定义注解简化 CRUD 操作：

@Query：自定义 JPQL/SQL 查询
@Modifying：标识更新操作
@EntityGraph：解决 N+1 查询问题

public interface UserRepository extends JpaRepository {
    @Query("SELECT u FROM User u WHERE u.status = :status")
    List findByStatus(@Param("status") UserStatus status);
    
    @Modifying
    @Query("UPDATE User u SET u.status = :status WHERE u.id = :id")
    int updateStatus(@Param("id") Long id, @Param("status") UserStatus status);
}

四、事务管理注解

Spring 的声明式事务管理通过 @Transactional 注解实现：

4.1 @Transactional 核心属性

propagation：事务传播行为（REQUIRED/REQUIRES_NEW 等）
isolation：事务隔离级别
timeout：事务超时时间
rollbackFor：指定触发回滚的异常类型

@Service
@Transactional(rollbackFor = Exception.class)
public class OrderService {
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void processOrder(Order order) {
        // 业务逻辑
        inventoryService.updateStock(order.getItems());
        paymentService.charge(order.getPayment());
    }
}

4.2 事务注解的最佳实践

1. 默认只在 public 方法上生效
2. 自调用（类内部方法调用）不会触发事务
3. 避免在事务方法中执行耗时操作

五、配置类注解

Spring 的 Java 配置方式通过以下注解实现：

5.1 @Configuration 与 @Bean

@Configuration 标记配置类，@Bean 定义 Bean 创建逻辑：

@Configuration
public class AppConfig {
    @Bean
    public DataSource dataSource() {
        return DataSourceBuilder.create()
                .url("jdbc:mysql://localhost:3306/mydb")
                .username("user")
                .password("pass")
                .build();
    }
    
    @Bean
    public PlatformTransactionManager transactionManager(DataSource dataSource) {
        return new DataSourceTransactionManager(dataSource);
    }
}

5.2 @Profile 与环境配置

@Profile 指定 Bean 在特定环境激活：

@Configuration
@Profile("dev")
public class DevConfig {
    @Bean
    public DataSource devDataSource() {
        return new EmbeddedDatabaseBuilder()
                .setType(EmbeddedDatabaseType.H2)
                .build();
    }
}

六、测试注解

Spring Test 模块提供了完整的测试支持注解：

6.1 集成测试注解

@SpringBootTest：启动完整应用上下文
@WebMvcTest：仅测试 MVC 层
@DataJpaTest：测试 JPA 组件
@MockBean：注入 Mock 对象

@SpringBootTest
@AutoConfigureMockMvc
public class UserControllerTest {
    @Autowired
    private MockMvc mockMvc;
    
    @MockBean
    private UserService userService;
    
    @Test
    public void testGetUser() throws Exception {
        when(userService.findById(1L)).thenReturn(new User(1L, "test"));
        
        mockMvc.perform(get("/api/users/1"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.name").value("test"));
    }
}

七、AOP 相关注解

Spring AOP 通过注解实现面向切面编程：

7.1 @Aspect 与切面定义

@Aspect
@Component
public class LoggingAspect {
    @Before("execution(* com.example.service.*.*(..))")
    public void logBefore(JoinPoint joinPoint) {
        log.info("Entering method: {}", joinPoint.getSignature());
    }
}

7.2 自定义注解切面

结合自定义注解实现更灵活的 AOP：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface LogExecutionTime {
}

@Aspect
@Component
public class ExecutionTimeAspect {
    @Around("@annotation(LogExecutionTime)")
    public Object logExecutionTime(ProceedingJoinPoint joinPoint) throws Throwable {
        long start = System.currentTimeMillis();
        Object proceed = joinPoint.proceed();
        long executionTime = System.currentTimeMillis() - start;
        log.info("{} executed in {} ms", joinPoint.getSignature(), executionTime);
        return proceed;
    }
}

八、进阶注解组合

Spring 5+ 引入了组合注解功能，可创建自定义注解组合：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@RestController
@RequestMapping("/api")
public @interface ApiController {
    String value() default "";
}

九、最佳实践总结

1. 优先使用构造器注入替代字段注入
2. 合理划分 @Component 衍生注解的使用场景
3. 事务方法保持短小精悍
4. 测试类注解组合使用（如 @SpringBootTest + @MockBean）
5. 自定义组合注解提升代码可读性

关键词：Spring注解、依赖注入、@Component、@Autowired、@Controller、@RequestMapping、@Transactional、@Configuration、Spring Data JPA、AOP切面、测试注解

简介：本文系统整理Spring框架中最常用的7大类核心注解，涵盖IoC容器管理、Web开发、数据访问、事务控制、配置类、测试支持和AOP编程等关键场景。通过代码示例和最佳实践，帮助开发者全面掌握Spring注解的使用技巧，提升开发效率。

立即下载

Java相关