Skip to content

MengStack v2.0 插件开发指南 ​

MengStack v2.0 插件系统基于 Plugin 接口 + 六维权限沙箱 + Uber FX 依赖注入,每个插件是独立的 Go 模块,通过实现标准接口接入框架。

概述 ​

v2.0 插件系统特性 ​

特性说明
Plugin 接口6 个方法标准化插件生命周期
六维权限沙箱Database / Storage / Network / Events / Routes / AdminPanel
FX 依赖注入每个插件是独立的 fx.Module
安全初始化SafeInit + SafeSetupRoutes 使用 defer recover()
独立迁移每插件独立迁移表 schema_migrations_{plugin_name}
事件总线EventBus 异步发布 + 沙箱权限检查

架构概览 ​

┌─────────────────────────────────────────────┐
│              MengStack 主进程                 │
│  ┌─────────────────────────────────────┐    │
│  │         Plugin Manager              │    │
│  │  SafeInit / SafeSetupRoutes         │    │
│  │  defer recover() 隔离 panic         │    │
│  └─────────────────────────────────────┘    │
│         │ FX           │ FX           │ FX  │
│  ┌──────▼──┐  ┌──────▼──┐  ┌──────▼──┐    │
│  │ Plugin A │  │ Plugin B │  │ Plugin C │    │
│  │ (fx.Mod) │  │ (fx.Mod) │  │ (fx.Mod) │    │
│  └─────────┘  └─────────┘  └─────────┘    │
│         │              │              │      │
│  ┌──────▼──────────────▼──────────────▼──┐ │
│  │     PostgreSQL  │  Redis  │  EventBus  │ │
│  └────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

环境准备 ​

前置条件 ​

  • Go 1.26+
  • MengStack v2.0 发行版
  • PostgreSQL 16+
  • Redis 7+

获取发行版 ​

bash
git clone https://mengstackgit.softunis.com/softunis/mengstack-kernel-dist.git
cd mengstack-kernel-dist

Plugin 接口 ​

每个插件必须实现 kernel/plugin/plugin.go 中定义的 6 个方法:

go
type Plugin interface {
    Metadata() Metadata
    Permissions() Permissions
    FxOption() fx.Option
    SetupRoutes(engine *gin.Engine, authMW gin.HandlerFunc,
                tenantResolver tenant.Resolver,
                requirePerm RequirePermissionFunc)
    Init() error
    MigrationsFS() fs.FS
}
方法作用
Metadata()返回插件元数据(ID、名称、版本、作者、描述)
Permissions()声明六维权限沙箱
FxOption()返回 FX 依赖注入模块
SetupRoutes()注册 HTTP 路由 + 权限中间件
Init()插件初始化(建表、种子数据等)
MigrationsFS()返回嵌入的 SQL 迁移文件系统

插件目录结构 ​

v2.0 采用四层架构标准结构:

my-plugin/
├── plugin.go              # Plugin 接口实现(入口)
├── domain/                # 领域层
│   ├── entity.go          # 实体定义(嵌入 BaseModel + TenantID)
│   └── repository.go      # 仓储接口
├── application/           # 应用层
│   └── service.go         # 业务服务
├── infrastructure/        # 基础设施层
│   ├── repository.go      # GORM 仓储实现
│   └── migration/         # SQL 迁移文件
│       └── 001_init.sql
├── interfaces/            # 接口层
│   ├── handler.go         # HTTP 处理器
│   └── plugin.go          # SetupRoutes 路由注册
└── README.md

实现示例 ​

1. 插件入口 ​

go
package myplugin

import (
    "embed"
    "io/fs"
    "mengstack/kernel/plugin"
    "go.uber.org/fx"
)

//go:embed infrastructure/migration/*.sql
var migrationFS embed.FS

type MyPlugin struct{}

func New() *MyPlugin { return &MyPlugin{} }

func (p *MyPlugin) Metadata() plugin.Metadata {
    return plugin.Metadata{
        ID:          "my-plugin",
        Name:        "My Plugin",
        Version:     "0.1.0",
        Author:      "SoftUnis",
        Description: "示例插件",
    }
}

func (p *MyPlugin) Permissions() plugin.Permissions {
    return plugin.Permissions{
        Database: []string{"my_resources"},
        Events:   []string{"my-resource.created"},
        Routes:   []string{"/api/v1/my-resource/*"},
    }
}

func (p *MyPlugin) FxOption() fx.Option {
    return fx.Module("my-plugin",
        fx.Provide(
            NewRepository,
            NewService,
            NewHandler,
        ),
    )
}

func (p *MyPlugin) Init() error {
    return nil
}

func (p *MyPlugin) MigrationsFS() fs.FS {
    sub, _ := fs.Sub(migrationFS, "infrastructure/migration")
    return sub
}

2. 路由注册 ​

