《Spring Boot 入门》附录 A：常用注解速查

本篇目标：把全书正文里散落的注解收拢成按用途分类的速查表，让你在写代码时能一眼查到「这个注解属于哪一层、在哪个包、对应哪一节」，并附一张 3.x 到 4.x 的变更对照表供迁移时核对。
适用版本：Spring Boot 4.1.x（Java 21）

附录 A 常用注解速查

正文 18 章把「为什么这样设计」讲透了，这一页只做一件事：把写代码时真正会去翻的注解压成表。建议第一次通读建立索引感，之后把它当案头卡片——写的时候不必回忆章节号，先在这里对号入座，再回正文看完整推导。

表里的「所在包」一列均按 4.x 口径给出。 4.0 起 Spring Boot 做了模块化重构，少数注解的包位置发生了变化（例如 @EntityScan 与 @PropertyMapping），这类差异集中列在本页末尾的「3.x → 4.x 注解与包名变更对照表」里，正文其余部分不再重复。

怎么用这张表

这张表按「注解在应用里扮演什么角色」分类，而不是按字母顺序。使用它的方式有三种：

• 写代码时查包名：不记得某个注解该 import 哪个包，先在对应分类里找到它，再复制包名。
• 读代码时反查：看到一个陌生注解，先在表里确认它属于哪一层，再翻到「详见章节」看它的完整行为。
• 迁移时对照：从 3.x 项目迁到 4.x，先看末尾的变更对照表，把已移除或改名的注解一次性替换掉。

需要提醒的是，速查表只能帮你「定位」，不能帮你「理解」。一个注解为什么存在、什么时候该用、什么时候不该用，仍然要看正文。尤其是 @Transactional、@ConditionalOnMissingBean、@Validated 这几个，写法只有一行，但行为受很多条件影响，值得回到对应章节读透。

① 启动与配置类

这一组注解决定「应用从哪启动、哪些类算配置、自动配置从哪来」。

@SpringBootApplication 是入口注解，但它本身几乎不做事，真正的启动逻辑由它引入的 @EnableAutoConfiguration 触发——这一层在 4.2 节会拆开讲。写自定义自动配置时，优先用 @AutoConfiguration 而不是裸的 @Configuration，因为前者额外携带了「什么时候该加载」的元数据约定。

② 组件与依赖注入

这一组注解决定「哪些对象交给容器、它们之间怎么互相拿到」。

一个常见困惑是「@Component、@Service、@Repository 到底有什么区别」。答案是：在容器眼里它们几乎等价，差别只在语义与少数副作用——@Repository 会额外把底层异常翻译成 Spring 的数据访问异常体系。选哪个，看这个类在架构里扮演什么角色，而不是看功能。

③ 生命周期

这两个注解来自 Jakarta 规范而非 Spring 自身，因此包里是 jakarta.annotation。它们的执行时机与构造器不同：构造器执行时依赖还没注入完，@PostConstruct 执行时依赖已经就绪。要真正搞清它们的顺序，需要理解 Bean 的生命周期回调，见 5.3 节。

④ 条件装配

这一组是自动配置的核心，决定「一个配置类到底要不要生效」。

其中 @ConditionalOnMissingBean 是「可被用户覆盖的默认值」这一设计的关键：框架先声明一个默认实现，但只要你自己的配置里提供了同类型 Bean，默认实现就让位。理解这一点，就能明白为什么「我写了一个 ObjectMapper，为什么自动配置的没生效」——答案往往就在这里。

⑤ Web

这组注解有一个共同点：它们大多只是「声明」，真正让它们生效的是 DispatcherServlet 启动时建立的那张映射表。所以当某个注解「没起作用」时，排查思路通常是「这个处理器有没有被注册到映射表里」，而不是「注解拼错了没有」。

⑥ 校验

@Valid 与 @Validated 的区别值得记住：前者是标准注解，负责「触发校验」；后者是 Spring 的扩展，额外支持「分组」与「方法级校验」。需要按场景分组校验时用 @Validated，见 9.3 节。

⑦ 数据与事务

JPA 注解来自 jakarta.persistence，与 Spring 无关；@Query 与 @Modifying 是 Spring Data JPA 的扩展；@Transactional 则来自 Spring 的事务模块。三者分属不同层次，混在一起用时要清楚每个注解「归谁管」——尤其 @Transactional 是基于代理生效的，同类内部调用不会触发它，这是 14.3 节要讲的经典坑。

⑧ 测试

这里最容易踩坑的是 4.x 的一条行为变更：@SpringBootTest 不再自动附带 MockMvc 与 TestRestTemplate，需要 @AutoConfigureMockMvc、@AutoConfigureTestRestTemplate 显式声明。如果你从 3.x 迁移测试代码，测试类会因为找不到这些组件而报错，补上对应的 @AutoConfigure* 注解即可。

