Skip to content

MengStack v1.0 插件开发指南 ​

已弃用

v1.0 插件系统已弃用。新功能开发请使用 v2.0 插件系统。

MengStack v1.0 提供了基础插件系统,支持通过回调注册机制为框架添加自定义功能。

概述 ​

v1.0 插件系统基于 回调注册 模式,插件在主进程内运行,通过注册回调函数介入框架的请求处理和数据流转。

v1.0 插件能力 ​

能力说明
路由扩展注册自定义 HTTP 路由和处理器
中间件注入在请求链路中插入自定义中间件
事件监听监听框架内部事件
数据模型扩展通过 Migration 扩展数据库表结构

v1.0 与 v2.0 对比 ​

特性v1.0v2.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 需要:

  1. 实现 Plugin 接口 — 编写 Metadata()、Permissions()、FxOption()、SetupRoutes()、Init()、MigrationsFS() 六个方法
  2. 声明六维权限 — 将简单权限声明迁移为 Database/Storage/Network/Events/Routes/AdminPanel 六维配置
  3. 接入 FX 依赖注入 — 将手动初始化改为 fx.Provide 模块化注入
  4. 添加沙箱权限 — 在 Permissions() 中声明所需的数据库表、事件、路由等资源

详细步骤参考 v2.0 插件开发指南。

常见问题 ​

Q: v1.0 插件能在 v2.0 中使用吗? ​

A: 不能直接使用。v2.0 引入了 Plugin 接口和六维权限沙箱,需要适配迁移。

Q: 插件之间如何通信? ​

A: 通过 EventBus 事件总线,使用发布/订阅模式解耦。详见 核心能力 — EventBus。

Q: 如何保证插件的安全性? ​

A: v1.0 插件运行在主进程内,建议:

  • 严格校验所有外部输入
  • 不直接操作其他插件的数据表
  • 遵循最小权限原则
  • 升级到 v2.0 使用沙箱隔离

最后更新于:

Released under the Apache 2.0 License.