go
// interfaces/plugin.go
func (p *MyPlugin) SetupRoutes(
    engine *gin.Engine,
    authMW gin.HandlerFunc,
    tenantResolver tenant.Resolver,
    requirePerm plugin.RequirePermissionFunc,
) {
    api := engine.Group("/api/v1/my-resource")
    {
        // 公开路由
        api.GET("", p.handler.List)
        api.GET("/:id", p.handler.Detail)

        // 需认证 + 权限的路由
        auth := api.Group("")
        auth.Use(authMW)
        auth.POST("", requirePerm("my-resource.write"), p.handler.Create)
        auth.PUT("/:id", requirePerm("my-resource.write"), p.handler.Update)
        auth.DELETE("/:id", requirePerm("my-resource.write"), p.handler.Delete)
    }
}

3. 数据模型 ​

go
// domain/entity.go
type MyResource struct {
    kernel.BaseModel
    TenantID string `gorm:"type:uuid;not null;index;primaryKey"`
    Name     string `gorm:"type:varchar(255);not null"`
    Status   string `gorm:"type:varchar(20);default:active"`
}

多租户自动过滤

内核的 tenant.Scope() 自动注入 tenant_id 过滤条件。Handler 通过 tenant.FromContext(c.Request.Context()) 获取租户 ID。

4. 数据库迁移 ​

sql
-- infrastructure/migration/001_init.sql
CREATE TABLE IF NOT EXISTS my_resources (
    id          BIGSERIAL PRIMARY KEY,
    tenant_id   UUID NOT NULL,
    name        VARCHAR(255) NOT NULL,
    status      VARCHAR(20) DEFAULT 'active',
    created_at  TIMESTAMPTZ DEFAULT NOW(),
    updated_at  TIMESTAMPTZ DEFAULT NOW(),
    deleted_at  TIMESTAMPTZ,
    PRIMARY KEY (id, tenant_id)
);

CREATE INDEX idx_my_resources_tenant ON my_resources(tenant_id);
CREATE INDEX idx_my_resources_deleted ON my_resources(deleted_at) WHERE deleted_at IS NULL;

六维权限沙箱 ​

每个插件通过 Permissions() 声明所需资源,运行时由 Sandbox 强制检查:

go
type Permissions struct {
    Database   []string  // 允许访问的表名
    Storage    bool      // 是否允许文件存储
    Network    []string  // 允许访问的域名
    Events     []string  // 允许发布的事件
    Routes     []string  // 允许注册的路由(支持 /* 通配)
    AdminPanel bool      // 是否允许管理面板
}
检查方法作用
CheckDatabase(plugin, table)表级数据库访问控制
CheckStorage(plugin)文件存储访问控制
CheckNetwork(plugin, domain)域名白名单网络控制
CheckEvent(plugin, event)事件发布控制
CheckRoute(plugin, path)路由注册验证
CheckAdminPanel(plugin)管理面板访问控制

SafeInit 和 SafeSetupRoutes 使用 defer recover() 包裹插件调用,单个插件 panic 不影响其他插件和主进程。

EventBus 集成 ​

插件可通过 EventBus 发布和订阅事件:

go
// 发布事件(沙箱检查权限)
bus.SafePublish(ctx, "my-plugin", "my-resource.created", permChecker)

// 异步发布
bus.PublishAsync(ctx, envelope)

异步队列容量 1024,4 Workers 并发消费。详见 核心能力 — EventBus。

注册插件 ​

在主应用的 FX 模块列表中添加新插件:

go
// 注册插件到 Plugin Manager
manager.Register(myplugin.New())

Plugin Manager 启动时依次调用每个插件的 Init() 和 SetupRoutes()。

当前 10 个内置插件(含 example 示例) ​

插件版本功能
example0.1.0示例插件,演示开发模式
cms0.5.0文章、版本、频道、分类、标签
comment-interaction0.1.0评论、点赞、收藏、举报、分享、统计
topic0.1.0专题管理
flash0.1.0快讯/快讯分类
community0.1.0论坛板块、帖子、回复
search0.2.0全文搜索、搜索建议、热词
seo0.3.1TDK、站点地图、robots、重定向、内链
media1.1.0上传流水线、分片上传、图片样式、审核、配额、回收站
author0.1.0入驻申请、作者画像、等级体系、公开作者页

常见问题 ​

Q: 插件崩溃会影响主服务吗? ​

A: 不会。SafeInit 和 SafeSetupRoutes 使用 defer recover() 捕获 panic,单个插件崩溃不影响其他插件和主进程。

Q: 如何在插件中使用多租户? ​

A: Handler 通过 tenant.FromContext(c.Request.Context()) 获取租户 ID,Repository 通过 tenant.Scope(id) 自动过滤查询。

Q: 插件可以访问其他插件的数据表吗? ​

A: 沙箱通过 CheckDatabase(plugin, table) 控制表级访问。插件只能访问 Permissions().Database 中声明的表。

Q: 迁移文件如何管理? ​

A: 每个插件独立迁移表 schema_migrations_{plugin_name},通过 MigrationsFS() 返回嵌入的 SQL 文件系统。

Released under the Apache 2.0 License.