CASE CONTRACT · V1

输入输出标准

用例结构

每个用例由元信息、请求和预期响应组成。音频 Blob 单独存储，以免污染 JSON 定义。

{
  "schema_version": 1,
  "name": "f 发成 bu 不应高分",
  "request": {
    "method": "POST",
    "path": "/v1/evaluate",
    "fields": { "word": "f" }
  },
  "expected": {
    "status": 200,
    "mode": "subset",
    "max_latency_ms": 8000,
    "body": {
      "evaluation_type": "SUBSTITUTION",
      "avg_score": { "$lte": 40 }
    }
  }
}

字段级输出定义

每一行对应一个需要校验的 JSON Path。删除一行即表示不校验该字段；接口模板会自动填入建议的关键字段和默认校验方式。

“完整 JSON（高级）”会直接编辑同一个 expected.body，可随时与字段列表相互转换。

字段校验方式

存在且非空非空字符串、数组或对象 字段存在字段存在，值不限 任意数字/字符串只校验值类型 候选值之一参数填写 JSON array 数值范围参数填写 { "$gte": 0, "$lte": 100 } 数组长度设置最少/最多元素个数 全部/至少一个元素通过 [*] 对数组元素字段进行校验 正则匹配参数填写正则表达式 字段不存在断言该 JSON Path 不应出现

匹配模式

Subset 只检查预期 JSON 中声明的字段，适合包含 request id、时间戳等动态信息的接口。

Exact 同时把实际响应中的额外字段标记为差异，适合严格契约回归。

共享语料库与自测

共享语料库存在服务端，是团队共同的回归基准。任何人发布的用例和录音，其他人登录后都能直接跑。每次发布记录提交人和说明，可以查看版本历史并回滚。

自测只存在你这台浏览器里，用来录音、试跑、反复改。确认有价值之后再「发布到共享」。共享用例也可以「复制到自测」改着玩，不影响别人。

接口模板（Method、Path、字段）随镜像发布，改它需要发版；加一个坏例不需要。

数据边界

服务器地址、用例和录音均保存在当前浏览器。导出包可选择携带 base64 音频，便于交接；页面不会把配置发送到其他服务。

发布到共享语料库

版本历史

每次发布都是一个不可变的版本。回滚只是把当前指针移回去，不会删除任何历史。