3.x → 4.x 注解与包名变更对照表

从 3.x 迁移到 4.x 时，下面这些注解要么被移除，要么改了名，要么挪了包。先按这张表把代码过一遍，再启动项目，能省下大量「编译不过却看不出原因」的时间。

几条配套说明：

• @MockitoBean / @MockitoSpyBean 有一条硬约束：它们只能用在测试类上，不能用在 @Configuration 类里。3.x 时代有人把 @MockBean 塞进配置类做「测试专用装配」，4.x 起这条路径被明确堵死。
• @MockitoBean 的包路径也变了，从 Spring 自己的包迁到了 org.springframework.test.context.bean.override.mockito，迁移时留意 import。
• @SpringBootTest 不再自带 MockMvc 与 TestRestTemplate：这虽然不算注解改名，但同样是「按旧写法照抄会失效」的典型，故一并提醒。
• 空安全注解的迁移影响面很广：org.springframework.lang.Nullable 被 org.jspecify.annotations.Nullable 取代后，凡是显式 import 旧包的位置都要替换。如果只是用注解而不 import，通常不受影响。

下面是一段符合 4.x 口径的最小组合示例，把上面几类注解放在同一个文件里，供你对照包名：

package com.example.book;

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/books")
public class BookController {

    private final BookService service;

    public BookController(BookService service) {
        this.service = service;
    }

    @GetMapping("/{id}")
    public Book find(@PathVariable Long id) {
        return service.findById(id);
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Book create(@Valid @RequestBody BookForm form) {
        return service.create(form);
    }

    public record BookForm(@NotBlank String title) {
    }
}

这段代码没有写 import 之外的任何 Spring 配置，但它已经覆盖了「控制器、路由、路径变量、请求体、校验、状态码、依赖注入」七件事——这正是 Spring Boot「约定优于配置」的直观体现。

注解的层次关系

Spring Boot 的注解可以粗略分成三层，理解层次有助于判断一个注解「归谁管」：

• Spring 核心层（org.springframework.context / org.springframework.beans）：@Configuration、@Bean、@Autowired、@Component 系列。它们管的是「对象如何被创建和装配」。
• Spring Boot 层（org.springframework.boot）：@SpringBootApplication、@AutoConfiguration、@ConditionalOn*、@ConfigurationProperties。它们管的是「在什么条件下自动装配什么」。
• 规范层（jakarta.*）：@PostConstruct、@Valid、@Entity 等。它们由 Jakarta 规范定义，Spring 只是支持它们。

分清这三层，你就能在遇到问题时快速判断「该去查 Spring 的文档，还是查 Jakarta 的文档」，也能理解为什么有些注解换一个框架依然可用。

几个容易混淆的注解

一个配置类示例

注解速查之外，一个常见的困惑是「配置类该怎么写」。下面这段示例把启动与配置类那一组注解放在一起：

@AutoConfiguration
@EnableConfigurationProperties(BookProperties.class)
public class BookAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public BookFormatter bookFormatter(BookProperties properties) {
        return new BookFormatter(properties.getPrefix());
    }
}

配合下面的属性类：

@ConfigurationProperties(prefix = "app.book")
public class BookProperties {

    private String prefix = "book";

    // getter / setter 省略
}

@AutoConfiguration 让这个类被识别为自动配置；@EnableConfigurationProperties 让属性类生效；@ConditionalOnMissingBean 保证用户自定义的 BookFormatter 能覆盖这个默认值。这三者组合起来，就是一个最小可用的「可被覆盖的自动配置」。更完整的自定义 starter 流程见 7.2 节。

按场景查注解

比起按分类逐个回忆，从「我要做的事」出发反查往往更快：

这张表里的每一项，都能在正文里找到对应的完整示例与解释。速查表的作用是让你「想起还有这么一个注解」，至于它怎么用、什么时候会失效，仍要回到正文。

小结

• 速查表的价值在于「定位」而非「理解」：先用表找到注解属于哪一层、在哪个包，再回正文看它的完整行为。
• 八类里最需要理解而非记忆的是条件装配：@ConditionalOnMissingBean 决定了「默认值可被覆盖」这一核心设计。
• 校验里分清 @Valid（触发）与 @Validated（分组），Web 里分清 @Controller（视图）与 @RestController（响应体）。
• 数据层要记住注解分属三套体系：jakarta.persistence 管映射，Spring Data 管查询，Spring 管事务。
• 迁移到 4.x 时，先按末尾的变更对照表把 @MockBean / @SpyBean 等替换掉，再启动项目——@MockBean 与 @SpyBean 在 4.x 已被移除。
• 需要查配置项而不是注解时，请看附录 B 的配置速查；需要查构建脚本时，看附录 C 的 Maven 与 Gradle 对照。