应用清单 app.json

app.json 是应用在平台上的唯一权威描述：编码、版本、产物路径、菜单树、依赖。 上架、安装、升级、卸载全部读它。写错了不会在编译期报错，只会在安装时失败或 在运行期静默失效（菜单点不开、按钮不出现、C 端 404）。

这一页解决三件事：

1. 每个字段真实的类型、必填性与取值约束（对着 AppManifest.java 与校验器写，不凭印象）；
2. menus[] 怎么设计，尤其是 type: "F" 按钮 —— 漏了会留下永久性的坏数据；
3. key 的命名转换，以及"为什么不能只用 perms 推 key"。

最小可用清单复制标题链接

范例应用是 wujies-hello，它的清单有 12 个顶层字段（没有 dependencies / migrations）：

{
  "code": "hello",
  "name": "Hello 示例",
  "version": "1.0.0",
  "type": "plugin",
  "engine": ">=5.6.2 <6.0.0",
  "author": { "name": "无界创镜" },
  "license": "MIT",
  "summary": "插件开发范例：一个表 + 五组演示，前端页面随包一起发。",
  "categories": ["开发工具"],
  "tags": ["示例", "插件开发", "PoC"],
  "assets": {
    "backend": "backend/wujies-hello-plugin-1.0.0.jar",
    "frontend": "frontend/index.js"
  },
  "menus": [
    {
      "key": "hello",
      "name": "Hello 示例",
      "type": "M",
      "path": "hello",
      "icon": "ri:emotion-happy-line",
      "order": 99,
      "children": [
        {
          "key": "hello-probe",
          "name": "运行时探针",
          "type": "C",
          "path": "probe",
          "component": "remote:hello/demo/home",
          "perms": "hello:probe:view",
          "icon": "ri:pulse-line",
          "order": 0,
          "children": [
            { "key": "hello-probe-view", "name": "查看探针", "type": "F", "path": "",
              "perms": "hello:probe:view", "icon": "#", "order": 1 }
          ]
        }
      ]
    }
  ]
}

源文件是 wujies/wujies-plugins/wujies-hello/app.json（下称"仓库路径"， 按 设计文档索引 的约定，仓库路径不是站内链接，故用行内代码写）。 新插件直接照它复制，不要从别的业务插件里抄（那些带一堆历史包袱）。

顶层字段复制标题链接

engine 的两道闸复制标题链接

engine 有两层校验，顺序很重要 —— 先查长度与字符，再查表达式语法：

private static final Pattern ENGINE_PATTERN = Pattern.compile("^[0-9.\\s<>=]+$");
private static final int ENGINE_MAX_LENGTH = 64;   // 与 app_version.engine_range varchar(64) 对齐

长度上限的目的是把数据库层的失败提前到业务层：否则用户看到的是 Data too long for column 'engine_range' 这种 500。当前平台版本常量是 AppMarketConstants.PLATFORM_VERSION = "5.6.2"，现有清单统一写 >=5.6.2 <6.0.0。

两个"占位"字段复制标题链接

上架端把整份 JSON 原样存进 app_version.manifest_json，所以任何合法 JSON 字段都能存下来 —— 下表这两个字段就是这种状态：结构在，逻辑没写。

migrations[] 不执行是刻意的：目录驱动让"清单声明了脚本却忘了打包"这类错误 根本不会发生，手工补一个修数据脚本也只需把 .sql 扔进目录。

字典、站点配置、示例数据也不走 config，而是随包走的迁移脚本： 02-create-<app>-seed-data.sql / 0N-create-<app>-dictionaries.sql / 0N-create-<app>-website-config.sql（范例见仓库路径 wujies/wujies-plugins/wujies-hello/migrations/，共三份脚本）。

assets复制标题链接

AppManifest.Assets 只有三个字段。

真实包结构（wujies-plugins/dist-packages/mall-1.0.3.zip，9 个条目 —— 那是产物默认落点还在仓库内时打的历史包；现在的新包落在仓库外的 <插件仓库的上一级>\.plugin-dist\<code>\<版本>\，见打包应用）：

app.json
signature.txt
backend/wujies-mall-plugin-1.0.3.jar
frontend/index.js
frontend/assets/mall-app.css
migrations/01-create-mall-tables.sql
migrations/02-create-mall-dictionaries.sql
migrations/03-create-mall-website-config.sql
migrations/04-create-mall-seed-data.sql

