#!/usr/bin/env python3 # -*- coding: utf-8 -*- """fe-api-inventory.py —— 从 JNPF 官方前端 api 层抽取「端点权威清单」。 为什么要有这把尺子 ------------------ 本仓此前靠**读 Java Controller** 推断面 B 端点,那是「服务端提供了什么」; 而前端 `src/api/**/*.ts` 写的是「前端**实际怎么调**」—— URL 大小写、 method、路径参数位置、query/body 归属。两者不是一回事,后者才是契约。 抽取规则(覆盖 JNPF 7.0 前端的两种写法) -------------------------------------- enum Api { Prefix = '/api/permission/Users' } defHttp.get({ url: Api.Prefix, params }) -> GET /api/permission/Users defHttp.put({ url: `${Api.Prefix}/${data.id}`, data }) -> PUT /api/permission/Users/{id} 用法 ---- python3 scripts/fe-api-inventory.py --fe <前端 src 目录> # 打清单 TSV python3 scripts/fe-api-inventory.py --fe <...> --diff <契约.md> # 与本仓契约差分 python3 scripts/fe-api-inventory.py --fe <...> --diff <...> --group # 差分按前缀汇总 退出码:0 正常 / 2 前置错误 """ import os import re import sys RE_HTTP_CALL = re.compile(r"\b(defHttp|reportHttp)\s*\.\s*(get|post|put|delete|patch|request)\s*\(") RE_ENUM = re.compile(r"enum\s+(\w+)\s*\{([^}]*)\}", re.S) RE_ENUM_ITEM = re.compile(r"(\w+)\s*=\s*(['\"`])(.*?)\2", re.S) RE_FUNC = re.compile(r"(?:export\s+)?(?:async\s+)?function\s+(\w+)|(?:export\s+)?const\s+(\w+)\s*=") def read(path): with open(path, "r", encoding="utf-8", errors="replace") as fh: return fh.read() def line_of(text, pos): return text.count("\n", 0, pos) + 1 def parse_enums(text): """返回 {枚举名: {成员名: 字面值}}。""" out = {} for m in RE_ENUM.finditer(text): name, body = m.group(1), m.group(2) items = {} for im in RE_ENUM_ITEM.finditer(body): items[im.group(1)] = im.group(3) if items: out[name] = items return out def match_brace(text, start): """text[start] == '{' ⇒ 返回配对 '}' 的下标;失败返回 -1。""" depth = 0 i = start in_str = None while i < len(text): ch = text[i] if in_str: if ch == "\\": i += 2 continue if ch == in_str: in_str = None elif ch in "'\"`": in_str = ch elif ch == "{": depth += 1 elif ch == "}": depth -= 1 if depth == 0: return i i += 1 return -1 def extract_url_expr(obj): """从 `{ url: XXX, ... }` 的对象体里取出 url 的表达式文本。""" m = re.search(r"\burl\s*:\s*", obj) if not m: return None i = m.end() # 跳过空白 while i < len(obj) and obj[i] in " \t\r\n": i += 1 if i >= len(obj): return None ch = obj[i] if ch in "'\"`": quote = ch j = i + 1 while j < len(obj): if obj[j] == "\\": j += 2 continue if obj[j] == quote: return obj[i : j + 1] j += 1 return obj[i:] # 非字面量:吃到深度 0 的逗号或对象结束 depth = 0 j = i while j < len(obj): c = obj[j] if c in "([{": depth += 1 elif c in ")]}": if depth == 0: break depth -= 1 elif c == "," and depth == 0: break j += 1 return obj[i:j].strip() def resolve_path(expr, enums): """把 url 表达式解析成真实路径模板。""" if not expr: return None expr = expr.strip() # 1) 纯字面量 if len(expr) >= 2 and expr[0] == expr[-1] and expr[0] in "'\"`": body = expr[1:-1] else: body = expr # 2) 内联 `enum Api { ... }` 之内的成员:先整体换掉 ${Api.X} / Api.X for _ename, items in enums.items(): for key, val in items.items(): body = body.replace("${%s.%s}" % (_ename, key), val) body = body.replace("${Api.%s}" % key, val) body = re.sub(r"\b%s\.%s\b" % (re.escape(_ename), re.escape(key)), val, body) body = re.sub(r"\bApi\.%s\b" % re.escape(key), val, body) # 3) 剩下的 ${...} 是运行时变量 ⇒ 归一成 {param} body = re.sub(r"\$\{[^}]*\}", "{param}", body) # 4) 去掉查询串残留与重复斜杠 body = body.split("?")[0] body = re.sub(r"/{2,}", "/", body) if not body.startswith("/"): return None if len(body) > 1 and body.endswith("/"): body = body[:-1] return body def scan_fe(fe_root): """扫 /api/**/*.ts(无 api 子目录则扫全树)。""" base = os.path.join(fe_root, "api") if not os.path.isdir(base): base = fe_root rows = [] for dirpath, _dirnames, filenames in os.walk(base): for fn in sorted(filenames): if not fn.endswith(".ts") or fn.endswith(".d.ts"): continue ap = os.path.join(dirpath, fn) text = read(ap) if "defHttp" not in text and "reportHttp" not in text: continue enums = parse_enums(text) for m in RE_HTTP_CALL.finditer(text): verb, meth = m.group(2), m.group(2) if verb == "request": continue # request({url, method}) 少见,先不猜 method # 找调用参数里的对象体 tail = text[m.end() :] brace = tail.find("{") if brace < 0: continue end = match_brace(tail, brace) if end < 0: continue obj = tail[brace + 1 : end] expr = extract_url_expr(obj) path = resolve_path(expr, enums) if not path: continue # 归属函数名:向上找最近的 function/const head = text[: m.start()] fname = "" for fm in RE_FUNC.finditer(head): fname = fm.group(1) or fm.group(2) or fname rel = os.path.relpath(ap, fe_root) rows.append( { "method": meth.upper(), "path": path, "func": fname, "where": "%s:%d" % (rel, line_of(text, m.start())), } ) # 去重(同 method+path 只留第一条) seen = set() uniq = [] for r in rows: k = (r["method"], r["path"]) if k in seen: continue seen.add(k) uniq.append(r) uniq.sort(key=lambda r: (r["path"], r["method"])) return uniq def norm(p): """路径归一:{xxx} 一律换成 {},便于跨端比对。""" return re.sub(r"\{[^}]*\}", "{}", p) def read_contract_endpoints(contract_path): """读 docs/contract.md 的 [ENDPOINT] 段。""" out = [] in_sec = False for raw in read(contract_path).splitlines(): line = raw.strip() if line.startswith("[ENDPOINT]"): in_sec = True continue if in_sec and line.startswith("[") and line.endswith("]"): break if not in_sec or not line or line.startswith("#"): continue parts = line.split("\t") if len(parts) < 3: continue out.append({"face": parts[0], "method": parts[1], "path": parts[2]}) return out def main(argv): fe = None diff = None group = False i = 1 while i < len(argv): a = argv[i] if a == "--fe" and i + 1 < len(argv): fe = argv[i + 1] i += 2 continue if a == "--diff" and i + 1 < len(argv): diff = argv[i + 1] i += 2 continue if a == "--group": group = True i += 1 continue if a in ("-h", "--help"): print(__doc__) return 0 sys.stderr.write("fe-api-inventory: 未知参数 %r\n" % a) return 2 if not fe or not os.path.isdir(fe): sys.stderr.write("fe-api-inventory: --fe 必须是存在的前端 src 目录\n") return 2 rows = scan_fe(fe) if not diff: print("METHOD\tPATH\tFUNC\tWHERE") for r in rows: print("%s\t%s\t%s\t%s" % (r["method"], r["path"], r["func"], r["where"])) sys.stderr.write("共 %d 条端点\n" % len(rows)) return 0 if not os.path.isfile(diff): sys.stderr.write("fe-api-inventory: --diff 指向的契约文件不存在:%s\n" % diff) return 2 be = read_contract_endpoints(diff) # 前端发 Vue-Version: 3 ⇒ 只会走面 B;面 B 端点 = face in (B, AB) be_b = [e for e in be if e["face"] in ("B", "AB")] be_keys = {(e["method"].upper(), norm(e["path"])) for e in be_b} fe_keys = {(r["method"], norm(r["path"])) for r in rows} missing = [r for r in rows if (r["method"], norm(r["path"])) not in be_keys] extra = [(m, p) for (m, p) in sorted(be_keys) if (m, p) not in fe_keys] print("== 前端端点总数 %d / 本仓面 B 已实现 %d / 覆盖 %d ==" % ( len(rows), len(be_b), len(rows) - len(missing))) print() if group: buckets = {} for r in missing: seg = [s for s in r["path"].split("/") if s and s != "api"] key = "/".join(seg[:2]) if seg else "(root)" buckets.setdefault(key, []).append(r) print("== 未实现端点按前缀汇总(%d 组)==" % len(buckets)) for key in sorted(buckets, key=lambda k: (-len(buckets[k]), k)): print("%5d %s" % (len(buckets[key]), key)) print() print("== 本仓已实现但前端不调用(面 B)==") for m, p in extra: print("%-6s %s" % (m, p)) print() print("== 前端调用但本仓未实现(按路径排序)==") for r in missing: print("%-6s %-60s %s" % (r["method"], r["path"], r["where"])) return 0 if __name__ == "__main__": sys.exit(main(sys.argv))