SpringBoot 的测试老实说不少项目里是被当成“可有可无”的那部分。Controller 写完直接启动应用Postman 点两下能通就完事。但等你真正开始维护一个超过半年、接口超过二十个的项目就会明白没有一个像样的测试体系兜底每一次重构都像在雷区里跳舞。Spring Boot 之所以在测试这件事上值得单独写一篇是因为它把“测试”从一件需要折腾基础设施的苦差事变成了框架原生支持、开箱即用的能力。这篇内容主要面向两类读者一是想给现有项目补测试但不知从何下手的开发者二是刚接触 Spring Boot 测试、被一堆注解和依赖搞晕的新手。我会从依赖怎么引、注解怎么用、MockMvc 怎么写、数据库层怎么测到真实环境下的集成测试、常见踩坑点完整过一遍。全程都是实操角度没有虚的你能照着抄、照着改。1. 为什么SpringBoot测试值得单独开一篇1.1 测试金字塔与SpringBoot的定位是什么先聊一个概念测试金字塔。这是我在实际项目里越来越有体会的东西。金字塔从下往上分别是单元测试、集成测试、端到端测试。最底层数量最多、运行最快、成本最低越往上越慢、越贵、越脆弱。很多团队一开始就写端到端测试启动整个应用、连数据库、调外部接口跑一遍要几分钟还动不动因为网络波动挂了。这本质上是在用最贵的方式覆盖最多逻辑性价比极差。Spring Boot 的测试生态恰恰是围绕这个金字塔设计的。你既能用 Mockito 做纯单元测试完全不启动 Spring 上下文也能用 SpringBootTest 启动完整上下文做集成测试还能用 WebMvcTest、DataJpaTest 这类“切片测试”只加载 Web 层或持久层需要的部分。这种“按需加载”的能力是很值钱的它让你可以在不同层级上用不同成本做验证而不是一测就要拉起整个应用。1.2 依赖引入与基础版本选型做 Spring Boot 测试第一个动作永远是引入依赖。绝大多数情况下你只需要一个dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency这一个依赖会帮你带上 JUnitSpring Boot 3.x 对应 JUnit 5、AssertJ、Mockito、JSONAssert、Spring Test 等一整套测试工具。用 Maven 的话IDEA 右侧的 Maven 面板打开 Dependency Hierarchy 可以看到它帮你拉了一堆子依赖还是相当贴心的。有人会另外单独引 JUnit 或者 AssertJ其实没必要只要用了 spring-boot-starter-test通常你常用的测试组件都齐了。提示Spring Boot 2.4 之后spring-boot-starter-test 不再自动包含 Testcontainers。如果你要用 Testcontainers得单独引依赖后面讲到真实环境集成测试时我会详细说。还有个小细节项目里如果同时有 mockito-core 和 mockito-inline某些版本会冲突。我自己碰到过 mockito-inline 覆盖了 spring 提供的核心 mock导致 MockBean 行为异常的情况。所以能靠 starter-test 统一依赖就尽量不要手动加 Mockito 相关的东西。2. 核心注解与运行机制拆解2.1 SpringBootTest最常用也最容易被误解SpringBootTest 是集成测试的主力注解。它的作用是启动一个 Spring 应用上下文让测试里的 Autowired 都能正常注入。往深了说它会根据测试类所在的包向上找 SpringBootConfiguration 注解的配置类然后以它为基准加载上下文。这里面有个常见的困惑SpringBootTest 到底启不启动 Web 服务器默认情况下它用的是 MOCK 环境也就是说它不会启动真实的 Servlet 容器而是用一个模拟的 Web 环境配合 MockMvc 去测试 Controller。如果你确实想启动真实端口比如要测 WebSocket 或者做端口级联调就要设置SpringBootTest(webEnvironment SpringBootTest.WebEnvironment.RANDOM_PORT)RANDOM_PORT 会随机挑一个可用端口启动真实容器避免端口冲突。对应的测试里可以用 LocalServerPort 拿到实际端口这对一次跑多条测试、多模块并行构建的场景特别重要。我必须提醒一点SpringBootTest 加载的是完整上下文包括数据源、Redis、MQ 连接等。如果你的项目里这些基础设施连不上测试启动就会直接失败。这也是为什么后面的“切片测试”和“配置隔离”如此重要它们能帮你把测试成本降下来。2.2 WebMvcTest只测 Controller 层项目里如果只想测 Controller 的逻辑比如参数校验、返回结构、状态码没必要把 Service 和 Repository 全部加载进来。这时候用 WebMvcTest它只会加载 Web 层的 BeanController、ControllerAdvice、过滤器等不会碰 Service。WebMvcTest(UserController.class) class UserControllerTest { // ... }但问题来了Controller 里面往往依赖 ServiceService 没被加载Autowired 就会报错。解决方式是用 MockBean 把 Service 打桩。下面是一段很典型的写法WebMvcTest(UserController.class) class UserControllerTest { Autowired private MockMvc mockMvc; MockBean private UserService userService; Test void shouldReturnUser() throws Exception { User user new User(1L, 张三); given(userService.findById(1L)).willReturn(user); mockMvc.perform(get(/users/1)) .andExpect(status().isOk()) .andExpect(jsonPath($.name).value(张三)); } }用 WebMvcTest 跑出来的测试速度非常快启动时间通常在几百毫秒到一两秒比 SpringBootTest 动不动几十秒舒服太多了。实测下来一个三十个左右的接口项目如果纯用 WebMvcTest整个 Controller 层的测试跑完不到两分钟。2.3 DataJpaTest持久层测试的轻量方案如果只想测试 Repository 的 SQL 写法、关联查询、分页逻辑用 DataJpaTest。它会只加载 JPA 相关组件和数据源默认用内嵌数据库替换你的真实数据库测试完还自动回滚事务不会污染数据。DataJpaTest class UserRepositoryTest { Autowired private UserRepository userRepository; Test void shouldFindByName() { User saved userRepository.save(new User(李四)); OptionalUser found userRepository.findByName(李四); assertThat(found).isPresent(); assertThat(found.get().getName()).isEqualTo(李四); } }这里有个关键点DataJpaTest 默认替换数据源。如果你项目里用的是 MyBatis需要换成 MybatisTestMyBatis 官方或第三方 starter 提供的切片注解如果你用的是 Postgres 且 SQL 里有 Postgres 专属语法H2 可能不兼容就得考虑集成真实数据库的测试方案了。这一点放在第 4 部分展开。2.4 JUnit 5 与 AssertJ断言别再用老套写法Spring Boot 3.x 默认带的是 JUnit 5也就是 JUnit Jupiter。它和 JUnit 4 的区别不仅仅是注解包名从org.junit.Test变成了org.junit.jupiter.api.Test更重要的是生命周期、参数化测试、断言机制都变了。断言方面我强烈建议用 AssertJ链式写法可读性比 JUnit 自带的断言语感好太多assertThat(result).isNotNull() .extracting(User::getName) .isEqualTo(王五); assertThat(userList).hasSize(3) .extracting(User::getName) .contains(张三, 李四);链式写法的好处是“读起来像一句人话”。老式的 assertEquals 在参数多、断言多的时候很难一眼看出哪个是期望值哪个是实际值。AssertJ 的assertThat(actual).isEqualTo(expected)方向感明确配合extracting还能直接把对象字段抽出来比较非常实用。3. 实操过程与核心环节实现3.1 从零写一个单元测试Service 层打桩很多人拿到代码不知道怎么开始写测试。我的经验是从 Service 层的纯业务逻辑起步这一步不需要启动 Spring跑起来毫秒级反馈最快。假设这个 Service 的职责是“用户注册”核心逻辑包括用户名不能重复、密码长度校验、注册后发通知。用 Mockito 打桩把 UserRepository 和 NotifyClient 都 mock 掉只验业务规则class UserServiceImplTest { private UserRepository userRepository; private NotifyClient notifyClient; private UserServiceImpl userService; BeforeEach void setUp() { userRepository mock(UserRepository.class); notifyClient mock(NotifyClient.class); userService new UserServiceImpl(userRepository, notifyClient); } Test void shouldThrowWhenUsernameExists() { given(userRepository.findByName(张三)).willReturn(Optional.of(new User(张三))); assertThatThrownBy(() - userService.register(张三, 12345678)) .isInstanceOf(BusinessException.class) .hasMessageContaining(用户名已存在); } Test void shouldSendNotificationAfterRegister() { given(userRepository.findByName(李四)).willReturn(Optional.empty()); userService.register(李四, 12345678); verify(notifyClient).send(any(User.class)); } }这种测试不依赖任何 Spring 机制纯手工 new 对象反而更能逼你把依赖设计得清晰。一个 Service 如果构造函数的依赖太多、太碎写测试时你会立刻感受到痛苦这种痛苦本身就是重构的信号。3.2 Controller 层MockMvc 完整实战Controller 测试是大家最关心的部分因为接口的对外行为都在这层。MockMvc 的核心思路是“不启动真实服务器但模拟完整的 HTTP 请求处理链路”从请求分发、参数绑定、注解处理到响应的序列化整个流程都会走一遍。一个覆盖比较全面的 Controller 测试长这样WebMvcTest(UserController.class) class UserControllerTest { Autowired private MockMvc mockMvc; MockBean private UserService userService; Autowired private ObjectMapper objectMapper; Test void shouldCreateUser() throws Exception { UserCreateRequest request new UserCreateRequest(王五, password123); mockMvc.perform(post(/users) .contentType(MediaType.APPLICATION_JSON) .content(objectMapper.writeValueAsString(request))) .andExpect(status().isCreated()) .andExpect(jsonPath($.id).exists()) .andExpect(jsonPath($.name).value(王五)); verify(userService).create(any(UserCreateRequest.class)); } Test void shouldReturn400WhenNameIsBlank() throws Exception { UserCreateRequest request new UserCreateRequest(, password123); mockMvc.perform(post(/users) .contentType(MediaType.APPLICATION_JSON) .content(objectMapper.writeValueAsString(request))) .andExpect(status().isBadRequest()); } }第一个测试验证的是“正常链路”请求能进 Controller、参数正确绑定、Service 被调用、返回结构和状态码都符合预期。第二个测试验证“异常链路”参数校验不过时必须返回 400。这两个“正一负”的组合是接口测试的基本盘每个接口至少应该覆盖这两条。注意用 ObjectMapper 将请求对象转成 JSON比手写 JSON 字符串要可靠。手写字符串一旦字段名拼错测试失败的原因会非常难排查看起来是逻辑问题实际是拼接问题。很多新人会忽略一个点MockMvc 测试要想触发 Valid 注解的参数校验需要在测试类上加一个东西吗如果你用的是 WebMvcTest并且在 Controller 上正确用了 Valid校验是自动生效的不需要额外配置。真正容易漏掉的是 ControllerAdvice 里的全局异常处理比如你自定义了错误响应结构WebMvcTest 默认会加载项目里的 ControllerAdvice所以测试时可以放心断言自定义错误体。3.3 数据访问层H2 内存库与 SQL 测试数据访问层的测试如果你用的是 JPA 且 SQL 比较标准DataJpaTest H2 内存库完全够用。运行快测试间互不影响因为每个测试都是事务回滚的。DataJpaTest class UserRepositoryTest { Autowired private UserRepository userRepository; Autowired private TestEntityManager entityManager; Test void shouldFindUsersByStatus() { entityManager.persist(new User(张三, Status.ACTIVE)); entityManager.persist(new User(李四, Status.INACTIVE)); ListUser users userRepository.findByStatus(Status.ACTIVE); assertThat(users).hasSize(1) .extracting(User::getName) .containsExactly(张三); } }TestEntityManager 是 Spring Boot 测试框架提供的一个工具类你可以在测试里手动往数据库塞数据、清数据而不必经过业务代码这样针对性更强。但这里要认真提醒H2 的 SQL 解析和真实数据库不是完全一致的。比如 Postgres 的 JSONB 类型、数组类型的字段H2 支持得就很差某些 MySQL 特有关键字H2 在特定模式下也可能报错。我遇过最典型的情况是H2 里跑得好好的分页查询换到 Postgres 就发现排序不稳定。所以这种测试的定位应该是“验证 Repository 方法逻辑和基本 SQL 语法”而不是“替真实数据库做校验”。3.4 集成测试完整上下文下的真实场景单元测试、切片测试都过了之后一定还需要至少一两个真正的集成测试验证各组件拼在一起能不能通。比如用户注册这条完整链路Controller 接收请求 - Service 处理业务 - Repository 存库。切片测试只能分别验证每层但层与层之间的装配问题必须用集成测试覆盖。SpringBootTest(webEnvironment SpringBootTest.WebEnvironment.RANDOM_PORT) class UserRegisterIntegrationTest { Autowired private TestRestTemplate restTemplate; Test void shouldRegisterUser() { UserCreateRequest request new UserCreateRequest(赵六, password123); ResponseEntityMap response restTemplate.postForEntity( /users, request, Map.class); assertThat(response.getStatusCode().is2xxSuccessful()).isTrue(); assertThat(response.getBody()).containsKey(id); } }RANDOM_PORT 会启动真实容器TestRestTemplate 走的是真实 HTTP 调用这比 MockMvc 更接近生产状态。为什么还留一条 MockMvc因为 RANDOM_PORT 测试慢、启动重、依赖真实组件不适合每个接口都来一遍。合理组合是Controller 层多用 WebMvcTest 快测挑 2 到 3 条核心业务链路写 SpringBootTest 集成测试。集成测试最大的挑战是外部依赖。如果项目里有 Redis、Kafka、MySQL而测试环境里没有这些服务就会启动失败。这个问题先记住下一部分我会讲怎么用 Testcontainers 解决。4. 测试配置与运行环境隔离4.1 application-test.yml 与配置覆盖测试环境必须和生产环境做配置隔离这是底线。你肯定不想测试用例跑着跑着往生产数据库写数据。Spring Boot 天然支持src/test/resources/application-test.yml测试时通过ActiveProfiles(test)激活。一个典型的测试配置长这样spring: datasource: url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY-1;DB_CLOSE_ON_EXITFALSE driver-class-name: org.h2.Driver jpa: hibernate: ddl-auto: create-drop redis: # 如果测试里不需要真实 Redis这里可以配置为内嵌模式或用 Mock注意ddl-auto: create-drop的选择逻辑测试时每次启动都重新建表测试完销毁保证环境干净。还有一种场景某个外部服务在测试环境根本不存在比如短信平台。正确做法不是在测试配置里硬写一个假地址而是用 MockBean 或者配置一个 stub。很多项目是因为这个没处理好导致测试机器一离线整个测试就全红。4.2 Testcontainers用真实数据库做测试H2 虽然快但终究不是生产用的数据库。要想让数据访问层测试更接近真实用 Testcontainers 是个靠谱的方案。它的思路很简单通过 Docker 启动一个真实数据库容器项目里写 SQL数据库就给你跑真实 SQL。DataJpaTest AutoConfigureTestDatabase(replace AutoConfigureTestDatabase.Replace.NONE) Import(PostgresTestContainerConfig.class) class UserRepositoryTest { Container static PostgreSQLContainer? postgres new PostgreSQLContainer(postgres:15-alpine); // 测试代码... }这里有两个关键点一是 DataJpaTest 默认会替换数据源要用 AutoConfigureTestDatabase(replace NONE) 关掉替换二是一定要配一个静态容器在所有测试类里共享否则每个测试类都起一个数据库容器资源消耗大、启动时间长。注意 Testcontainers 本身对 Docker 有依赖CI 环境需要支持 Docker。如果团队里有人机器上没装 Docker这类测试在他的本地会失败。我的建议是把 Testcontainers 测试单独标记用 Tag 区分确保本地日常开发时可以直接跳过只有 CI 或者专门的集成测试阶段才跑。5. 常见问题与排查技巧实录5.1 测试之间互相污染数据串了怎么办测试 A 造了一条数据导致测试 B 断言失败。这个我太熟了。根因通常是测试方法之间共享了 Spring 上下文而代码里没有做好隔离。排查路径一般是这样的确认数据访问层的测试是否被 DataJpaTest 的事务回滚保护。Service 层测试如果用了真实数据库检查是否继承了某个基类基类里是否有 BeforeEach 的清理逻辑。静态变量、内存缓存比如 ConcurrentHashMap 做的缓存最隐蔽测试 A 往缓存里写了测试 B 读到了极难排查。遇到这种情况优先在 BeforeEach 里手动清缓存。一个通用且务实的技巧所有持久层测试统一继承一个抽象基类基类里定义好清理策略。这样新成员写测试时不需要每次都考虑数据清理直接继承基础类就能保证环境干净。5.2 SpringBootTest 启动慢到怀疑人生一个大型项目完整上下文可能要加载几十秒十几个测试类跑下来好几分钟。这里有几个立竿见影的优化方向第一尽量用切片测试替代完整启动。Controller 用 WebMvcTestRepository 用 DataJpaTest能避免加载不需要的 Bean。第二确认测试类之间是否复用了同一个上下文。Spring 会做上下文缓存相同配置的测试类共享上下文但如果每个测试类都改 MockBean缓存就会失效每改一个 MockBean 都相当于重新启动一次应用。第三检查测试配置里是否引入了大量不必要的外部连接能关就关。我曾经处理过一个项目测试套件从 6 分钟优化到 1 分半主要就是做了两件事把大而全的 SpringBootTest 拆成了切片测试梳理了 MockBean 的使用让上下文能被复用。5.3 jsonPath 断言失败大部分是结构问题jsonPath 断言是 Controller 测试里最容易出问题的地方。你以为返回结构是这样实际却是那样。排查建议第一次调试时先打印响应体String responseBody mockMvc.perform(get(/users/1)) .andReturn() .getResponse() .getContentAsString(StandardCharsets.UTF_8); System.out.println(responseBody);看到真实 JSON 结构后再对着写 jsonPath。注意嵌套层级最深的地方比如$._embedded.users[0].name。还有一点Spring Boot 默认的 JSON 序列化会把带下划线的字段转成驼峰或者反过来如果实体里的字段是userName而第三方要求user_name这个转换过程也会让 jsonPath 断言踩坑。5.4 测试中文乱码MockMvc 测试响应中文乱码是经典问题。根因是响应的 Character Encoding 没有设置成 UTF-8。解决方式是在测试里显式声明字符集mockMvc.perform(get(/users/1).accept(MediaType.APPLICATION_JSON)) .andExpect(status().isOk());但更底层的方案是保证应用的 Content-Type 里带charsetUTF-8。Spring Boot 3.x 里RestController 返回字符串时默认字符集一般是 UTF-8但如果项目里手动配置了 StringHttpMessageConverter或者频繁用 ResponseEntity 拼接字符串就容易把中文变乱码。在测试配置里设置server.servlet.encoding.forcetrue也是个兜底办法。5.5 一个实战避坑清单最后把这些年攒下的经验整理成一个清单方便你对照检查问题原因解决方案MockBean 导致测试上下文不缓存每次注入的 Mock 对象变化尽量用构造函数注入配合 Mockito 的 mock()少用 MockBean数据库测试跑完但数据还在缺事务回滚或清理逻辑DataJpaTest 默认有回滚自定义的数据源测试需手动清理MockMvc post 请求 415 错误忘记设置 contentType请求里必须显式contentType(MediaType.APPLICATION_JSON)测试时间不稳定有真实网络调用没打桩找到 Feign/HTTP 客户端用 MockBean 替换或使用 WireMockTestcontainers 启动极慢每次新建容器静态容器共享减少withReuse以外的资源消耗同一个测试类里多个测试共享数据缺乏隔离机制BeforeEach 清库或刷新缓存必要时用 AfterEach这个清单不是一次性整理的是我在多个项目里被这几种问题反复折磨过后沉淀下来的。每一条背后都是真实的排查过程。6. 从能跑到跑好测试维护的两点建议测试写好了只是第一步真正难的是让测试在项目演进过程中始终保持价值。这里有两个建议特别想说。第一把测试当成代码来 review。不要因为测试代码不进入生产环境就降低标准。变量命名、断言粒度、是否引入了不稳定的时间依赖这些都要在 review 的时候被看到。我见过太多“永远通过的假测试”断言全是isNotNull()跑一百次全绿但 function 改成返回 null 照样通过——这种测试除了占时间没有任何意义。第二关注测试的“失败模式”。好的测试失败时你能立刻定位到问题坏测试失败时你得先花半小时搞清楚是代码坏了还是测试坏了。避免坏测试的一个重要手段是避免在断言里写入过多的实现细节。比如只关心“调用结果是否正确”而不关心“内部调用了哪个私有方法”“传入了哪个临时变量”。还有一个小技巧每次提交代码前跑一遍mvn test如果某个测试跑挂了先看是指断言的期望值还是测试环境的配置。常出问题的测试类和经常挂的模块会形成一种“狼来了”效应团队成员会慢慢不信任测试这是最危险的信号。我用 SpringBoot 测试的体会是框架层面的工具再强大测试最终的质量还是取决于开发者愿不愿意把边界想清楚。从 WebMvcTest 到 DataJpaTest从 Mockito 到 Testcontainers选型没有绝对的高下只有适不适合当下场景。给 Controller 写轻量的切片测试、给核心链路写集成测试、给数据访问层按需用真实数据库,这个组合我在多个项目里验证过稳、快、维护成本低。如果你们团队还没有一套像样的测试骨架这一篇可以直接拿去当起点依葫芦画瓢先落几个测试进去用起来再逐步优化。