Appearance
MengStack v1.0 插件开发指南
已弃用
v1.0 插件系统已弃用。新功能开发请使用 v2.0 插件系统。
MengStack v1.0 提供了基础插件系统,支持通过回调注册机制为框架添加自定义功能。
概述
v1.0 插件系统基于 回调注册 模式,插件在主进程内运行,通过注册回调函数介入框架的请求处理和数据流转。
v1.0 插件能力
| 能力 | 说明 |
|---|---|
| 路由扩展 | 注册自定义 HTTP 路由和处理器 |
| 中间件注入 | 在请求链路中插入自定义中间件 |
| 事件监听 | 监听框架内部事件 |
| 数据模型扩展 | 通过 Migration 扩展数据库表结构 |
v1.0 与 v2.0 对比
| 特性 | v1.0 | v2.0 |
|---|---|---|
| 扩展点模式 | 回调注册 | Plugin 接口 + 六维权限沙箱 |
| 沙箱隔离 | 无(主进程内运行) | SafeInit/SafeSetupRoutes panic 恢复 |
| 插件更新 | 需重启 | 需重编译(编译期装配) |
| 权限模型 | 简单声明 | 六维权限(Database/Storage/Network/Events/Routes/AdminPanel) |
| 依赖注入 | 无 | Uber FX 模块化注入 |
| 插件数量 | — | 10 个内置插件 |
环境准备
前置条件
- Go 1.21+
- MengStack v1.0 发行版
- PostgreSQL 15+
- Redis 6+
获取发行版
bash
git clone https://mengstackgit.softunis.com/softunis/mengstack-kernel-dist.git
cd mengstack-kernel-dist插件目录结构
v1.0 插件遵循统一的目录规范:
my-plugin/
├── plugin.go # 插件入口与回调注册
├── routes.go # 路由注册
├── handlers/ # 请求处理器
│ ├── create.go
│ ├── update.go
│ └── delete.go
├── models/ # 数据模型
│ └── entity.go
├── migrations/ # 数据库迁移
│ └── 001_init.sql
└── README.md路由注册
插件通过回调函数注册自定义 API 端点:
go
// 注册路由示例
func RegisterRoutes(router *gin.Engine) {
group := router.Group("/api/v1/my-resource")
{
group.GET("/", ListHandler)
group.GET("/:id", DetailHandler)
group.POST("/", CreateHandler)
group.PUT("/:id", UpdateHandler)
group.DELETE("/:id", DeleteHandler)
}
}数据模型
定义实体
go
type MyResource struct {
ID int64 `json:"id" db:"id"`
TenantID int64 `json:"tenant_id" db:"tenant_id"`
Name string `json:"name" db:"name"`
Status string `json:"status" db:"status"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
}多租户注意
v1.0 中所有数据表必须包含 tenant_id 字段,并在查询时显式过滤,确保租户数据隔离。
数据库迁移
在 migrations/ 目录下创建 SQL 迁移文件:
sql
-- migrations/001_init.sql
CREATE TABLE IF NOT EXISTS my_resources (
id BIGSERIAL PRIMARY KEY,
tenant_id BIGINT NOT NULL,
name VARCHAR(255) NOT NULL,
status VARCHAR(20) DEFAULT 'active',
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_my_resources_tenant ON my_resources(tenant_id);迁移到 v2.0
v1.0 插件迁移到 v2.0 需要:
- 实现 Plugin 接口 — 编写
Metadata()、Permissions()、FxOption()、SetupRoutes()、Init()、MigrationsFS()六个方法 - 声明六维权限 — 将简单权限声明迁移为 Database/Storage/Network/Events/Routes/AdminPanel 六维配置
- 接入 FX 依赖注入 — 将手动初始化改为
fx.Provide模块化注入 - 添加沙箱权限 — 在
Permissions()中声明所需的数据库表、事件、路由等资源
详细步骤参考 v2.0 插件开发指南。
常见问题
Q: v1.0 插件能在 v2.0 中使用吗?
A: 不能直接使用。v2.0 引入了 Plugin 接口和六维权限沙箱,需要适配迁移。
Q: 插件之间如何通信?
A: 通过 EventBus 事件总线,使用发布/订阅模式解耦。详见 核心能力 — EventBus。
Q: 如何保证插件的安全性?
A: v1.0 插件运行在主进程内,建议:
- 严格校验所有外部输入
- 不直接操作其他插件的数据表
- 遵循最小权限原则
- 升级到 v2.0 使用沙箱隔离

