中国 帮助

应用清单 app.json

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

应用清单 app.json
封面

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

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

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

这一页解决三件事:

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

parseAndValidate(manifestJson, expectedAppCode);菜单部分复用安装时的 AppMenuPlanner.plan(...), 所以"保存时通过、安装时失败"不可能发生。 这几个类都是 2026-10-30 抽出来的上架判据内核(wujies-modules/wujies-market-core), 平台安装侧与中心上架服务共用同一份。

  • Java 映射:wujies-platform/wujies-modules/wujies-market-core/src/main/java/cn/wujies/appmarket/domain/AppManifest.java
  • 校验入口:wujies-market-core/.../appmarket/service/AppManifestValidator.java 的

最小可用清单

范例应用是 wujies-hello,它的清单有 13 个顶层字段(没有 migrations / config):

{
  "code": "hello",
  "name": "Hello 示例",
  "version": "1.0.2",
  "type": "plugin",
  "engine": ">=5.6.2 <6.0.0",
  "author": { "name": "无界创镜" },
  "license": "MIT",
  "summary": "插件开发范例:一个表 + 五组演示(调用宿主系统服务、跨插件调用、从插件开放 /open 接口、两种定时任务、标准 CRUD 列表页),前端页面随包一起发。",
  "dependencies": [
    { "code": "member" }
  ],
  "categories": ["开发工具"],
  "tags": ["示例", "插件开发", "PoC"],
  "assets": {
    "backend": "backend/wujies-hello-plugin-1.0.2.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 }
          ]
        }
      ]
    }
  ]
}

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

顶层字段

字段Java 类型必填含义与约束
codestring是应用编码。正则 ^[a-z][a-z0-9-]{1,62}$(2–63 位,中心上架服务 AppAdminController.APP_CODE_PATTERN 在建应用时钉住它;平台侧 AppManifestValidator 只查非空 + 与所属应用一致)。同时是表名前缀、权限前缀、远程视图前缀
namestring是应用名称。DB 列 app_info.app_name 为 varchar(64)
versionstring是语义化版本,正则 ^\d+\.\d+\.\d+(-[0-9A-Za-z.]+)?$
typestring否module 内置模块 / app 应用 / plugin 插件,默认 module。第三方包写 app 或 plugin,怎么选见下方「type:三种形态怎么选」
enginestring否平台版本约束,见下
authorobject否只有 name、url 两个子字段
licensestring否如 MIT / Apache-2.0。DB 列 varchar(32)
licenseRequiredboolean否这个包要不要本机授权凭证解锁才能装与加载,默认 false(社区件)。判据写在包内清单里、且在包签名覆盖范围之内 —— 把它从 true 改成 false 会当场验签失败。付费件写 true,此时中心上架要求目录条目为 private(LicenseVisibilityRule)。三档口径见[授权与版本](/docs/wujies/5.x/license/)
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 与已上架的历史包两处都要看(早期那份 app.schema.json 草案已不存在)。

### type:三种形态怎么选

判据参考 NiuCloud —— 它把扩展分成应用和插件两类,界线是业务体量,不是代码放在哪:

形态什么时候用谁执行安装
module平台自带、代码随宿主一起发布的内置模块,不加载任何外部产物ModuleAppInstaller:注册菜单 + 授权 + 迁移
app一套完整业务体系:有自己的前后台与数据闭环,能围绕它组织业务。现有 5 个属于这类:商城、会员、即时通讯、考试、企业数据PluginAppInstaller
plugin功能单一、依附在应用之上的增量能力,与其它单元几乎无耦合。现有 7 个属于这类:支付、财务、报价、图床、社

本文导览

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

章节导览
THE END

喜欢就支持以下吧

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

回到内容