#!/usr/bin/env python3 """上游动作端点普查:把「上游有、本仓没有」的动作端点按**路径形态**分成两类。 用法: python3 scripts/upstream-action-census.py # 打印普查表 python3 scripts/upstream-action-census.py --json # 机器可读 🔴 **为什么要有这个脚本**: `docs/known-limitations.md` 的 L5(上游动作端点未实现)与 L7(通用详情路由 **吞掉**单段尾动作端点)都带具体数字 ⇒ 数字必须**可复算**,不能只写在散文里。 本脚本只读上游克隆(`/tmp/sswtdc-probe`),**不碰本仓任何东西**。 🔴 **口径**(与 L5/L7 的措辞一一对应): ① 范围 = 18 个 `extends TdcCrudController` 的控制器**自己声明**的 method-level 映射(`@GetMapping` / `@PostMapping` / `@PutMapping` / `@DeleteMapping`, 含**空路径**写法)。 —— CRUD-6 基线(列表 GET / `All` GET / `{id}` GET·PUT·DELETE / POST 创建) **住在基类** `TdcCrudController` 里,子类不重复声明 ⇒ 不在计数里。 ② 扣掉 **6 条 CRUD `{id}` 覆写**(子类显式重写基类的 `@PutMapping("/{id}")` / `@DeleteMapping("/{id}")` 以禁写)—— 本仓**已实现**这些路径。 ③ 扣掉 **2 条只读聚合体** `Resource/{id}/Detail` · `Dataset/{id}/Detail` —— 本仓 B3 已实现。 ④ 剩下的按**尾段数**分两类: · 形态 A = `/{Entity}/{action}`(**恰好 1 个尾段**) ⇒ 本仓的通用详情路由 `/{Entity}/{id}`(`src/tdc/controller/crud.rs`) **会先匹配上** ⇒ 请求**不会 404**,而是走到 detail 处理器 ⇒ 查出「记录不存在」⇒ **HTTP 200 + `code:400`**。 · 形态 B = `/{Entity}/{x}/{y}`(**≥2 个尾段**) ⇒ 本仓无此路由 ⇒ **真 404**。 """ import argparse import json import os import re import sys UPSTREAM_ROOT = os.environ.get("SSW_TDC_UPSTREAM", "/tmp/sswtdc-probe") CTRL_DIR = os.path.join( UPSTREAM_ROOT, "boot/ssw-tdc/ssw-tdc-controller/src/main/java/ssw/tdc/controller" ) # 本仓 B3 已实现的只读聚合体 AGGREGATE_DETAIL = { "/api/ssw/tdc/Resource/{id}/Detail", "/api/ssw/tdc/Dataset/{id}/Detail", } MAPPING_RE = re.compile(r'@(Get|Post|Put|Delete)Mapping(\(\s*"([^"]*)"\s*\))?') # 18 个实体的 api_name(与本仓 `src/tdc/entity/mod.rs` 的 `ALL_SPECS` 一一对应)。 ENTITIES = [ "ApiConsumeLog", "AuditLog", "Contract", "Credential", "DataInterface", "Dataset", "Datasource", "DeliveryLog", "DeliveryTask", "DestroyLog", "Identity", "Notification", "Order", "Policy", "PolicyCheckLog", "PolicyTemplate", "Product", "Resource", ] def crud_baseline(): """CRUD-6 基线(基类 `TdcCrudController` 提供,子类**也会重复声明**): 列表 GET / 创建 POST / `All` GET / `{id}` GET·PUT·DELETE。 ⇒ 这些**不是**动作端点,本仓**全部已实现**,必须扣掉。 """ base = set() for e in ENTITIES: p = "/api/ssw/tdc/" + e base.add(("GET", p)) base.add(("POST", p)) base.add(("GET", p + "/All")) base.add(("GET", p + "/{id}")) base.add(("PUT", p + "/{id}")) base.add(("DELETE", p + "/{id}")) return base def segs(path): return [s for s in path.strip("/").split("/") if s] def collect(): """⇒ [(method, full_path, file)],含空路径映射;method 已**大写**(HTTP 方法大小写敏感)。""" rows = [] if not os.path.isdir(CTRL_DIR): return rows for dirpath, _dirs, files in os.walk(CTRL_DIR): for name in files: if not name.endswith(".java"): continue full = os.path.join(dirpath, name) with open(full, encoding="utf-8", errors="replace") as fh: text = fh.read() if "extends TdcCrudController" not in text: continue cm = re.search(r'@RequestMapping\("([^"]*)"\)', text) prefix = cm.group(1) if cm else "" for m in MAPPING_RE.finditer(text): method = m.group(1).upper() # 🔴 HTTP 方法大小写敏感 ⇒ 统一大写 path = m.group(3) or "" full_path = (prefix + path).replace("//", "/") rows.append((method, full_path, name)) return rows def classify(rows): """⇒ (crud_base, aggregate, shadowed, true404) 四个集合。""" baseline = crud_baseline() crud_base = [] # CRUD-6 基线 —— 本仓已实现 aggregate = [] # 只读聚合体 —— 本仓 B3 已实现 shadowed = [] # 形态 A:被通用详情路由吞掉 true404 = [] # 形态 B:真 404 for method, path, name in rows: if (method, path) in baseline: crud_base.append((method, path, name)) continue if path in AGGREGATE_DETAIL: aggregate.append((method, path, name)) continue s = segs(path) if len(s) == 5: # 尾段是**字面量**(`Options` / `Types` / `Enabled` …)⇒ 形态 A shadowed.append((method, path, name)) else: true404.append((method, path, name)) return crud_base, aggregate, shadowed, true404 def main(): ap = argparse.ArgumentParser() ap.add_argument("--json", action="store_true") args = ap.parse_args() if not os.path.isdir(CTRL_DIR): print("❌ 上游克隆不在:%s" % CTRL_DIR) print(" (只读克隆;本脚本不下载任何东西)") return 2 rows = collect() crud_base, agg, shadowed, true404 = classify(rows) shadowed_u = sorted(set((m, p) for m, p, _ in shadowed)) true404_u = sorted(set((m, p) for m, p, _ in true404)) if args.json: print(json.dumps({ "upstream_root": UPSTREAM_ROOT, "declared_mappings": len(rows), "crud_baseline": sorted(set((m, p) for m, p, _ in crud_base)), "aggregate_detail": sorted(set((m, p) for m, p, _ in agg)), "shadowed": shadowed_u, "true404": true404_u, "unimplemented_total": len(shadowed_u) + len(true404_u), }, ensure_ascii=False, indent=1)) return 0 get_a = len([1 for m, _ in shadowed_u if m == "GET"]) post_a = len([1 for m, _ in shadowed_u if m == "POST"]) print("上游动作端点普查(只读上游克隆)") print("-" * 72) print(" 上游根:%s" % UPSTREAM_ROOT) print(" 18 个 `extends TdcCrudController` 控制器自声明的 method-level 映射:%d 条" % len(rows)) print(" ├─ CRUD-6 基线(列表/创建/All/{id})—— 本仓已实现:%d 条" % len(set(crud_base))) print(" ├─ 只读聚合体 Detail —— 本仓 B3 已实现:%d 条" % len(set(agg))) print(" ├─ ★形态 A /{Entity}/{action} 单尾段 ⇒ 被通用详情路由吞掉:%d 条" % len(shadowed_u)) print(" │ ├ GET %d 条 ⇒ HTTP 200 + `code:400`「记录不存在或已删除」(**不是 404**)" % get_a) print(" │ └ POST %d 条 ⇒ HTTP 405「方法不被允许」(`{id}` 上没注册 POST)" % post_a) print(" └─ ★形态 B ≥2 尾段 ⇒ 真 404:%d 条" % len(true404_u)) print("-" * 72) print(" 未实现动作端点合计:%d 条(形态 A %d + 形态 B %d)" % (len(shadowed_u) + len(true404_u), len(shadowed_u), len(true404_u))) print() print("★ 形态 A 明细(逐条):") for m, p in shadowed_u: print(" %-6s %s" % (m, p)) return 0 if __name__ == "__main__": sys.exit(main())