springboot-verification

用途

Spring Boot 验证循环（Verification Loop）是一个面向 Spring Boot 项目的质量关卡流程，用于在合并请求（PR）之前、重大重构或依赖升级之后，以及预发布或生产环境部署之前执行系统化验证。其目标是在代码进入主干或上线前，通过构建、静态分析、测试、安全扫描和差异审查等阶段，尽早暴露问题，避免后期“惊喜”。

主要能力

该技能提供一条完整的流水线：构建（Build）→ 代码检查（Lint）→ 测试（Test）→ 安全扫描（Security Scan），并验证测试覆盖率是否达到阈值。具体包括：

构建阶段：使用 Maven 或 Gradle 执行清理与编译，构建失败即停止并修复。
静态分析阶段：通过 SpotBugs、PMD、Checkstyle 等插件检查代码质量。
测试与覆盖率阶段：运行单元测试、集成测试和 API 测试，并生成 JaCoCo 覆盖率报告，验证覆盖率是否达到 80% 以上。
安全扫描阶段：扫描依赖项 CVE 漏洞、源码中的密钥/敏感信息、Git 历史记录中的敏感信息，并检查常见安全问题（如 System.out.println、原始异常信息泄露、通配符 CORS 配置）。
代码检查/格式化阶段（可选关卡）：使用 Spotless 等工具统一代码风格。
差异审查阶段：通过 git diff 检查变更，确认无遗留调试日志、错误信息与 HTTP 状态码有意义、事务与校验到位、配置变更已记录文档。

使用方式

该技能以命令和检查清单的形式组织，按阶段顺序执行。

第一阶段：构建

mvn -T 4 clean verify -DskipTests
# 或者
./gradlew clean assemble -x test

如果构建失败，请停止并修复。

第二阶段：静态分析

Maven（常用插件）：

mvn -T 4 spotbugs:check pmd:check checkstyle:check

Gradle（如果已配置）：

./gradlew checkstyleMain pmdMain spotbugsMain

第三阶段：测试与覆盖率

mvn -T 4 test
mvn jacoco:report   # 验证 80% 以上的覆盖率
# 或者
./gradlew test jacocoTestReport

报告内容需包含测试总数、通过/失败数，以及覆盖率百分比（行/分支）。

单元测试通过模拟依赖隔离测试服务逻辑，示例：

@ExtendWith(MockitoExtension.class)
class UserServiceTest {

  @Mock private UserRepository userRepository;
  @InjectMocks private UserService userService;

  @Test
  void createUser_validInput_returnsUser() {
    var dto = new CreateUserDto("Alice", "alice@example.com");
    var expected = new User(1L, "Alice", "alice@example.com");
    when(userRepository.save(any(User.class))).thenReturn(expected);

    var result = userService.create(dto);

    assertThat(result.name()).isEqualTo("Alice");
    verify(userRepository).save(any(User.class));
  }

  @Test
  void createUser_duplicateEmail_throwsException() {
    var dto = new CreateUserDto("Alice", "existing@example.com");
    when(userRepository.existsByEmail(dto.email())).thenReturn(true);

    assertThatThrownBy(() -> userService.create(dto))
        .isInstanceOf(DuplicateEmailException.class);
  }
}

使用 Testcontainers 进行集成测试，针对真实数据库而非 H2：

@SpringBootTest
@Testcontainers
class UserRepositoryIntegrationTest {

  @Container
  static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
      .withDatabaseName("testdb");

  @DynamicPropertySource
  static void configureProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.datasource.url", postgres::getJdbcUrl);
    registry.add("spring.datasource.username", postgres::getUsername);
    registry.add("spring.datasource.password", postgres::getPassword);
  }

  @Autowired private UserRepository userRepository;

  @Test
  void findByEmail_existingUser_returnsUser() {
    userRepository.save(new User("Alice", "alice@example.com"));

    var found = userRepository.findByEmail("alice@example.com");

    assertThat(found).isPresent();
    assertThat(found.get().getName()).isEqualTo("Alice");
  }
}

