源码插件开发与上架规范
本文描述插件市场源码包的开发与上架要求,与后台「上传源码版本」使用的校验逻辑一致 (SourcePluginPackageReader / PluginDescriptorValidator)。
不要与仓库内置的
forge-plugin-*模块扩展文档混淆:
Starter / Plugin 选择 讲的是框架内如何拆模块;
上架市场必须按本文的forge-plugin.json源码包协议交付。
购买方安装步骤见 源码插件购买与安装。通用编码约定见 编码规范。
上架流程(当前)
- 按本文协议完成插件开发与 ZIP 打包。
- 微信联系作者,说明插件 ID、名称、兼容核心版本、功能简介与交付包。
- 运营在后台创建商品 → 上传源码 ZIP → 校验通过登记草稿 → 人工确认后发布**。
- 发布后进入公开市场;售出后按约定收益分成。
上传校验通过不等于已发布;发布是独立确认步骤。
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" }
}| 字段 | 规则 |
|---|---|
id | 2–32 位,小写字母开头,仅 [a-z0-9-] |
name | 非空,长度 ≤ 128 |
version | 语义化版本(SemVer) |
edition | community 或 enterprise |
requiresCore | 版本范围;上传时填写的「校验核心版本」必须落在该范围内 |
features | 数组;编码合法且不重复;community 功能不得以 ee. 开头,enterprise 必须以 ee. 开头 |
server.module | 安全的模块目录名(小写字母数字短横线) |
ui.dir | 相对目录,禁止 . / .. 与路径穿越 |
升级时须同时修改根描述与 META-INF 描述;已执行的数据库迁移脚本禁止改字节,只能追加新版本。
与后台上传的对应关系
后台「上传源码版本」会:
- 读取 ZIP 中的根
forge-plugin.json - 按上表校验字段与核心兼容范围
- 校验前后端目录、描述一致性、POM
- 计算包 SHA-256;同插件同版本不可覆盖
- 登记为草稿,等待运营发布
开发者自测时,请确保包能通过上述校验后再联系上架。本地安装可用客户工程 CLI(若工程已集成):
bash
pnpm forge:plugin check "/absolute/path/to/plugin.zip"预检不能代替安全审查与人工审核。
开发时还需遵守
- 编码规范:命名、异常、日志、SQL 落 Mapper XML 等
- 菜单 / API 权限需可授权;不得依赖默认放开
- 功能编码走
FeatureGate,不能代替登录与 RBAC - 插件迁移独立历史;不要改已执行脚本,不要指望卸载自动删库
相关文档
- 源码插件购买与安装 — 购买方视角
- Starter / Plugin 如何选择 — 框架内模块拆分(非市场上架协议)
- 扩展机制总览 — 微内核分层背景
