> 本文整理自平台文档 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 类型 | 必填 | 含义与约束 |
|---|---|---|---|
code | string | 是 | 应用编码。正则 ^[a-z][a-z0-9-]{1,62}$(2–63 位)。同时是表名前缀、权限前缀、远程视图前缀 |
name | string | 是 | 应用名称。DB 列 app_info.app_name 为 varchar(64) |
version | string | 是 | 语义化版本,正则 ^\d+\.\d+\.\d+(-[0-9A-Za-z.]+)?$ |
type | string | 否 | module / plugin / deploy,默认 module。抽出来的业务模块写 plugin |
engine | string | 否 | 平台版本约束,见下 |
author | object | 否 | 只有 name、url 两个子字段 |
license | string | 否 | 如 MIT / Apache-2.0。DB 列 varchar(32) |
summary | string | 否 | 一句话简介,市场卡片用。DB 列 varchar(200) |
categories | string[] | 否 | 分类名,必须与 app_category 里已存在的分类对得上 |
tags | string[] | 否 | 搜索标签。DB 里存成逗号分隔的 varchar(200) |
menus | MenuDef[] | 否 | 菜单树,安装时幂等写入 sys_menu |
dependencies | Dependency[] | 否 | 依赖的其它应用。没装/没启用时安装与升级会被拦住并明确告诉你缺谁,见 [dependencies[]](#dependencies) |
migrations | Migration[] | 否 | 预留字段,当前不参与执行(见下) |
config | object | 否 | 预留字段,当前没有任何代码读它(见下) |
assets | object | 否 | 前后端产物路径 |
宿主 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)


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