#!/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 = "" END = "" 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/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}/Dispute": ["PUT"], "/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`)", "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}/Dispute": "账单异议(出向 TDS `BillingLedger/{id}/Dispute`)", "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("" % 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()