Spring Boot 常用注解：分类、用法与避坑指南

在 Spring Boot 项目开发中，各种注解的使用极大地简化了配置，提高了开发效率。但面对琳琅满目的注解，如何理解其作用、正确使用以及避免踩坑，是每个开发者都需要掌握的技能。本文将对 Spring Boot 常用注解进行分类整理，并结合实际案例进行讲解，希望能帮助大家更好地理解和应用这些注解。

控制器相关注解

@RestController 和 @Controller

@RestController 和 @Controller 是最常用的两个注解，用于标记类为控制器。它们的主要区别在于 @RestController 包含了 @Controller 和 @ResponseBody，这意味着 @RestController 标记的类中的所有方法默认都会将返回值序列化成 JSON 格式返回。在前后端分离的项目中，我们通常使用 @RestController。

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // ...
        return new User();
    }
}

如果使用 @Controller，则需要显式地使用 @ResponseBody 注解来将返回值序列化成 JSON 格式。

@Controller
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    @ResponseBody // 需要显式添加
    public User getUser(@PathVariable Long id) {
        // ...
        return new User();
    }
}

实战避坑：

• 如果使用 Thymeleaf 或 Freemarker 等模板引擎，需要使用 @Controller，而不是 @RestController，否则会尝试将模板名称作为 JSON 返回。
• 确保你的项目引入了 jackson-databind 或类似的 JSON 序列化库，否则可能出现类型转换错误。

@RequestMapping、@GetMapping、@PostMapping 等

这些注解用于映射 HTTP 请求到特定的处理方法。@RequestMapping 是一个通用的注解，可以指定请求的 URL、HTTP 方法、Content-Type 等。@GetMapping、@PostMapping、@PutMapping、@DeleteMapping 等则是 @RequestMapping 的快捷方式，分别对应 GET、POST、PUT、DELETE 等 HTTP 方法。

@RestController
@RequestMapping("/products")
public class ProductController {

    @GetMapping
    public List<Product> getAllProducts() {
        // ...
        return new ArrayList<>();
    }

    @PostMapping
    public Product createProduct(@RequestBody Product product) {
        // ...
        return product;
    }
}

实战避坑：

• 在使用 @RequestBody 注解时，需要确保请求的 Content-Type 是 application/json，并且请求体中的 JSON 结构与 Java 类的属性匹配。
• 注意区分 @RequestParam 和 @PathVariable 的使用场景。@RequestParam 用于获取 URL 中的查询参数，而 @PathVariable 用于获取 URL 中的路径参数。

@PathVariable 和 @RequestParam

@PathVariable 用于获取 URL 路径中的参数，例如 /users/{id} 中的 id。@RequestParam 用于获取 URL 查询参数，例如 /users?name=John 中的 name。

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // ...
        return new User();
    }

    @GetMapping
    public List<User> getUsersByName(@RequestParam String name) {
        // ...
        return new ArrayList<>();
    }
}

实战避坑：

• 如果 @RequestParam 注解的参数是必需的，但请求中没有提供该参数，Spring Boot 会抛出 MissingServletRequestParameterException 异常。可以通过设置 required = false 来避免这种情况。
• 注意 @PathVariable 的参数名称必须与 URL 路径中的变量名称匹配。

组件相关注解

@Component、@Service、@Repository、@Configuration

这些注解用于标记类为 Spring Bean，方便 Spring 容器进行管理。@Component 是一个通用的注解，可以用于标记任何类为 Spring Bean。@Service 用于标记业务逻辑层的类，@Repository 用于标记数据访问层的类，@Configuration 用于标记配置类。

@Service
public class UserServiceImpl implements UserService {
    // ...
}

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    // ...
}

@Configuration
public class AppConfig {
    @Bean
    public DataSource dataSource() {
        // ...
        return new DataSource();
    }
}

实战避坑：

• 虽然可以使用 @Component 标记任何类为 Spring Bean，但建议根据类的职责使用 @Service、@Repository、@Configuration 等更具体的注解，以提高代码的可读性和可维护性。
• 确保你的类被 Spring 容器扫描到。通常，Spring Boot 会自动扫描启动类所在包及其子包下的所有类。如果你的类不在这些包下，需要使用 @ComponentScan 注解来指定扫描的包。

@Autowired 和 @Resource

@Autowired 和 @Resource 用于依赖注入。@Autowired 是 Spring 提供的注解，默认按照类型进行注入。@Resource 是 JSR-250 规范提供的注解，默认按照名称进行注入。当有多个相同类型的 Bean 时，@Autowired 可以结合 @Qualifier 注解来指定注入的 Bean 的名称。

@Service
public class UserServiceImpl implements UserService {

    @Autowired
    private UserRepository userRepository;

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

    // ...
}

实战避坑：

• 当有多个相同类型的 Bean 时，建议使用 @Qualifier 注解来明确指定注入的 Bean 的名称，避免出现歧义。
• 避免循环依赖。如果出现循环依赖，Spring Boot 会抛出 BeanCurrentlyInCreationException 异常。可以通过构造器注入或 Setter 注入来解决循环依赖问题。

数据访问相关注解

@Transactional

@Transactional 用于声明事务。它可以用于方法或类上。当用于方法上时，表示该方法中的所有操作都在同一个事务中。当用于类上时，表示该类中的所有方法都在同一个事务中。在配置分布式事务时，需要考虑使用 Seata 等组件，保证数据一致性，防止出现数据错乱的情况，特别是在高并发场景下。

@Service
public class UserServiceImpl implements UserService {

    @Autowired
    private UserRepository userRepository;

    @Transactional
    public void createUser(User user) {
        userRepository.save(user);
        // ...
    }
}

实战避坑：

• 默认情况下，@Transactional 注解只对 RuntimeException 和 Error 进行回滚。如果需要对 Checked Exception 进行回滚，需要显式地指定 rollbackFor 属性。
• 注意事务的传播行为。默认情况下，事务的传播行为是 REQUIRED，表示如果当前存在事务，则加入该事务；如果当前没有事务，则创建一个新的事务。

配置相关注解

@Value 和 @ConfigurationProperties

@Value 用于将配置文件中的属性值注入到 Bean 的字段中。@ConfigurationProperties 用于将配置文件中的一组属性值绑定到一个 Java Bean 中。在生产环境中，需要考虑使用 Nacos 或 Consul 等配置中心，动态更新配置，避免频繁重启应用。

@Component
public class AppProperties {

    @Value("${app.name}")
    private String name;

    @Value("${app.version}")
    private String version;

    // ...
}

@ConfigurationProperties(prefix = "database")
public class DatabaseProperties {

    private String url;
    private String username;
    private String password;

    // ...
}

实战避坑：

• 在使用 @ConfigurationProperties 注解时，需要确保配置文件中的属性名称与 Java Bean 的字段名称匹配。可以使用 @EnableConfigurationProperties 注解来启用 @ConfigurationProperties 注解。
• @Value 注解可以使用 SpEL 表达式来获取属性值。

通过以上对 Spring Boot 常用注解的分类整理和实例分析，希望能帮助你更好地理解和应用这些注解，在实际开发中更加得心应手。理解底层原理可以更好地应对复杂场景，例如在高并发环境下，如何优化数据库连接池配置，提高系统吞吐量，防止出现连接耗尽等问题。同时，不断学习新的技术和工具，例如 Kotlin、WebFlux 等，可以进一步提高开发效率和系统性能。