- 协议版本收敛为单一常量 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
314 lines
13 KiB
Python
Executable File
314 lines
13 KiB
Python
Executable File
#!/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()
|