行为- diff —— ADLC C14
用于 P6 人行门. 审查 变了什么 在行为, 不是五千行长 捕获可观测到的HTTP表面(状态、内容类型、体) 结构)在变化前后,然后diffs在行为空间:"3个终点 换了外形,1去掉,其他的都一样"
代码diff为5000行;行为diff为6项. 人文审查 意图对行为 ——唯一判断机器不能作出——同时显示 (C11)证明机器已经做了其余的.
ADLC 阶段
P6 — 人行门由人文审查员在出道时直接使用.
与 gate-manifest (C11): 清单证明机器检查通过;行为差异
证明可观察到的行为在预期范围内.
动词
capture
点击配置文件中的每个路径, 将可观察到的 HTTP 行为记录到 JSON 示意图.
behavior-diff capture --config behavior.json --out before.json
旗帜 :
| 旗帜 | 需求 | 说明 |
|---|---|---|
--config <path> | 对 | JSON 文件的行为配置路径 |
--out <path> | 对 | 快取 JSON 输出路径 |
--json | 没有 | 打印机器可读结果摘要到 stdout |
配置格式 (单位:千美元)behavior.json:
{
"baseUrl": "http://localhost:3000",
"routes": [
{ "method": "GET", "path": "/health" },
{ "method": "GET", "path": "/api/users" },
{ "method": "POST", "path": "/api/items", "body": { "name": "test" } },
{ "method": "GET", "path": "/api/data", "headers": { "Accept": "application/json" } }
]
}
每条路线: { method, path, body?, headers? }。 。 。 . body 序列化为 JSON 与
Content-Type: application/json 自动添加.
记录每条路由错误 (截至 { method, path, error }(不中止)
运行。 该快照中总是包含每个配置路径的条目.
抓取的退出代码 :
| 代码 | 含义 |
|---|---|
0 | 所有路线都尝试过, 至少一个可以到达; 快照写入( 有些路线可能错误) Name |
1 | 操作错误: 配置文件无法读取, 无效配置, 无法写入输出 |
compare
比较两个快照,并产生一个人可读的行为报告.
behavior-diff compare before.json after.json [--json]
旗帜 :
| 旗帜 | 需求 | 说明 |
|---|---|---|
--json | 没有 | 打印机器可读的 diff 结果到 stdout |
产出(人可读):
2 routes identical, 2 changed, 0 errored
+ GET /metrics: route added (absent in before, present in after)
~ GET /health:
body (json): 2 changes:
~ version: "1.0.0" → "2.0.0"
+ newField: "added"
~ GET /users:
status: 200 → 503
body (json): 2 changes:
- users: [...]
+ error: "Service Unavailable"
Diff 规则 :
- 匹配的路线
METHOD path。 。 。 . - 状况变化:直接报告.
- 内容类型变化:报告(参数如下):
; charset=utf-8页:1. - JSON身体:结构递归diff. 路径使用点标记( I)
body.items[3].price) (中文(简体) ). 阵列: 长度变化报告 + 第一个不同的索引已钻入 。 潜入了50道. - 文字/二元体:由SHA-256散列作比较.
- 道路只进入前 ~"删除"。 只有"加"之后的路线.
比较的退出代码 :
| 代码 | 含义 |
|---|---|
0 | 出入口——所有路线相同 |
1 | 操作错误: 快照文件无法读取或无效的 JSON |
2 | 门失败——一个或多个路线被更改、去除或添加 |
典型的工作流程
# Before the change: capture baseline
behavior-diff capture --config behavior.json --out before.json
# Make your code change, restart the service, then:
behavior-diff capture --config behavior.json --out after.json
# Review behavior diff (exits 0 if clean, 2 if changes found)
behavior-diff compare before.json after.json
抓图格式
{
"baseUrl": "http://localhost:3000",
"capturedAt": "2024-01-15T10:30:00.000Z",
"routes": [
{
"method": "GET",
"path": "/health",
"status": 200,
"contentType": "application/json",
"body": { "status": "ok" }
},
{
"method": "GET",
"path": "/large-html",
"status": 200,
"contentType": "text/html",
"body": { "textHash": "sha256hex...", "bytes": 4096 }
},
{
"method": "GET",
"path": "/broken",
"error": "timeout after 10000ms"
}
]
}
- JSON回应:身体被解析并存储为JSON值.
- 非JSON反应: 被储存为
{ textHash, bytes }。 。 。 . - 错误: 路由存储为
{ method, path, error }(无状态/机构).
未来工作(请注意)
浏览器/ 无头模式 ——通过无头浏览器渲染路由,diff渲染出 DOM 或者截图 已记录为今后的工作;尚未执行。 HTTP 固定模式 (此工具) 是当前支持的模式 .
核心差距
无。 此工具自成一体, 只使用 parseArgs, (中文(简体) ), pass, (中文(简体) ), gateFail, (中文(简体) ),
opError,以及 printJson 从 @adlc/core。在本地通过
node:crypto 而不是核心 sha256 帮助避免对齐抓取
序列化格式到共享库.