Appearance
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-distPlugin 接口
每个插件必须实现 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 示例)
| 插件 | 版本 | 功能 |
|---|---|---|
| example | 0.1.0 | 示例插件,演示开发模式 |
| cms | 0.5.0 | 文章、版本、频道、分类、标签 |
| comment-interaction | 0.1.0 | 评论、点赞、收藏、举报、分享、统计 |
| topic | 0.1.0 | 专题管理 |
| flash | 0.1.0 | 快讯/快讯分类 |
| community | 0.1.0 | 论坛板块、帖子、回复 |
| search | 0.2.0 | 全文搜索、搜索建议、热词 |
| seo | 0.3.1 | TDK、站点地图、robots、重定向、内链 |
| media | 1.1.0 | 上传流水线、分片上传、图片样式、审核、配额、回收站 |
| author | 0.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 文件系统。

