Files
tdc-rs/scripts/contract_probe.py
T
admin 4b32b40bd6 feat(tds): 同步 ssw-tdc 最新 internal 契约并完成真 TDS 联调验证
- 协议版本收敛为单一常量 3.2,移除联调期自创的 env 覆盖
- 按真源同步 5 项契约:Dispute 下线、Billing/List 增 side、internalCatalog 6 过滤字段、新增 ServiceCatalog/Detail、出向方法收敛
- 修正 /api/** 未命中非 GET 请求被静态兜底判成 405 的偏差,恢复 404 契约
- 新增上游用例跨进程验证脚本与 4 份联调文档;部署级凭据只从环境变量读取
- 全量测试 308 passed;132 端点契约一致;真 TDS 21 条用例 19 PASS / 1 FAIL / 1 INFO
2026-11-05 17:53:15 +08:00

314 lines
13 KiB
Python
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env python3
"""契约对账:`docs/contract.md` 的端点表 ↔ **实际注册路由**(v3 spec §8 B5 验收)。
两种用法:
python3 scripts/contract_probe.py --gen
生成端点表(markdown 行)⇒ 往 `docs/contract.md` 里贴。
python3 scripts/contract_probe.py --base http://127.0.0.1:PORT
对账:
A. **路径完整性**:源码里注册/派生的每个路径都必须在文档表里,且**不多不少**
B. **方法准确性**:文档表里每个 (方法, 路径) 必须**真的注册**;
且每个路径上**运行时注册的方法集合** == 文档表的方法集合
(「已注册」⟺ 状态码 ∉ {404 路径没注册, 405 方法不对})
C. **端点总数**
🔴 **「真的注册」怎么判**(运行时探测,不是静态推断):
- 路径未注册 ⇒ **404**
- 路径注册但方法不对 ⇒ **405**(`platform::mw::json_method_not_allowed` 只改 body,不改状态码)
- 路径与方法都对 ⇒ 200 / 400 / 401 / 403 …
⇒ 「该方法已注册」⟺ status ∉ {404, 405}。
🔴 **为什么不用静态解析 Rust 源码拿方法**:`.route(p, get(..).post(..))` 的链式调用
跨多行、括号套嵌,正则脆得一碰就碎 ⇒ **方法以运行时探测为准**,静态侧只负责**路径全集**。
🔴 **零外部依赖**:只用标准库(`urllib` 显式禁用代理 ⇒ 不吃本机 HTTP_PROXY)。
"""
import argparse
import os
import re
import sys
import urllib.error
import urllib.request
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
DOC = os.path.join(ROOT, "docs", "contract.md")
BEGIN = "<!-- BEGIN ENDPOINTS -->"
END = "<!-- END ENDPOINTS -->"
METHODS = ["GET", "POST", "PUT", "DELETE"]
# ── 非 CRUD 端点的方法表(照抄各 controller 的 `.route(...)` 注册)────
LITERAL_METHODS = {
"/api/health": ["GET"],
"/api/ssw/tdc/Auth/Login": ["POST"],
"/api/ssw/tdc/Auth/Me": ["GET"],
"/api/ssw/tdc/Auth/Spaces": ["GET"],
"/api/ssw/tdc/Auth/SsoConfig": ["GET"],
"/api/oauth/Login": ["POST"],
"/api/permission/Users": ["GET", "POST"],
"/api/permission/Users/{id}": ["PUT", "DELETE"],
"/api/permission/Users/{id}/Actions/ResetPassword": ["POST"],
"/api/permission/Users/{id}/Actions/State": ["PUT"],
"/api/ssw/tdc/ServiceCatalog": ["GET"],
"/api/ssw/tdc/ServiceCatalog/Detail/{productCode}": ["GET"],
"/api/ssw/tdc/ServiceCatalog/Buy": ["POST"],
"/api/ssw/tdc/ServiceCatalog/BuyBatch": ["POST"],
"/api/ssw/tdc/Billing/List": ["GET"],
"/api/ssw/tdc/Billing/LocalCompare": ["GET"],
"/api/ssw/tdc/Billing/{id}/Confirm": ["PUT"],
"/api/ssw/tdc/Billing/{id}/Settle": ["PUT"],
"/api/ssw/tdc/Billing/{id}/Receipt": ["PUT"],
"/api/ssw/tdc/Billing/{id}/Voucher": ["GET"],
}
DESCRIPTIONS = {
"GET /api/health": "健康检查(**裸对象**,非业务信封)",
"POST /api/ssw/tdc/Auth/Login": "连接器身份登录(软 PKI,签发会话令牌)",
"GET /api/ssw/tdc/Auth/Me": "当前身份视图(**去敏**:不含私钥/一次性密钥;带 `roles`)",
"GET /api/ssw/tdc/Auth/Spaces": "环境空间列表",
"GET /api/ssw/tdc/Auth/SsoConfig": "SSO 配置(本仓恒 `enabled:false`)",
"POST /api/oauth/Login": "JNPF 兼容登录(表单:`account`/`password`(密文 hex)/`grant_type=password`)",
"GET /api/permission/Users": "用户管理 · 列表(**仅管理员**)",
"POST /api/permission/Users": "用户管理 · 新建(**仅管理员**)",
"PUT /api/permission/Users/{id}": "用户管理 · 改资料(**仅管理员**)",
"DELETE /api/permission/Users/{id}": "用户管理 · 删账号(**仅管理员**,逻辑删除)",
"POST /api/permission/Users/{id}/Actions/ResetPassword": "用户管理 · 重设口令(**仅管理员**)",
"PUT /api/permission/Users/{id}/Actions/State": "用户管理 · 启用/禁用(**仅管理员**)",
"GET /api/ssw/tdc/ServiceCatalog": "服务目录(出向 TDS `Catalog/Internal/Catalog`)",
"GET /api/ssw/tdc/ServiceCatalog/Detail/{productCode}": "目录详情(出向 TDS `Catalog/Detail/{productCode}?spaceId=`)",
"POST /api/ssw/tdc/ServiceCatalog/Buy": "目录下单(出向 TDS `TradeOrder/Internal/Apply`)",
"POST /api/ssw/tdc/ServiceCatalog/BuyBatch": "目录批量下单(出向 TDS `TradeOrder/Internal/ApplyBatch`)",
"GET /api/ssw/tdc/Billing/List": "本方账单列表(出向 TDS `BillingLedger/Internal/List`)",
"GET /api/ssw/tdc/Billing/LocalCompare": "本地计量比对(读本地 `tdc_api_consume_log`,**零出向**)",
"PUT /api/ssw/tdc/Billing/{id}/Confirm": "账单确认(出向 TDS `BillingLedger/{id}/Confirm`)",
"PUT /api/ssw/tdc/Billing/{id}/Settle": "账单结算(出向 TDS `BillingLedger/{id}/Settle`)",
"PUT /api/ssw/tdc/Billing/{id}/Receipt": "收据(出向 TDS `BillingLedger/{id}/Receipt`)",
"GET /api/ssw/tdc/Billing/{id}/Voucher": "对账凭证(出向 TDS `BillingLedger/{id}/Voucher`)",
}
CRUD_DESCRIPTIONS = {
"list": "分页列表(业务信封 `data.list` + `data.pagination`)",
"all": "全量列表(不分页,仍是业务信封)",
"detail": "详情(部分实体带子表挂载 ⇒ 见 §子表聚合)",
"create": "新增(`no_create` 的实体拒绝)",
"update": "修改(`no_update` 的实体拒绝;冻结列拒改)",
"delete": "逻辑删除(`no_delete` 的实体拒绝)",
}
def read(path):
with open(path, "r", encoding="utf-8") as fh:
return fh.read()
def entity_specs():
"""从 `src/tdc/entity/*.rs` 解析每个实体的 api_name / path / aggregate_detail。"""
out = []
ent_dir = os.path.join(ROOT, "src", "tdc", "entity")
for name in sorted(os.listdir(ent_dir)):
if not name.endswith(".rs") or name == "mod.rs":
continue
text = read(os.path.join(ent_dir, name))
api = re.search(r'api_name:\s*"([^"]+)"', text)
path = re.search(r'path:\s*"([^"]+)"', text)
agg = re.search(r'aggregate_detail:\s*(true|false)', text)
if not (api and path):
continue
out.append(
{
"api_name": api.group(1),
"path": path.group(1),
"aggregate": bool(agg and agg.group(1) == "true"),
"file": "src/tdc/entity/%s" % name,
}
)
return out
def source_paths():
"""源码侧的**路径全集**(controller 字面量 + 注册表派生)。"""
paths = set()
ctl_dir = os.path.join(ROOT, "src", "tdc", "controller")
for name in sorted(os.listdir(ctl_dir)):
if not name.endswith(".rs"):
continue
text = read(os.path.join(ctl_dir, name))
for m in re.finditer(r'"(/api/[^"]*)"', text):
paths.add(m.group(1))
for spec in entity_specs():
p = spec["path"]
paths.add(p)
paths.add(p + "/All")
paths.add(p + "/{id}")
if spec["aggregate"]:
paths.add(p + "/{id}/Detail")
return paths
def gen_rows():
"""生成 markdown 行(按分组排,组内按路径/方法排)。"""
ents = entity_specs()
rows = []
def add(meth, path, desc):
rows.append("| %s | `%s` | %s |" % (meth, path, desc))
# 1. 健康检查
for meth in LITERAL_METHODS["/api/health"]:
add(meth, "/api/health", DESCRIPTIONS["GET /api/health"])
# 2. 连接器身份(Auth/*)
for path in sorted(p for p in LITERAL_METHODS if p.startswith("/api/ssw/tdc/Auth/")):
for meth in LITERAL_METHODS[path]:
add(meth, path, DESCRIPTIONS["%s %s" % (meth, path)])
# 3. 账号层
acct = sorted(p for p in LITERAL_METHODS if p.startswith("/api/permission/") or p == "/api/oauth/Login")
for path in acct:
for meth in LITERAL_METHODS[path]:
add(meth, path, DESCRIPTIONS["%s %s" % (meth, path)])
# 4. 实体 CRUD(18 × 6 + 2 聚合体)
for spec in sorted(ents, key=lambda s: s["api_name"]):
p = spec["path"]
name = spec["api_name"]
add("GET", p, "%s · %s" % (name, CRUD_DESCRIPTIONS["list"]))
add("GET", p + "/All", "%s · %s" % (name, CRUD_DESCRIPTIONS["all"]))
add("GET", p + "/{id}", "%s · %s" % (name, CRUD_DESCRIPTIONS["detail"]))
add("POST", p, "%s · %s" % (name, CRUD_DESCRIPTIONS["create"]))
add("PUT", p + "/{id}", "%s · %s" % (name, CRUD_DESCRIPTIONS["update"]))
add("DELETE", p + "/{id}", "%s · %s" % (name, CRUD_DESCRIPTIONS["delete"]))
for spec in sorted(ents, key=lambda s: s["api_name"]):
if spec["aggregate"]:
add(
"GET",
spec["path"] + "/{id}/Detail",
"%s · 只读聚合体(挂子表:见 §子表聚合)" % spec["api_name"],
)
# 5. TDS 出向
tds = sorted(
p
for p in LITERAL_METHODS
if p.startswith("/api/ssw/tdc/ServiceCatalog") or p.startswith("/api/ssw/tdc/Billing")
)
for path in tds:
for meth in LITERAL_METHODS[path]:
add(meth, path, DESCRIPTIONS["%s %s" % (meth, path)])
return rows
def parse_doc_table(doc=DOC):
"""从 `docs/contract.md` 抠出端点表 ⇒ [(方法, 路径)]。"""
text = read(doc)
if BEGIN not in text or END not in text:
sys.stderr.write("❌ %s 缺 BEGIN/END ENDPOINTS 标记\n" % doc)
sys.exit(2)
block = text.split(BEGIN, 1)[1].split(END, 1)[0]
rows = []
for line in block.splitlines():
line = line.strip()
if not line.startswith("|"):
continue
cols = [c.strip() for c in line.strip("|").split("|")]
if len(cols) < 2:
continue
meth = cols[0].strip()
path = cols[1].strip().strip("`")
if meth not in METHODS:
continue
rows.append((meth, path))
return rows
def probe(base, meth, path, token=None):
"""返回 HTTP 状态码(404 / 405 / 2xx / 4xx…)。
🔴 **必须带内部令牌**:鉴权中间件在**路由之前**就拦(`src/platform/auth.rs`),
未带凭证 ⇒ 任何 /api/** 请求都先回 **401**(连 404 都到不了)
⇒ 不带令牌探针会把「所有方法都 401」误判成「所有方法都注册」。
"""
url = base + path.replace("{id}", "probe-id")
headers = {"X-Internal-Token": token} if token else {}
req = urllib.request.Request(
url, method=meth, data=b"" if meth in ("POST", "PUT") else None, headers=headers
)
opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
try:
with opener.open(req, timeout=10) as resp:
return resp.status
except urllib.error.HTTPError as exc:
return exc.code
except Exception as exc: # noqa: BLE001
return "ERR:%s" % exc
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--gen", action="store_true", help="生成端点表")
ap.add_argument("--base", help="后端基址(对账用)")
ap.add_argument("--doc", default=DOC)
ap.add_argument("--token", default=None, help="内部令牌(探针必带,否则全被 401 拦掉)")
args = ap.parse_args()
if args.gen:
rows = gen_rows()
print("\n".join(rows))
print("<!-- 共 %d 行 -->" % len(rows))
return
if not args.base:
sys.stderr.write("用法:--gen 或 --base http://127.0.0.1:PORT\n")
sys.exit(2)
doc_rows = parse_doc_table(args.doc)
doc_paths = {p for _, p in doc_rows}
expected_paths = source_paths()
failures = []
# A. 路径完整性(源码 ↔ 文档,双向)
for path in sorted(expected_paths - doc_paths):
failures.append("源码有路由但文档表缺该路径:%s" % path)
for path in sorted(doc_paths - expected_paths):
failures.append("文档表有该路径但源码没有:%s" % path)
# B. 方法准确性(运行时探测)
documented = {}
for meth, path in doc_rows:
documented.setdefault(path, set()).add(meth)
for path in sorted(doc_paths):
registered = set()
for meth in METHODS:
status = probe(args.base, meth, path, args.token)
# 🔴 404 = 路径没注册;**405 = 路径注册了但这个方法不允许** ⇒ 两种都不算「该方法已注册」。
if status not in (404, 405):
registered.add(meth)
if registered != documented.get(path, set()):
failures.append(
"方法集合不一致 %s:运行时={%s} 文档={%s}"
% (path, ",".join(sorted(registered)), ",".join(sorted(documented.get(path, set()))))
)
total = len(doc_rows)
print("端点表行数:%d" % total)
print("源码路径全集:%d 条(CRUD 实体 %d 个)" % (len(expected_paths), len(entity_specs())))
if failures:
print("\n❌ 不一致 %d 处:" % len(failures))
for f in failures[:60]:
print(" - %s" % f)
if len(failures) > 60:
print(" … 还有 %d 处" % (len(failures) - 60))
sys.exit(1)
print("✅ 端点表与实际注册路由完全一致(%d 条端点)" % total)
if __name__ == "__main__":
main()