一次面向初学者的完整实战：从零构建SpringBoot测试类

目录

一、问题的提出 

二、准备工作：依赖与目录结构

三、被测代码简介

四、编写第一个测试类

五、逐行解读：注解与运行时行为

六、运行测试的三种方式

七、运行结果示例

八、常见错误与排查策略

九、测试设计的延伸思考

十、JUnit5 的简洁写法

十一、结语

---

一、问题的提出 

        在日常开发中，我们往往先写出业务 Mapper、Service 或 Controller，随后才想起“应该补一个测试”。这种做法虽然普遍，却容易让测试沦为事后的形式化检查。更好的顺序是：在编写任何持久层或业务层代码时，同步给出可运行的单元或集成测试。本文的目标即是在 Spring Boot 环境下演示这一同步过程，并以一段针对 Mapper 层的查询测试为例，展示如何从零开始构建一个可靠、可重复、易维护的测试类。

---

二、准备工作：依赖与目录结构

        任何测试代码都必须首先解决“运行环境”问题。Spring Boot 官方在 spring-boot-starter-test 中封装了 JUnit、Spring Test、AssertJ、Mockito 等常用库。因此，只要我们在 pom.xml 中声明如下依赖，即可获得完整的测试栈：

    org.springframework.boot
    spring-boot-starter-test
    test

        一旦依赖下载完毕，Maven 会按照约定把测试代码与资源分别放置在 src/test/java 与 src/test/resources。保持这一目录结构并非可有可无的“规矩”，而是 Spring Boot 在自动扫描测试配置时的默认起点。忽视这一点往往会导致“测试类无法注入 Bean”的初级错误。

---

三、被测代码简介

        为了使讨论具体而不空泛，本文使用一个简化的车辆管理系统作为示例。系统包含三张表：brands、models、admins，分别对应品牌、车型、管理员。持久层采用 MyBatis，并通过通用 Mapper 模式生成 BrandsMapper、ModelsMapper、AdminsMapper 三个接口。接口的签名形如：

public interface ModelsMapper {
    List selectList(Q query);
}

        其中 ModelsQuery 是一个纯粹用于封装查询条件的 POJO，字段包括 descriptionFuzzy、launchDateStart、launchDateEnd 等。为了让示例聚焦“测试”而非“业务”，本文假设上述接口与 XML 映射文件均已正确实现，且数据库中存在少量测试数据。

---

四、编写第一个测试类

        依赖就绪、被测代码存在之后，编写测试类的第一步是选择运行器（Runner）。在 JUnit4 体系中，SpringRunner 是官方推荐的与 Spring TestContext 框架集成的桥梁；在 JUnit5 中，这一角色由 SpringExtension 扮演。考虑到多数存量项目仍停留在 JUnit4，本文先以 JUnit4 为例，再在最后给出 JUnit5 的简要改写。

测试类的完整骨架如下：

package com.lxk.test;

import com.lxk.RunDemoApplication;
import com.lxk.mappers.ModelsMapper;
import com.lxk.query.ModelsQuery;
import com.lxk.entity.Models;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

import javax.annotation.Resource;
import java.util.List;

@SpringBootTest(classes = RunDemoApplication.class)
@RunWith(SpringRunner.class)
public class MapperTest {

    @Resource
    private ModelsMapper modelsMapper;

    @Test
    public void selectList() {
        ModelsQuery modelsQuery = new ModelsQuery();
        modelsQuery.setDescriptionFuzzy("一款顶级超级跑车");
        modelsQuery.setLaunchDateStart("2016-03-01");
        modelsQuery.setLaunchDateEnd("2016-03-01");

        List list = modelsMapper.selectList(modelsQuery);
        list.forEach(System.out::println);
    }
}

---

五、逐行解读：注解与运行时行为

1. @SpringBootTest(classes = RunDemoApplication.class)
   该注解告诉 Spring Boot：在启动测试上下文时，使用 RunDemoApplication 作为配置入口。这样做的好处是，整个 Spring 容器会按正常启动流程加载，包括自动配置、组件扫描、数据源初始化等。

