中国 帮助

应用清单 app.json

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

应用清单 app.json
封面

> 本文整理自平台文档 docs/wujies/1.x/plugin-dev/basics/manifest.mdx,用于站点内容演示。

(https://console.wujies.cn/remote-apps/cms-assets/doc-ef77f107f7b6-cover.svg)

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

这一页解决三件事:

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

菜单部分复用安装时的 AppMenuPlanner.plan(...),所以"保存时通过、安装时失败"不可能发生。

  • Java 映射:wujies-platform/wujies-modules/wujies-app-market/src/main/java/cn/wujies/appmarket/domain/AppManifest.java
  • 校验入口:AppManifestValidator.parseAndValidate(manifestJson, expectedAppCode);

最小可用清单

范例应用是 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(下称"仓库路径", 按 [设计文档索引](/docs/wujies/1.x/design/design-docs) 的约定,仓库路径不是站内链接,故用行内代码写)。 新插件直接照它复制,不要从别的业务插件里抄(那些带一堆历史包袱)。

顶层字段

字段Java 类型必填含义与约束
codestring是应用编码。正则 ^[a-z][a-z0-9-]{1,62}$(2–63 位)。同时是表名前缀、权限前缀、远程视图前缀
namestring是应用名称。DB 列 app_info.app_name 为 varchar(64)
versionstring是语义化版本,正则 ^\d+\.\d+\.\d+(-[0-9A-Za-z.]+)?$
typestring否module / plugin / deploy,默认 module。抽出来的业务模块写 plugin
enginestring否平台版本约束,见下
authorobject否只有 name、url 两个子字段
licensestring否如 MIT / Apache-2.0。DB 列 varchar(32)
summarystring否一句话简介,市场卡片用。DB 列 varchar(200)
categoriesstring[]否分类名,必须与 app_category 里已存在的分类对得上
tagsstring[]否搜索标签。DB 里存成逗号分隔的 varchar(200)
menusMenuDef[]否菜单树,安装时幂等写入 sys_menu
dependenciesDependency[]否依赖的其它应用。没装/没启用时安装与升级会被拦住并明确告诉你缺谁,见 [dependencies[]](#dependencies)
migrationsMigration[]否预留字段,当前不参与执行(见下)
configobject否预留字段,当前没有任何代码读它(见下)
assetsobject否前后端产物路径

宿主 Jackson 配了 fail_on_unknown_properties: false (wujies-admin/src/main/resources/application.yml)。所以拼错的键名不会让解析失败, 只会表现为"这个功能没生效",且日志里什么都没有。

排查手段只有一条:对着 AppManifest.java 的字段名逐字比。改动字段名时, AppManifest.java、docs/app-market/app.schema.json(在工作区根松散 docs/ 下, 不在任何 git 仓库里)与已上架的历史包三处都要看。

### 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) 对齐
报错触发条件
应用清单 engine 过长(N 字符,上限 64):x超过 64 字符
应用清单 engine 含非法字符(只允许数字、点、空格与 <>= ):x写了 ^ ~ `\` 等
应用清单 engine 表达式非法: ...语法错,如 >=1.0.0 <

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

上架端允许先存草稿,所以 parseAndValidate 不会因为"引擎版本不满足"而拒绝保存; 真正拒绝发生在安装时。这也意味着上架成功不等于客户端装得上。

### 两个"占位"字段

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

字段真实状态依据
migrations[]不执行。只有 version / up / down 三个子字段,down 是为回滚预留的真正执行的是目录驱动:打包时把 `migra

本文导览

(https://console.wujies.cn/remote-apps/cms-assets/doc-ef77f107f7b6-guide.svg)

章节导览
THE END

喜欢就支持以下吧

评论区需要浏览器启用 JavaScript 才能加载。

回到内容