Skip to content

源码插件开发与上架规范 ​

本文描述插件市场源码包的开发与上架要求,与后台「上传源码版本」使用的校验逻辑一致 (SourcePluginPackageReader / PluginDescriptorValidator)。

不要与仓库内置的 forge-plugin-* 模块扩展文档混淆:
Starter / Plugin 选择 讲的是框架内如何拆模块;
上架市场必须按本文的 forge-plugin.json 源码包协议交付。

购买方安装步骤见 源码插件购买与安装。通用编码约定见 编码规范。

上架流程(当前) ​

  1. 按本文协议完成插件开发与 ZIP 打包。
  2. 微信联系作者,说明插件 ID、名称、兼容核心版本、功能简介与交付包。
  3. 运营在后台创建商品 → 上传源码 ZIP → 校验通过登记草稿 → 人工确认后发布**。
  4. 发布后进入公开市场;售出后按约定收益分成。

上传校验通过不等于已发布;发布是独立确认步骤。

ZIP 包结构 ​

ZIP 根目录直接包含描述文件,不要再套一层文件夹:

text
forge-plugin.json
server/<module>/                 # 有后端时必填
  pom.xml
  src/main/resources/META-INF/forge-plugin.json   # 须与根描述字节级一致
  ...
ui/...                           # 有前端时,路径须与描述 ui.dir 一致

约束(与后台上传一致):

项要求
格式.zip,非空
体积整包 ≤ 8 MiB(后台上限)
组件至少包含后端 server 或前端 ui 之一
描述根 forge-plugin.json 必填
一致性有后端时,根描述与 META-INF/forge-plugin.json 必须完全一致
POM后端 pom.xml 须通过单模块校验,模块名与 server.module 一致
安全拒绝越界路径、软链接等不安全条目

可参考社区样例包结构(Forge 主仓 plugins-samples/forge-plugin-hello)。

forge-plugin.json 字段 ​

根描述与运行时描述使用同一 JSON。示例:

json
{
  "id": "hello",
  "name": "示例插件",
  "version": "1.0.0",
  "edition": "community",
  "requiresCore": ">=1.2.0 <2.0.0",
  "features": ["community.hello"],
  "server": { "module": "forge-plugin-hello" },
  "ui": { "dir": "ui" }
}
字段规则
id2–32 位,小写字母开头,仅 [a-z0-9-]
name非空,长度 ≤ 128
version语义化版本(SemVer)
editioncommunity 或 enterprise
requiresCore版本范围;上传时填写的「校验核心版本」必须落在该范围内
features数组;编码合法且不重复;community 功能不得以 ee. 开头,enterprise 必须以 ee. 开头
server.module安全的模块目录名(小写字母数字短横线)
ui.dir相对目录,禁止 . / .. 与路径穿越

升级时须同时修改根描述与 META-INF 描述;已执行的数据库迁移脚本禁止改字节,只能追加新版本。

与后台上传的对应关系 ​

后台「上传源码版本」会:

  1. 读取 ZIP 中的根 forge-plugin.json
  2. 按上表校验字段与核心兼容范围
  3. 校验前后端目录、描述一致性、POM
  4. 计算包 SHA-256;同插件同版本不可覆盖
  5. 登记为草稿,等待运营发布

开发者自测时,请确保包能通过上述校验后再联系上架。本地安装可用客户工程 CLI(若工程已集成):

bash
pnpm forge:plugin check "/absolute/path/to/plugin.zip"

预检不能代替安全审查与人工审核。

开发时还需遵守 ​

  • 编码规范:命名、异常、日志、SQL 落 Mapper XML 等
  • 菜单 / API 权限需可授权;不得依赖默认放开
  • 功能编码走 FeatureGate,不能代替登录与 RBAC
  • 插件迁移独立历史;不要改已执行脚本,不要指望卸载自动删库

相关文档 ​