两种合法形态复制标题链接

assets.backend 与 assets.frontend 都不写在 Schema 的 required 里，可以只写一边：

menus[]复制标题链接

字段与 sys_menu 一一对应。

只有这五条是校验器强制的（AppMenuPlanner.collect）： key 合法、name 非空、type 属于 M/C/F、type=C 必有 component、type=F 必有 perms。 其余字段（path / icon / order / perms 用在 M/C 上）校验器不管。

AppMenuPlanner 的三条设计规则复制标题链接

1. 按 key 幂等 —— 重复上架同一版本不会产生重复菜单；
2. 跨版本复用 menu_id —— 新版本里同名 key 沿用旧 menu_id， 否则租户已有的菜单授权会在升级后全部失效；
3. 深度优先、父先于子 —— 保证落库时父菜单 ID 一定已确定。

旧版本存在、新版本已移除的菜单会被算进 obsolete， 调用方应当将其停用而不是删除。

F 按钮必须写进清单复制标题链接

type: "F" 的按钮不是可选项。漏了会同时踩两个坑：

1. 全新部署装完没有按钮 —— 前端 v-hasPermi 过不了，租户用户看不到任何操作按钮；
2. "彻底删除"时也删不掉它们 —— 归属映射表里没有它们。

这条是补出来的：图床的 23 个按钮不在原清单里（历史上来自平台初始化 SQL）， 后来才补进 wujies-gallery/app.json。对已有部署还要配一条 seed SQL 把新 key 映射到既有的按钮 ID（script/sql/update/fix_gallery_menu_tree.sql）， 否则升级会建出一套重复按钮 —— 这与 app_market_gallery_migrate.sql 当初为 7 个菜单做的是同一件事。

key 的命名转换（本页重点）复制标题链接

唯一的硬约束复制标题链接

// AppMenuPlanner
private static final Pattern KEY_PATTERN = Pattern.compile("^[a-z][a-z0-9-]{1,62}$");

key 必须是小写字母开头的 2–63 位小写字母 / 数字 / 连字符， 且同一份清单内不许重复。除此之外，key 怎么取名完全自由 —— 这一点很重要，因为下面会看到真实清单里并存着好几种形状。

驼峰转换复制标题链接

perms 里普遍有驼峰，直接拿 perms 当 key 会在上传时被拒：

第 N 个菜单 key 非法（需为小写字母开头的 2-63 位小写字母/数字/连字符）: member-member-adjustPoints

转换规则只有一条：驼峰前插 -，再整体小写。

为什么不能只从 perms 推 key复制标题链接

同一个 perms 可能在多行菜单上重复出现。IM 那轮实测：工作台自带一套按钮、 各管理页又各带一套，19 个 perms 重复 2~3 次。只按 perms 推 key 必然撞车， 而撞车会被校验器直接拒掉（菜单 key 重复: x）。

所以 F 行的 key 必须由父键限定。当前约定是：

F 行 key = <父级 key> + "-" + kebab(perms 的最后一段)

对 407 个真实 F 按钮做统计，三种形状并存：

SELECT perms, COUNT(*) FROM sys_menu
-- 把 :appCode 换成真实应用编码（如 social），也可以直接写 CONCAT('social', ':%')
WHERE perms LIKE CONCAT(:appCode, ':%') GROUP BY perms HAVING COUNT(*) > 1;

生成而不是手写复制标题链接

菜单多的模块（会员 68 行、商城 163+ 行）必须用脚本生成，理由不是省事：

app.json 与 seed SQL 的 key 必须由同一份数据生成。手写两份必然漂移， 而漂移的后果是升级时建出一套重复菜单。

生成步骤与两个已验证的坑：

1. 从库里读那批菜单行（menu_id / parent_id / type / name / path / component / perms / icon）， 一次生成 app.json + menu_id = key 映射，再由映射生成 seed SQL；