2. @RunWith(SpringRunner.class)
   JUnit4 的 Runner 机制允许第三方框架介入测试生命周期。SpringRunner 在测试开始前创建 ApplicationContext，在测试结束后关闭它，并负责将 @Resource 或 @Autowired 标注的字段注入到测试实例。

3. @Resource
   这是 JSR-250 标准定义的注入注解，等价于 @Autowired(required = true)，但按名称而非类型匹配。由于 Mapper 接口在容器中只有一个实现，使用 @Resource 或 @Autowired 均可。

4. @Test
   JUnit4 的核心注解。方法必须为 public void，无参，无返回值。测试框架通过反射调用该方法，并在断言失败或抛出异常时标记为失败。

---

六、运行测试的三种方式

1. IDE 内执行
   IntelliJ IDEA 或 Eclipse 会自动识别类路径下的 JUnit 注解，并在方法左侧生成绿色三角。点击即可运行。

2. Maven 命令
   在项目根目录执行 mvn test，Maven Surefire 插件会扫描 **/Test*.java、**/*Test.java 等命名模式的类，并汇总结果到 target/surefire-reports。

3. Gradle 命令
   若项目使用 Gradle，则执行 ./gradlew test，结果位于 build/test-results。

        无论哪种方式，成功的标志是控制台输出若干条形如 Models(id=..., name=...) 的日志，并且构建工具报告 Tests run: 1, Failures: 0。

---

七、运行结果示例

---

八、常见错误与排查策略

1. NoSuchBeanDefinitionException
   错误信息提示找不到 ModelsMapper 类型的 Bean。根因多半是 @MapperScan 未扫描到 Mapper 接口，或测试目录的包名与主代码脱节。

2. Failed to load ApplicationContext
   通常是数据源配置错误，例如 spring.datasource.url 指向了不存在的数据库。在测试环境中，推荐使用 H2 等内存库，并通过 application-test.yml 隔离配置。

3. 日期格式解析失败
   若实体字段为 LocalDate 而查询条件为字符串 "2016-03-01"，需要在 ModelsQuery 中显式使用 @DateTimeFormat 或手动转换，否则 MyBatis 绑定参数时会抛出类型不匹配异常。

4. 日志级别过高导致刷屏
   在测试资源目录下新建 logback-test.xml，把 root level 设为 WARN，可显著减少控制台噪音，同时保留失败时的堆栈信息。

---

九、测试设计的延伸思考

        虽然本文示例仅执行了一次查询并打印结果，但在真实项目中，测试应回答以下问题：

• 当查询条件为空时，是否返回全表数据？

• 当日期区间非法（结束早于开始）时，是返回空集合还是抛出异常？

• 当模糊查询关键字包含 SQL 通配符 _ 或 % 时，是否做了转义？
  为了覆盖这些场景，我们可以在同一测试类中继续追加多个 @Test 方法，或使用参数化测试（JUnit5 的 @ParameterizedTest）。此外，若业务依赖外部服务（如第三方 REST 接口），则应引入 Mock 框架（Mockito、MockK）或 Testcontainers 启动真实中间件副本，以确保测试的稳定性与可重复性。

---

十、JUnit5 的简洁写法

        对于新项目，官方已全面转向 JUnit5。迁移成本极低：只需把 spring-boot-starter-test 升级到 2.4 以上版本，并改写为：

@SpringBootTest(classes = RunDemoApplication.class)
class MapperTest {

    @Autowired
    ModelsMapper modelsMapper;

    @Test
    void selectList() {
        ...
    }
}

        JUnit5 默认不再需要 @RunWith，因为 SpringExtension 已通过 @SpringBootTest 隐式注册。此外，JUnit5 的断言 API 更丰富，如 assertAll、assertThrows，可进一步提高测试表达力。

---

十一、结语

        测试并非锦上添花，而是软件交付流程中的必要环节。Spring Boot 通过自动配置与统一的测试注解，将繁琐的基础设施问题封装起来，使开发者得以把注意力集中在“验证行为是否符合预期”这一本质任务上。本文通过一个最小可运行的示例，逐步展示了依赖引入、测试类编写、运行方式、错误排查以及设计演进的全过程。希望读者在实践之后，能够形成“先写测试、再写实现”的肌肉记忆，从而在未来的项目中收获长期而稳定的质量红利。