使用 MockMvc 进行 API 测试，在完整的 Spring 上下文中测试控制层：

@WebMvcTest(UserController.class)
class UserControllerTest {

  @Autowired private MockMvc mockMvc;
  @MockBean private UserService userService;

  @Test
  void createUser_validInput_returns201() throws Exception {
    var user = new UserDto(1L, "Alice", "alice@example.com");
    when(userService.create(any())).thenReturn(user);

    mockMvc.perform(post("/api/users")
            .contentType(MediaType.APPLICATION_JSON)
            .content("""
                {"name": "Alice", "email": "alice@example.com"}
                """))
        .andExpect(status().isCreated())
        .andExpect(jsonPath("$.name").value("Alice"));
  }

  @Test
  void createUser_invalidEmail_returns400() throws Exception {
    mockMvc.perform(post("/api/users")
            .contentType(MediaType.APPLICATION_JSON)
            .content("""
                {"name": "Alice", "email": "not-an-email"}
                """))
        .andExpect(status().isBadRequest());
  }
}

第四阶段：安全扫描

# 依赖项 CVE 漏洞扫描
mvn org.owasp:dependency-check-maven:check
# 或者
./gradlew dependencyCheckAnalyze

# 源码中的密钥/敏感信息 (Secrets)
grep -rn "password\s*=\s*\"" src/ --include="*.java" --include="*.yml" --include="*.properties"
grep -rn "sk-\|api_key\|secret" src/ --include="*.java" --include="*.yml"

# 密钥/敏感信息 (Git 历史记录)
git secrets --scan  # 如果已配置

常见安全问题检查：

# 检查 System.out.println (应使用 logger 代替)
grep -rn "System\.out\.print" src/main/ --include="*.java"

# 检查响应中是否包含原始异常信息
grep -rn "e\.getMessage()" src/main/ --include="*.java"

# 检查通配符 CORS 配置
grep -rn "allowedOrigins.*\*" src/main/ --include="*.java"

第五阶段：代码检查/格式化（可选关卡）

mvn spotless:apply   # 如果使用了 Spotless 插件
./gradlew spotlessApply

第六阶段：差异审查

git diff --stat
git diff

检查清单：

未遗留调试日志（System.out，无守卫的 log.debug）
错误信息和 HTTP 状态码具有明确意义
在需要的地方包含事务（Transactions）和校验（Validation）
配置变更已记录文档

输出模板：

验证报告 (VERIFICATION REPORT)
===================
构建 (Build):     [通过/失败]
静态分析 (Static): [通过/失败] (spotbugs/pmd/checkstyle)
测试 (Tests):     [通过/失败] (X/Y 通过, Z% 覆盖率)
安全 (Security):  [通过/失败] (CVE 漏洞发现: N)
差异 (Diff):      [X 个文件已变更]

总体状态 (Overall): [准备就绪 / 尚未就绪]

待修复问题：
1. ...
2. ...

持续模式（Continuous Mode）：在发生重大变更时，或在长会话期间每 30–60 分钟重新运行各阶段。保持短循环：运行 mvn -T 4 test + spotbugs 以获取快速反馈。

适用场景

为 Spring Boot 服务开启合并请求（Pull Request）之前。
在重大重构（Refactoring）或依赖（Dependency）升级之后。
预发布或生产环境部署（Deployment）前的验证。
长会话期间需要周期性重新验证时。

限制

该技能以 Maven 和 Gradle 为主要构建工具，示例命令和插件配置基于这两种工具；其他构建方式暂未提供。安全扫描中的 git secrets --scan 需要预先配置。覆盖率阈值示例为 80% 以上，实际阈值可能因项目而异。该技能强调“将警告视为缺陷”，在生产系统中保持严格关卡。

技能介绍

用途

主要能力

使用方式

适用场景

限制