多语言/表单套件/缓存管理/任务调度/IM 会话/收藏菜单/公式目录/系统监控 + 三处 Actions/Export;新表 8 张(官方 DDL 逐字)⇒ tables 65,BASE_TABLES 62。 影响: - 多语言是「一行一语种 + f_group_id 聚组」,列表 id = groupId;tableHead 的列来自 字典 Language(seed 按官方初始库种子化);PUT 时 map 里没有的语种要删掉。 - CacheManage 落到本仓真实的内存会话表:DELETE 真的把人踢下线、ClearAll 保留操作者 自己、overdueTime 恒 null(会话不过期,不编时间)、绝不把 token 放进响应。 - scheduletask 只登记不执行(本仓无 XXL-JOB):runCount 恒 0、lastRunTime/nextRunTime 恒 null、TaskMethods 返空 list(返错会让新建表单整条红)。 - 三处 Export 与 BaseLang 模板/导入 = 明确业务失败(无文件服务),不返假 url; Kit 那条尤其不能用 data:null(官方前端 res.data.url 会抛 JS 异常)。 - Monitor 真读宿主机指标;macOS 的 CPU 占空比用负载均值近似(契约标 partial)。 顺手修掉 fe-api-inventory.py 的嵌套模板串截断(真因):内层反引号会截断 URL、内层 } 会截断变量替换 ⇒ 产出畸形路径,让 system 永远差 2 条。改成深度配对 + 丢掉「拼查询串 的三元片段」后,system 缺口 41 → 0(196/196)。另把 3 条「官方前端声明但官方后端 从无映射、也无人调用」的死接口记进 [OFFICIAL] 的 oos(带判据,不进分母)。 回归测试 tests/batch15_it.rs 12 条;全量 610 passed / 0 failed;verify.sh 全绿。
382 lines
13 KiB
Python
382 lines
13 KiB
Python
#!/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
|
||
# 🔴 模板串里的 `${...}` 可以再套一层模板
|
||
# (官方 `` `${Prefix}/getConfig/${id}${encryption ? `?e=${encryption}` : ''}` ``)
|
||
# ⇒ 那里面出现的反引号**不是**结束符,必须整段跳过;
|
||
# 否则 URL 会在内层反引号处被截断成 `…/${encryption`,变成永远修不完的假缺口。
|
||
if quote == "`" and obj.startswith("${", j):
|
||
end = find_template_end(obj, j)
|
||
if end < 0:
|
||
return obj[i:]
|
||
j = end
|
||
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()
|
||
|
||
|
||
RE_TMPL_LITERAL = re.compile(r"'[^']*'|\"[^\"]*\"|`[^`]*`")
|
||
|
||
|
||
def find_template_end(s, i):
|
||
"""`s[i:]` 以 `${` 开头 ⇒ 返**配对**的 `}` 之后的下标;未闭合返 -1。
|
||
|
||
🔴 必须按**嵌套深度**配对,不能用 `\\$\\{[^}]*\\}`:官方前端真的有
|
||
`` `${Api.Prefix}/Selector/${`${id || '0'}`}` `` 这种套两层模板的写法,
|
||
`[^}]*` 会停在内层的 `}` 上 ⇒ 截出 `/api/system/Menu/Selector/${` 这种畸形路径,
|
||
然后在缺口报表里变成一个**永远修不完的假缺口**。
|
||
"""
|
||
depth = 0
|
||
j = i
|
||
while j < len(s):
|
||
if s.startswith("${", j):
|
||
depth += 1
|
||
j += 2
|
||
continue
|
||
if s[j] == "}":
|
||
depth -= 1
|
||
if depth == 0:
|
||
return j + 1
|
||
j += 1
|
||
return -1
|
||
|
||
|
||
def subst_template_vars(body):
|
||
"""把剩下的 `${...}` 归一成 `{param}`(深度感知,见 `find_template_end`)。
|
||
|
||
🔴 **拼查询串的片段要整段丢掉**,不能变成 `{param}`:官方
|
||
`` `${Api.Prefix}/${type}${interfaceId ? `?dataInterFaceId=${interfaceId}` : ''}` ``
|
||
的后半段是往 URL 尾巴上追加 `?dataInterFaceId=…`,它**不是**一个路径段。
|
||
判据:这一段里的字符串字面量有以 `?` 开头的 ⇒ 查询串追加 ⇒ 丢掉。
|
||
"""
|
||
out = []
|
||
i = 0
|
||
while i < len(body):
|
||
if body.startswith("${", i):
|
||
end = find_template_end(body, i)
|
||
if end < 0:
|
||
# 未闭合:原样留着 ⇒ 下游照旧报缺口(宁可多报,不要静默吞掉)
|
||
out.append(body[i:])
|
||
break
|
||
expr = body[i + 2 : end - 1]
|
||
query_append = any(
|
||
lit[1:].startswith("?") for lit in RE_TMPL_LITERAL.findall(expr)
|
||
)
|
||
out.append("" if query_append else "{param}")
|
||
i = end
|
||
continue
|
||
out.append(body[i])
|
||
i += 1
|
||
return "".join(out)
|
||
|
||
|
||
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 = subst_template_vars(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):
|
||
"""扫 <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))
|