Files
dacli/docs/cmd-review/apis.md
T
sswandClaude b9c9e318af feat(v0.11+): Phase 1 - 23 个 dacli 父命令审计完成
派 25 个 Explore 子代理 (5 批 × 5) 审计 23 个父命令.
产出 cmd-review/{cmd}.md (24 文件) + _summary.md.

关键发现:
- webapi 镜像使用率 < 30% (12+ 父命令 100% 绕 webapi)
- 30+ P0 必补新命令 (form update, log exception, di CRUD, role authorize 等)
- 3 处 P0 端点错误 (假 PASS):
  * integration emailTest/smsTest
  * msg templateCreate
- 用户关键修正: bigscreen → jnpf-web-datascreen-vue3 (独立子项目)
- 用户关键修正: report → jnpf-web-datareport (独立子项目)

下一步: Phase 2 按 P0 优先级执行 (修端点 + 新命令 + webapi 化)

Co-Authored-By: Claude <[email protected]>
2026-06-25 14:58:32 +08:00

3.3 KiB
Raw Blame History

dacli apis 命令审计报告 (2026-06-25)

1. 命令清单

子命令 格式 用途
dacli apis list [--tag=<t>] [--method=<m>] [--keyword=<k>] [--json] 列 JNPF 平台所有 API (从 /v3/api-docs 拉取, 12h 缓存)
dacli apis info <pathMethod> [--json] 查单个 API 详情 + 递归解析 $ref (含 ActionResult.data 展开)
dacli apis refresh — 强制刷新 OpenAPI 缓存 (忽略 12h TTL)
dacli apis status [--json] OpenAPI 缓存状态 (loaded/age/pathCount/openapiSize)

2. web 端对应

apis 是元工具,没有对应的 web 页面。它直接调用 JNPF 后端端点:

  • GET /v3/api-docs — SpringDoc OpenAPI 标准端点,返回 1000+ API 完整定义
  • 备选:http://127.0.0.1:30000/v3/api-docs(容器外 fallback)

3. 改/删/留 建议

[KEEP] 所有 4 个子命令

  • list:高频 AI 排查入口,支持 tag/method/keyword 过滤
  • info:杀手特性,递归展开 $ref + ActionResult.data 展开
  • refresh:JNPF 升级/新增 API 后强制重拉
  • status:诊断"为什么看不到新 API"的标准命令

[REFACTOR-WEBAPI] 不适用

apis 不是业务 API 客户端,直接拉 SpringDoc OpenAPI。无 webapi 镜像对象。

[DEPRECATE] 无

所有 4 个子命令都有明确价值。

[NEW-CMD] 建议新增

dacli apis search --field=<f>(P0)

  • 场景:AI 知道字段名(如 f_user_name),想知道哪些 API 返回/接受这个字段
  • 实现:遍历 OpenAPI schema,匹配 properties 中字段名
  • 价值:避免 AI 盲猜(盲点根因 B)

dacli apis tags(P1)

  • 场景:AI 不知道 JNPF 有哪些业务 tag(visualdev/system/workflow等)
  • 实现:解析 OpenAPI tags 字段,列出所有 tag + API 数
  • 价值:作为 apis list --tag=X 的引导

4. AI 痛点评估

痛点 1:缓存失效机制有盲区

  • 12h TTL + PID 哈希(process.pid + 启动时间分钟)
  • 问题:JNPF 容器重启后 API 可能已变,但 PID 哈希可能未变,AI 误以为缓存最新
  • 建议:缓存 key 加入后端版本号(来自 /v3/api-docs 的 info.version)

痛点 2:缺少字段维度搜索

  • AI 知道字段名 f_user_name,但 --keyword 只能搜 path/summary,搜不到 schema 内部
  • 影响:AI 盲猜"哪个 API 接受 f_user_name",浪费 2-3 次试探
  • 解决:apis search --field=<name>

痛点 3:info 输出体积过大

  • --json 输出 ~15KB(包含所有 schema 展开)
  • 影响:浪费 AI context token
  • 建议:加 --summary(仅 method/path/summary)和 --resolved-only(仅展开 schema)

痛点 4:status 缺少变化检测

  • 只输出 pathCount,不显示与上一次拉取的差异
  • 影响:AI 无法判断"JNPF 升级后是否有新 API"
  • 建议:加 --diff flag,对比最近两次拉取

核心结论:apis 命令族设计简洁(4 子命令覆盖 90% 场景),但缺少字段级搜索和tag 引导两个高频 AI 痛点的支持。建议优先级:

  1. P0:apis search --field=(解决字段盲猜)
  2. P1:apis tags(引导命令)
  3. P2:apis info --summary / --resolved-only(减 token)
  4. P3:apis status --diff(变化检测)
  5. P3:缓存 key 加版本号(容器重启场景)