前沿

你是否经历过这样的场景：前后端联调时，Swagger 文档看似完备，却频频因为“两个部门不能同时是责任部门”这类隐性规则而返工？根本原因在于我们把技术接口文档当成了业务规格的完整载体。本文从驾驭工程、规范文档、Skill 三者的职责边界切入，结合自动化测试平台的分层设计和 Java OpenAPI 扩展实践，给出从规则定义到工程落地的端到端解决方案。

---

一、一个经典翻车现场

产品需求：“一个合同可以关联多个部门，其中一个为责任部门，其余为配合部门。”
开发人员在 Swagger 定义接口：

department:
  type: object
  properties:
    deptId: string
    deptName: string
    isResponsible: boolean

联调时测试传来数据：

"departments": [
  { "deptId": "D001", "isResponsible": true },
  { "deptId": "D002", "isResponsible": true }
]

系统爽快地创建成功，没有校验，没有报错。原因出在哪？
Swagger 只描述了字段，没有描述规则——“同一合同下，有且仅有一个责任部门”这条业务不变性彻底丢失。

这不是偶然，而是规范文档、工程能力和个人技能三者责任真空的必然结果。下面我们先认清各自的边界，再用一个三层自动化测试平台的设计将规则彻底固化。

---

二、三者的核心职责边界

维度	核心职责	在隐性规则场景中的定位
规范文档	业务规则的唯一真相源，将隐性知识显性化、精确化	必须把“不能两个对象同时为责任部门”这类规则写清楚，而不只停留在口头或脑中
驾驭工程	将规则固化为可执行的设计与校验，防止退化	在后端、数据库、甚至前端做出防御性约束，让系统替人“记住”规则
Skill（技能）	在分析和沟通中挖掘、质疑、补全规则	有经验的工程师/BA 能在联调时、评审时，从例子中反推出缺失的约束

三者的关系：文档定规则，工程保执行，技能堵漏洞。

回到上面的例子：

• 规范文档应明确定义规则 R-001：“一个合同关联的部门列表中，isResponsible=true 的记录最多 1 条”。
• 工程侧需要后端做校验，请求进来时统计 isResponsible 数量，大于1直接返回业务错误。
• 个人技能要求在需求评审时多问一句：“两个部门能不能同时是责任方？”并在测试用例中覆盖这种异常组合。

只有三者各司其职，隐性规则才不会成为漏网之鱼。

---

三、用自动化测试平台将规则显性化

理论说清后，如何落地？我们设计一个分层的自动化测试平台，通过自动化层、智能化层、人工层的协作，让业务规则从文档到测试用例全链路可见、可执行。

3.1 平台三层架构

• 自动化层：处理结构化任务，降低 token 消耗。前端通过 ID 四层接口（模块-页面-组件-元素）让 UI 测试用例通过术语表自动映射。
• 智能化层（AI） ：根据业务规则文档，自动生成测试用例、补充边界值和等价类。比如根据规则 R-001 生成“两个责任部门”的异常用例。
• 人工层：兜底审查，确保 AI 生成的用例不偏离业务，保证安全。

核心挑战：定义一套同时满足可执行、AI可理解、人工可审查的用例结构。

3.2 测试用例的结构化设计（四层模型）

一个 API 测试用例拆为四层：

TestCase
├── Meta        # 元信息（来源、优先级、关联业务规则）
├── Context     # 上下文（环境、前置条件、术语绑定）
├── Steps       # 步骤序列（接口调用、等待、赋值）
└── Verdict     # 断言集（状态码、响应体、业务校验）

（1）Meta——为智能与人工设计

{
  "testId": "TC-API-001",
  "name": "创建合同-责任部门唯一性校验",
  "source": "ai-generated",
  "sourceRuleRefs": ["R-001"],
  "priority": "P0",
  "reviewStatus": "pending_review"
}

• sourceRuleRefs 让智能化层知道该用例验证哪条规则；
• reviewStatus 让人工层过滤待审批的 AI 用例，实现安全兜底。

（2）Context——术语映射与前置数据

{
  "baseUrl": "https://api.example.com",
  "preconditions": [
    { "action": "seed_data", "table": "departments", "data": "src/testdata/dept_A.json" },
    { "action": "login", "user": "admin" }
  ],
  "terminology": {
    "责任部门": { "field": "isResponsible", "valueMap": { "是": true, "否": false } },
    "合同主体": { "endpoint": "/api/contracts", "idField": "contractId" }
  }
}

术语表是桥梁：自动化层用它把业务术语直接映射到 API 字段或 UI 元素，极大降低 AI 生成成本。

（3）Steps——严格的可执行指令