2. 菜单要"从根整棵取"，不要按 perms LIKE '<appCode>:%' + path 过滤。 社交那轮实测：根与页面之间还有两个中间目录（follow/management、action/management）， 它们既没有以应用编码开头的 perms、path 里也不含 social， 过滤会把它们连同下面 11 个页面一起丢掉 —— 结果清单里只剩一个光杆根目录。 用递归 CTE 从根往下取整棵：

   复制代码

   WITH RECURSIVE tree AS (
     SELECT menu_id FROM sys_menu WHERE menu_type = 'M' AND path = 'social'
     UNION ALL
     SELECT m.menu_id FROM sys_menu m JOIN tree t ON m.parent_id = t.menu_id
   )
   SELECT ... FROM sys_menu
   WHERE menu_id IN (SELECT menu_id FROM tree)
   ORDER BY parent_id, order_num, menu_id

   （'social' 处换成真实应用编码；社交的根 menu_type='M'、path='social'。）

3. 中间目录的 key 用整条路径转 kebab（social-follow-management）； 只取末段会撞车（两个都叫 management）。

dependencies[]复制标题链接

什么时候会用到它复制标题链接

依赖检查发生在安装与升级，位置在最前面（落位、迁移、加载之前）：

那句报错长这样（mall 没装 member / pay / im 时）：

应用「商城管理」依赖「会员管理」「支付管理」「即时通讯」，请先安装并启用它们，才能安装。

已装但被停用的依赖会另起一句说明处置办法（停用会卸载它的插件后端，依赖它的应用照样加载不了）：

其中「会员管理」已安装但处于已停用状态：停用会卸载插件后端，依赖它的应用照样加载不了，
请先到「我的应用」里启用。

为什么必须声明，而不是"装的时候自然会知道"复制标题链接

mall 的代码直接注入兄弟应用的 Service（IMemberService 等）。插件运行时是这样的：

• 每个插件一个子 Spring 上下文，父上下文是宿主 —— 所以插件能注入宿主，宿主看不见插件；
• 兄弟插件之间能互相注入（Spring 按类型解析会一路问到祖先上下文），前提是对端已经加载， 且它的类能被 PluginClassLoader 委托到（按包名 cn.wujies.<code>.* 找拥有者加载器）。

于是"依赖没装"的表现不是一句"缺少依赖"，而是：

Error creating bean with name 'mallMerchantController':
No qualifying bean of type 'cn.wujies.mall.merchant.service.IMallMerchantService'

引用缺失依赖的那些类会被守卫跳过并只 WARN，它们的 @Service 没有 bean， 控制器自然建不出来 —— 用户看到的是最后一环，根因要往回翻很多层。这就是"依赖必须能声明"的原因。 完整的机制与顺序约束见仓库根 wujies-platform/AGENTS.md 的 §2.5。

⚠️ 版本约束（version）当前不参与判定复制标题链接

判定只看在不在与启没启用，version 字段原样透出给前端展示。 原因：平台现有的版本比较器（EngineConstraint）语义是"平台版本 vs 语义化版本"， 拿它比"已装应用的版本"会把 1.0.10 判成小于 1.0.9，那比不判更糟（会误拦）。

{
  "dependencies": [
    { "code": "member" },
    { "code": "pay", "version": ">=1.0.0" },
    { "code": "chat", "optional": true }
  ]
}

卸载时的反向提示复制标题链接

卸载 A 时，如果本租户还有已装应用依赖 A，任务日志里会多一条 WARN：

注意：「商城管理」(mall) 依赖本应用。卸载后它们的相关功能会跟着不可用
（接口会回「应用不可用」）；如需继续使用，请先安装回本应用，或先一并卸载它们。

只提示、不拦截 —— 卸载是用户明确要做的事，而且默认卸载保留数据（可逆）。

校验报错速查复制标题链接

这些都是会真实看到的中文报错，看到就知道改哪里。

AppManifestValidator 会把菜单类报错再包一层： 应用清单菜单声明非法: <上面那条>。

[System.IO.File]::WriteAllText($p, $json, (New-Object System.Text.UTF8Encoding($false)))

相关阅读复制标题链接

• 菜单与权限 —— 菜单落库、归属映射与保护
• 后端工程 —— 自包含工程结构与 provided 依赖
• 前端远程应用 —— remote:{appCode}/{viewKey} 怎么解析
• 数据库迁移 —— migrations/ 目录驱动与幂等要求
• 应用范例 hello —— 五组演示的源码对照