springboot — Harness 示例

基于 Martin Fowler 提出的 Harness Engineering 理念，为 Spring Boot Web 项目搭建的最小可用 harness。

核心思路：让 agent（ClaudeCode）写代码之前，先给它修一条能回家的路。

项目结构

springboot-example/
├── CLAUDE.md                              # Feedforward: agent 规则（铁律在最前）
├── docs/ai/                               # 项目知识库
│   ├── index.md                           # 项目知识库索引
│   ├── architecture.md                    # 架构说明
│   └── api-contracts.md                   # API 契约
├── scripts/agent-check.sh                 # 后置检查 : 自动检查脚本
├── checkstyle.xml                         # 代码风格规则（检查代码格式）
├── spotbugs-exclude.xml                   # SpotBugs 排除规则（防止逻辑缺陷检查过于严格）
├── src/main/java/com/example/user/
│   ├── controller/UserController.java     # HTTP 入口，参数校验，返回 DTO
│   ├── service/UserService.java           # 业务逻辑，事务边界
│   ├── mapper/UserMapper.java             # MyBatis 接口
│   ├── model/User.java                    # 数据库实体
│   └── dto/                               # 请求/响应 DTO
├── src/main/resources/
│   ├── application.yml                    # 数据库配置
│   ├── schema.sql                         # 建表脚本
│   ├── data.sql                           # 初始化数据
│   └── mapper/UserMapper.xml              # SQL（全部用 #{} 绑定）
└── src/test/
    ├── java/.../architecture/LayeringTest.java    # ArchUnit 分层测试
    ├── java/.../controller/UserControllerTest.java # Controller 测试，包含 HTTP 方法
    ├── java/.../service/UserServiceTest.java      # Service 测试，包含业务逻辑
    ├── java/.../FixtureDrivenTest.java            # fixture 驱动的验收测试
    └── resources/fixtures/user-create-success.json

Harness 的三层控制

1. Feedforward：事前引导

CLAUDE.md 在 agent 开工前告诉它：

• 分层规则：Controller → Service → Mapper，禁止穿透
• SQL 安全：只用 #{}，禁止 ${}
• 日志安全：禁止输出密钥、token、手机号等敏感信息
• 完成前必须运行 ./scripts/agent-check.sh

2. Architecture Fitness：架构守护

ArchUnit 测试自动检查分层边界：

layeredArchitecture()
    .layer("Controller").definedBy("..controller..")
    .layer("Service").definedBy("..service..")
    .layer("Mapper").definedBy("..mapper..")
    .whereLayer("Mapper").mayOnlyBeAccessedByLayers("Service")

agent 如果在 Controller 里直接调 Mapper，测试立刻红。

3. Feedback：事后检查

scripts/agent-check.sh 按顺序执行：

检查	工具	抓什么
单元测试 + 架构测试	mvn test	功能正确性、分层边界
代码风格	checkstyle:check	命名、import、花括号、行宽
静态分析	spotbugs:check	空指针、资源泄漏、返回值忽略

4. Behaviour Harness：fixture 驱动

关键输入输出由人确认，agent 不能改：

{
  "request": { "username": "wangwu", "email": "wangwu@example.com" },
  "expectedResponse": { "username": "wangwu", "status": "ACTIVE" }
}

• fixture 是人类确认的验收样例，agent 不得为了让测试通过而修改它
• 新增行为可以新增 fixture，但要说明业务含义
• 修改 fixture 必须在 PR 描述里单独解释

快速开始

# 运行测试
./mvnw test

# 运行完整检查（agent 每次改完代码必须跑这个，后期可以配置在 CI/CD 中运行）
./scripts/agent-check.sh

API 接口

方法	路径	说明
POST	/api/users	创建用户
GET	/api/users	获取所有用户

技术栈

• Java 8 + Spring Boot 2.7
• MyBatis（XML mapper，#{} 参数绑定）
• MySQL 8.0
• ArchUnit（架构测试）
• Checkstyle + SpotBugs（静态检查）