[
  {
    "id": "step1",
    "type": "http",
    "method": "POST",
    "path": "/api/contracts",
    "body": {
      "subject": "合同1",
      "departments": [
        { "deptId": "${deptA.id}", "isResponsible": true },
        { "deptId": "${deptB.id}", "isResponsible": true }
      ]
    },
    "extract": { "responseContractId": "contractId" }
  }
]

自动化层直接解析执行，无需 AI 参与，极致节省 token。

（4）Verdict——分层断言

[
  { "on": "step1", "assert": "status", "equals": 400 },
  { "on": "step1", "assert": "jsonPath", "path": "$.errorCode", "equals": "DUPLICATE_RESPONSIBLE_DEPT" },
  { "on": "step1", "assert": "jsonPath", "path": "$.message", "contains": "只能指定一个责任部门" }
]

技术断言（状态码）与业务断言（错误码、提示）分离，业务断言可由 AI 根据规则文档生成。

3.3 与后端的契约约定

• OpenAPI + 业务规则扩展：在标准 OpenAPI 3.0 中通过 x-business-rules 扩展字段挂载规则摘要。
• 用例格式 Schema：定义一个标准 JSON Schema，后端提供 /testcases/validate 和 /testcases/run 接口，只执行 reviewStatus=approved 的用例。
• 协作流程：AI 服务读取规范文档和 OpenAPI → 生成符合 Schema 的用例 → 导入草稿区 → 人工审查 → 自动化引擎执行。

这样，业务规则文档真正成为唯一真相源，三层各自聚焦：工程负责稳、AI 负责全、人负责准。

---

四、Java 中的工程实践：用注解扩展 OpenAPI

要让智能化层能够自动发现业务规则，最好把规则“贴”在接口代码上。Java 生态中，Swagger Core 和 SpringDoc 提供了标准的扩展注解。

4.1 直接使用 @Extension 注解

@PostMapping("/contracts")
@Operation(summary = "创建合同")
@Extensions({
    @Extension(name = "x-business-rules", properties = {
        @ExtensionProperty(name = "ruleId", value = "R-001"),
        @ExtensionProperty(name = "desc", value = "部门列表中最多一个责任部门")
    })
})
public Contract createContract(@RequestBody ContractDTO dto) { ... }

生成的 OpenAPI 片段：

post:
  summary: 创建合同
  x-business-rules:
    ruleId: R-001
    desc: 部门列表中最多一个责任部门

4.2 自定义注解 + 全局扫描（推荐）

定义业务规则注解：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface APIBusinessRules {
    BusinessRule[] value();
    @interface BusinessRule {
        String ruleId();
        String description();
        String severity() default "ERROR";
        String[] examples() default {};
    }
}

实现 OperationCustomizer 自动扫描：

@Component
public class BusinessRuleCustomizer implements OperationCustomizer {
    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        APIBusinessRules rules = handlerMethod.getMethodAnnotation(APIBusinessRules.class);
        if (rules != null) {
            List<Map<String, Object>> ruleList = Arrays.stream(rules.value())
                .map(rule -> Map.of("ruleId", rule.ruleId(),
                    "description", rule.description(),
                    "severity", rule.severity(),
                    "examples", Arrays.asList(rule.examples())))
                .collect(Collectors.toList());
            operation.addExtension("x-business-rules", ruleList);
        }
        return operation;
    }
}

在 Controller 上使用：

@PostMapping("/contracts")
@APIBusinessRules({
    @BusinessRule(ruleId = "R-001", description = "部门列表中最多一个责任部门",
        examples = {"允许:[{true},{false}]", "拒绝:[{true},{true}]"}),
    @BusinessRule(ruleId = "R-002", description = "合同金额必须大于0")
})
public Contract createContract(@RequestBody ContractDTO dto) { ... }

这样，代码即文档，规则随 API 一同发布，智能化层可直接解析 OpenAPI 获得结构化规则，生成测试用例，从根本上解决规则遗漏。

---

五、总结

隐性业务规则的漏网，不是工具不够强，而是规范、工程、技能三者责任边界模糊。
要让规则不再“隐形”，我们需要：

1. 把业务规则写进规范文档，给予唯一 ID，用 Given-When-Then 或决策表精确描述。
2. 用工程手段将规则固化为校验逻辑和扩展元数据，让系统自动执行，避免人工记忆。
3. 提升团队技能，养成在分析、评审、测试中主动挖掘约束的习惯。
4. 设计分层自动化测试平台，以可扩展的用例结构连接 AI 生成与人工审查，让业务规则成为贯穿始终的一等公民。

从 Swagger 到 OpenAPI 扩展，从纸上规则到自动化断言，一步步把“隐性”变成“显性”，我们的软件才会更加健壮。希望这套思路能够帮助你的团队告别被遗忘的边界条件，让每一行代码都服务于真实的业务不变性。