mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-01 06:36:38 +08:00
docs(plugins): add plugin layered architecture spec and templates
This commit is contained in:
ryan
@@ -16,17 +16,41 @@ description: "Wavelet 项目专用：当新增或修改业务 API、Handler、
|
||||
|
||||
### 插件目录推荐结构 (`backend/plugins/domain/<name>/` 或下游 `custom_plugins/<name>/`)
|
||||
|
||||
#### 模式 1：扁平自包含分层（适用于简单业务逻辑 / 推荐默认）
|
||||
```text
|
||||
backend/plugins/domain/order/
|
||||
├── plugin.go # 插件入口：实现 core.Plugin，通过 ctx.Router() 挂载路由
|
||||
├── handlers.go # HTTP 控制器：参数校验、上下文提取、调用 Service、信封响应
|
||||
├── service.go # 业务服务层：纯 Go 逻辑，仅依赖 context.Context
|
||||
├── models.go # GORM 数据实体定义（自带表前缀）
|
||||
├── repository.go # 数据库访问层：GORM 查询、SQL 防注入与转义
|
||||
├── models.go # GORM 数据实体定义（自带表前缀）与 DTO
|
||||
├── errs.go # 模块内错误常量定义（camelCase 字符串）
|
||||
└── migrations/ # 专属嵌入式 Goose SQL 迁移脚本
|
||||
└── 20260827000001_create_orders_table.sql
|
||||
```
|
||||
|
||||
#### 模式 2：严格子包分层架构（适用于复杂业务逻辑 / 多聚合根 / 大代码量）
|
||||
```text
|
||||
backend/plugins/domain/order/
|
||||
├── plugin.go # 插件根入口：实现 core.Plugin，装配各子包并向 Cordis 注册
|
||||
├── controller/ # package controller：HTTP 控制器与路由声明
|
||||
│ ├── http.go
|
||||
│ └── router.go
|
||||
├── service/ # package service：业务逻辑层（用例编排、事件发布）
|
||||
│ ├── service.go
|
||||
│ └── service_impl.go
|
||||
├── repository/ # package repository：数据持久化访问层 (DAL)
|
||||
│ ├── repository.go
|
||||
│ └── repository_impl.go
|
||||
├── model/ # package model：纯数据实体与 DTO（无外部依赖）
|
||||
│ ├── entity.go
|
||||
│ └── dto.go
|
||||
├── errs/ # package errs：错误常量与错误码
|
||||
│ └── errs.go
|
||||
└── migrations/ # 专属嵌入式 Goose SQL 迁移脚本
|
||||
└── 20260827000001_create_orders_table.sql
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 插件契约与路由注册流程
|
||||
|
||||
@@ -99,9 +99,11 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
|
||||
- 跨插件通信的统一公开 Go Interface（如 `AuthService`、`UserService`、`CacheService`、`DBService`、`StorageService`）与公共 DTO。
|
||||
- **严禁**包含任何具体业务实现或 SQL 操作。
|
||||
- **自包含插件 (`backend/plugins/`)**：
|
||||
- 所有业务功能与驱动实现均以扁平自包含插件形式存在（`backend/plugins/drivers/`、`backend/plugins/infra/`、`backend/plugins/domain/` 或下游 `backend/downstream/`）。
|
||||
- 所有业务功能与驱动实现均以插件形式存在（`backend/plugins/drivers/`、`backend/plugins/infra/`、`backend/plugins/domain/` 或下游 `backend/downstream/`）。
|
||||
- 每个插件实现 `core.Plugin`（`Name() string` 与 `Apply(ctx *core.Context) error`）。
|
||||
- 插件内部就近组织 Handler、Service、Model 与 Migration。
|
||||
- **分层模式选型**：
|
||||
- **模式 1（扁平自包含分层，简单业务默认）**：单 package 结构（`plugin.go`, `handlers.go`, `service.go`, `repository.go`, `models.go`, `errs.go`, `migrations/`）。
|
||||
- **模式 2（严格子包物理分层，复杂业务使用）**：多 package 物理隔离（`plugin.go`, `controller/`, `service/`, `repository/`, `model/`, `errs/`, `migrations/`），严格约束 `controller -> service -> repository -> model` 单向依赖。
|
||||
- **插件通信与依赖隔离**：
|
||||
- **严禁跨包 import internal/私有实现**：插件之间严禁直接 import 对方具体实现包代码。
|
||||
- **单向服务契约调用**：调用方仅面向 `backend/core/contracts` 编程，在 `Apply` 中通过 `core.Provide[contracts.XxxService](ctx, svc)` 注册服务，通过 `core.Inject[contracts.XxxService](ctx)` 或 `ctx.Using(func(svc contracts.XxxService) { ... })` 声明式解析。
|
||||
|
||||
@@ -32,6 +32,11 @@
|
||||
- [场景 22：插件如何安全处理文件上传与大文件摄取 (upload.Ingest)？](#场景-22插件如何安全处理文件上传与大文件摄取-uploadingest)
|
||||
- [第二部分：整个项目的目录结构划分与包职责定义](#第二部分整个项目的目录结构划分与包职责定义)
|
||||
- [第三部分：框架核心提供给插件调用的公用能力矩阵 (Context Capability Matrix)](#第三部分框架核心提供给插件调用的公用能力矩阵-context-capability-matrix)
|
||||
- [第四部分：Cordis 插件分层开发规范与代码模板 (Plugin Layered Architecture & Code Templates)](#第四部分cordis-插件分层开发规范与代码模板-plugin-layered-architecture--code-templates)
|
||||
- [1. 分型与选型策略 (模式 1 vs 模式 2)](#1-分型与选型策略-模式-1-vs-模式-2)
|
||||
- [2. 模式 1：扁平自包含分层规范与完整代码模板](#2-模式-1扁平自包含分层规范与完整代码模板)
|
||||
- [3. 模式 2：严格子包物理分层规范与完整代码模板](#3-模式-2严格子包物理分层规范与完整代码模板)
|
||||
- [4. 各层核心职责边界与严格禁止防线 (Guardrails)](#4-各层核心职责边界与严格禁止防线-guardrails)
|
||||
|
||||
---
|
||||
|
||||
@@ -603,7 +608,10 @@ Wavelet/
|
||||
- **职责**：仅定义公开的 Go Interface 和公共 DTO。
|
||||
- **严禁**：严禁包含任何具体实现逻辑或 SQL 操作。
|
||||
3. **`plugins/`**：
|
||||
- **职责**：所有业务逻辑和驱动实现的归宿。每个插件扁平自包含。
|
||||
- **职责**：所有业务逻辑和驱动实现的归宿。遵循标准分层架构（Layered Architecture / MVC 变体）。
|
||||
- **分层模式选型**：
|
||||
- **模式 1（扁平自包含分层，简单业务推荐）**：单 package 内部通过文件划分职责（`plugin.go`, `handlers.go`, `service.go`, `repository.go`, `models.go`, `errs.go`, `migrations/`）。适用于代码量 < 3000 行、单聚合根的插件。
|
||||
- **模式 2（严格子包物理分层，复杂业务推荐）**：多 package 目录级物理隔离（`plugin.go`, `controller/`, `service/`, `repository/`, `model/`, `errs/`, `migrations/`）。编译器级约束 `controller -> service -> repository -> model` 单向依赖。适用于代码量 ≥ 3000 行、多聚合根的大型复杂插件。
|
||||
- **严禁**：插件之间严禁跨包 import 内部私有代码，跨插件调用一律走 `contracts` 接口或 `EventBus`。
|
||||
|
||||
---
|
||||
@@ -632,3 +640,394 @@ Wavelet/
|
||||
| `core.Inject[contracts.TaskService]` | `(TaskService, error)` | 后台任务下发、重试与调度管理契约 | 任务下发与定时调度管理 |
|
||||
| `core.Inject[contracts.RiskControlService]` | `(RiskControlService, error)` | 访问日志查询、聚合分析与存储引擎管理契约 | 审计日志与安全分析 |
|
||||
|
||||
---
|
||||
|
||||
# 第四部分：Cordis 插件分层开发规范与代码模板 (Plugin Layered Architecture & Code Templates)
|
||||
|
||||
为了统一规范 Wavelet 所有官方插件与下游业务二开插件的研发质量，每个插件在内部遵循 **标准分层架构（Layered Architecture / MVC 变体）**。
|
||||
|
||||
## 1. 分型与选型策略 (模式 1 vs 模式 2)
|
||||
|
||||
根据业务复杂度和规模采用不同的物理包组织方式：
|
||||
|
||||
```
|
||||
┌────────────────────────┐
|
||||
│ 插件分层模式选型策略 │
|
||||
└───────────┬────────────┘
|
||||
│
|
||||
┌───────────────────────┴───────────────────────┐
|
||||
▼ ▼
|
||||
【模式 1：扁平自包含分层】 【模式 2：严格子包分层】
|
||||
适合：简单/单一聚合/轻量插件 (<3000行) 适合：复杂业务/多聚合/高协同插件 (≥3000行)
|
||||
结构：单 Package，文件级职责划分 结构：多 Package，目录物理隔离与单向依赖
|
||||
```
|
||||
|
||||
| 维度 | 模式 1：扁平自包含分层 (Flat Self-Contained) | 模式 2：严格子包物理分层 (Strict Sub-packages) |
|
||||
| :--- | :--- | :--- |
|
||||
| **适用场景** | 简单业务、单一聚合根、中小型插件（推荐默认） | 复杂业务、多聚合根、状态流转复杂的大型插件 |
|
||||
| **代码量规模** | 通常 < 3000 行（如 `upload`, `cap`, `system`） | 通常 ≥ 3000 行（如大型 `auth`, `order/billing`, `admin`） |
|
||||
| **Go 包形态** | 单一 Go Package，按文件名语义拆分各层 | 多个 Go Package 物理子目录隔离，编译级约束依赖 |
|
||||
| **核心优势** | 彻底杜绝 Go 循环导入；开发摩擦极小；直观扁平 | 强约束调用方向（Controller → Service → Repo → Model） |
|
||||
|
||||
---
|
||||
|
||||
## 2. 模式 1：扁平自包含分层规范与完整代码模板
|
||||
|
||||
### 2.1 目录结构
|
||||
```text
|
||||
backend/plugins/domain/order/
|
||||
├── plugin.go # [Cordis 接入层] 实现 core.Plugin，负责 Apply 组装、依赖注入与扩展点注册
|
||||
├── handlers.go # [Controller 层] HTTP 控制器：参数校验、上下文提取、信封响应 (response.OK/Abort)
|
||||
├── service.go # [Service 层] 核心业务用例、事务编排、事件触发 (ctx.Events().Emit)，仅接收 context.Context
|
||||
├── repository.go # [Repository 层] 数据持久化层：GORM / DB 操作、SQL 防注入与 EscapeLike 转义
|
||||
├── models.go # [Model 层] GORM 表映射实体 (带插件前缀)、入参/出参 DTO、请求响应结构体
|
||||
├── errs.go # [Error 层] 模块内专用错误常量 (camelCase 字符串)
|
||||
├── plugin_test.go # 插件级单元与集成测试
|
||||
└── migrations/ # [Migration 层] 专属 Goose SQL 嵌入文件 (//go:embed)
|
||||
└── 20260828000001_init_order.sql
|
||||
```
|
||||
|
||||
### 2.2 核心代码模板 (模式 1)
|
||||
|
||||
#### (1) `plugin.go` (插件入口与装配)
|
||||
```go
|
||||
package order
|
||||
|
||||
import (
|
||||
"embed"
|
||||
"reflect"
|
||||
|
||||
"github.com/Rain-kl/Wavelet/core"
|
||||
"github.com/Rain-kl/Wavelet/core/contracts"
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
//go:embed migrations/*.sql
|
||||
var orderMigrations embed.FS
|
||||
|
||||
const PluginName = "domain.order"
|
||||
|
||||
type Plugin struct {
|
||||
svc *OrderService
|
||||
}
|
||||
|
||||
func New() *Plugin {
|
||||
return &Plugin{}
|
||||
}
|
||||
|
||||
func (p *Plugin) Name() string {
|
||||
return PluginName
|
||||
}
|
||||
|
||||
func (p *Plugin) Inject() []reflect.Type {
|
||||
return []reflect.Type{
|
||||
reflect.TypeFor[contracts.DBService](),
|
||||
}
|
||||
}
|
||||
|
||||
func (p *Plugin) Apply(ctx *core.Context) error {
|
||||
// 1. 注册专属数据库迁移
|
||||
ctx.Migrations().Register("order", orderMigrations)
|
||||
|
||||
// 2. 初始化持久层与服务层
|
||||
repo := newOrderRepository(ctx)
|
||||
p.svc = newOrderService(ctx, repo)
|
||||
|
||||
// 3. 注册 HTTP 路由组
|
||||
authSvc, _ := core.Inject[contracts.AuthService](ctx)
|
||||
group := ctx.Router().Group("/api/v1/orders")
|
||||
if authSvc != nil {
|
||||
group.Use(authSvc.RequireAuthMiddleware())
|
||||
}
|
||||
{
|
||||
group.POST("", p.handleCreateOrder)
|
||||
group.GET("/:id", p.handleGetOrderDetail)
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
#### (2) `handlers.go` (Controller 层)
|
||||
```go
|
||||
package order
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
|
||||
"github.com/Rain-kl/Wavelet/pkg/oauth"
|
||||
"github.com/Rain-kl/Wavelet/pkg/response"
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
// @Summary 创建订单
|
||||
// @Description 创建新的用户订单
|
||||
// @Tags Order
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Param request body CreateOrderRequest true "创建参数"
|
||||
// @Success 200 {object} response.Envelope{data=OrderDTO} "成功"
|
||||
// @Failure 400 {object} response.Envelope "参数错误"
|
||||
// @Router /api/v1/orders [post]
|
||||
func (p *Plugin) handleCreateOrder(c *gin.Context) {
|
||||
var req CreateOrderRequest
|
||||
if err := c.ShouldBindJSON(&req); err != nil {
|
||||
response.AbortBadRequest(c, errBindParamsFailed)
|
||||
return
|
||||
}
|
||||
|
||||
user, ok := oauth.GetCurrentUser(c)
|
||||
if !ok {
|
||||
response.AbortUnauthorized(c, errUnauthorized)
|
||||
return
|
||||
}
|
||||
|
||||
order, err := p.svc.CreateOrder(c.Request.Context(), user.ID, req)
|
||||
if err != nil {
|
||||
response.AbortInternal(c, errCreateOrderFailed)
|
||||
return
|
||||
}
|
||||
|
||||
c.JSON(http.StatusOK, response.OK(order))
|
||||
}
|
||||
```
|
||||
|
||||
#### (3) `service.go` (Service 业务逻辑层)
|
||||
```go
|
||||
package order
|
||||
|
||||
import (
|
||||
"context"
|
||||
|
||||
"github.com/Rain-kl/Wavelet/core"
|
||||
)
|
||||
|
||||
type OrderService struct {
|
||||
ctx *core.Context
|
||||
repo *orderRepository
|
||||
}
|
||||
|
||||
func newOrderService(ctx *core.Context, repo *orderRepository) *OrderService {
|
||||
return &OrderService{ctx: ctx, repo: repo}
|
||||
}
|
||||
|
||||
func (s *OrderService) CreateOrder(ctx context.Context, userID string, req CreateOrderRequest) (*OrderDTO, error) {
|
||||
order := &OrderModel{
|
||||
UserID: userID,
|
||||
Amount: req.Amount,
|
||||
Status: "pending",
|
||||
}
|
||||
|
||||
if err := s.repo.Create(ctx, order); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// 发射领域事件
|
||||
s.ctx.Events().Emit(ctx, "order:created", OrderCreatedEvent{
|
||||
OrderID: order.ID,
|
||||
UserID: order.UserID,
|
||||
Amount: order.Amount,
|
||||
})
|
||||
|
||||
return &OrderDTO{
|
||||
ID: order.ID,
|
||||
Amount: order.Amount,
|
||||
Status: order.Status,
|
||||
}, nil
|
||||
}
|
||||
```
|
||||
|
||||
#### (4) `repository.go` (Repository 数据访问层)
|
||||
```go
|
||||
package order
|
||||
|
||||
import (
|
||||
"context"
|
||||
|
||||
"github.com/Rain-kl/Wavelet/core"
|
||||
"github.com/Rain-kl/Wavelet/core/contracts"
|
||||
"github.com/Rain-kl/Wavelet/pkg/util"
|
||||
"gorm.io/gorm"
|
||||
)
|
||||
|
||||
type orderRepository struct {
|
||||
ctx *core.Context
|
||||
}
|
||||
|
||||
func newOrderRepository(ctx *core.Context) *orderRepository {
|
||||
return &orderRepository{ctx: ctx}
|
||||
}
|
||||
|
||||
func (r *orderRepository) getDB(ctx context.Context) *gorm.DB {
|
||||
if dbSvc, err := core.Inject[contracts.DBService](r.ctx); err == nil && dbSvc != nil {
|
||||
return dbSvc.GetDB().WithContext(ctx)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (r *orderRepository) Create(ctx context.Context, order *OrderModel) error {
|
||||
return r.getDB(ctx).Create(order).Error
|
||||
}
|
||||
|
||||
func (r *orderRepository) SearchByKeyword(ctx context.Context, keyword string) ([]OrderModel, error) {
|
||||
var list []OrderModel
|
||||
// SQL LIKE 防注入与通配符转义规范
|
||||
safeKeyword := util.EscapeLike(keyword) + "%"
|
||||
err := r.getDB(ctx).Where("status LIKE ? ESCAPE '\\'", safeKeyword).Find(&list).Error
|
||||
return list, err
|
||||
}
|
||||
```
|
||||
|
||||
#### (5) `models.go` 与 `errs.go`
|
||||
```go
|
||||
// models.go
|
||||
package order
|
||||
|
||||
import "time"
|
||||
|
||||
type OrderModel struct {
|
||||
ID string `gorm:"column:id;primaryKey;size:64" json:"id"`
|
||||
UserID string `gorm:"column:user_id;index;size:64;not null" json:"user_id"`
|
||||
Amount int64 `gorm:"column:amount;not null" json:"amount"`
|
||||
Status string `gorm:"column:status;size:32;index;not null;default:'pending'" json:"status"`
|
||||
CreatedAt time.Time `gorm:"column:created_at;autoCreateTime" json:"created_at"`
|
||||
UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime" json:"updated_at"`
|
||||
}
|
||||
|
||||
func (OrderModel) TableName() string {
|
||||
return "w_orders"
|
||||
}
|
||||
|
||||
type CreateOrderRequest struct {
|
||||
Amount int64 `json:"amount" binding:"required,gt=0"`
|
||||
}
|
||||
|
||||
type OrderDTO struct {
|
||||
ID string `json:"id"`
|
||||
Amount int64 `json:"amount"`
|
||||
Status string `json:"status"`
|
||||
}
|
||||
|
||||
type OrderCreatedEvent struct {
|
||||
OrderID string `json:"order_id"`
|
||||
UserID string `json:"user_id"`
|
||||
Amount int64 `json:"amount"`
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// errs.go
|
||||
package order
|
||||
|
||||
const (
|
||||
errBindParamsFailed = "errBindParamsFailed"
|
||||
errUnauthorized = "errUnauthorized"
|
||||
errCreateOrderFailed = "errCreateOrderFailed"
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 模式 2：严格子包物理分层规范与完整代码模板
|
||||
|
||||
用于大型复杂插件，各层使用独立的 Go package 物理隔离。
|
||||
|
||||
### 3.1 目录结构
|
||||
```text
|
||||
backend/plugins/domain/order/
|
||||
├── plugin.go # [插件根入口] 实现 core.Plugin，装配各子包并向 Cordis 注册
|
||||
├── controller/ # package controller：HTTP API Handler
|
||||
│ ├── http.go # 参数校验、上下文提取、调用 service、信封响应与 Swagger 注解
|
||||
│ └── router.go # 路由组挂载
|
||||
├── service/ # package service：核心业务逻辑
|
||||
│ ├── service.go # 业务用例接口定义 (Service Interface)
|
||||
│ └── service_impl.go # 业务接口实现 (ServiceImpl)
|
||||
├── repository/ # package repository：数据访问持久化层 (DAL)
|
||||
│ ├── repository.go # 仓储接口定义 (Repository Interface)
|
||||
│ └── repository_impl.go # GORM 数据持久化实现与安全转义
|
||||
├── model/ # package model：纯领域实体与传输对象（零外部框架依赖）
|
||||
│ ├── entity.go # 数据库映射实体 (TableName() 必须带 w_<plugin>_ 前缀)
|
||||
│ └── dto.go # 请求与响应 DTO
|
||||
├── errs/ # package errs：错误常量与错误码定义
|
||||
│ └── errs.go
|
||||
└── migrations/ # Goose SQL 独立迁移嵌入文件
|
||||
└── 20260828000001_init_order.sql
|
||||
```
|
||||
|
||||
### 3.2 模式 2 核心装配代码范例 (`plugin.go`)
|
||||
```go
|
||||
package order
|
||||
|
||||
import (
|
||||
"embed"
|
||||
|
||||
"github.com/Rain-kl/Wavelet/core"
|
||||
"github.com/Rain-kl/Wavelet/core/contracts"
|
||||
"github.com/Rain-kl/Wavelet/plugins/domain/order/controller"
|
||||
"github.com/Rain-kl/Wavelet/plugins/domain/order/repository"
|
||||
"github.com/Rain-kl/Wavelet/plugins/domain/order/service"
|
||||
)
|
||||
|
||||
//go:embed migrations/*.sql
|
||||
var orderMigrations embed.FS
|
||||
|
||||
type Plugin struct{}
|
||||
|
||||
func (p *Plugin) Name() string {
|
||||
return "domain.order"
|
||||
}
|
||||
|
||||
func (p *Plugin) Apply(ctx *core.Context) error {
|
||||
// 1. 注册迁移
|
||||
ctx.Migrations().Register("order", orderMigrations)
|
||||
|
||||
// 2. 构造数据层与服务层
|
||||
repo := repository.NewOrderRepository(ctx)
|
||||
svc := service.NewOrderService(ctx, repo)
|
||||
|
||||
// 3. 构造控制器并挂载路由
|
||||
ctrl := controller.NewOrderController(svc)
|
||||
authSvc, _ := core.Inject[contracts.AuthService](ctx)
|
||||
controller.RegisterRoutes(ctx.Router(), ctrl, authSvc)
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 各层核心职责边界与严格禁止防线 (Guardrails)
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ Controller / Handler 层 (HTTP 接入) │
|
||||
│ • 参数绑定 ShouldBindJSON • 用户会话 oauth.GetCurrentUser │
|
||||
│ • 统一信封 response.OK/Abort* • 严禁 SQL 操作 / 严禁重度业务 │
|
||||
└─────────────────────────────────┬────────────────────────────────┘
|
||||
│ 调用 Service (入参 context.Context)
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ Service 层 (业务用例 & 领域逻辑) │
|
||||
│ • 纯 Go 逻辑 (零 Web 依赖) • 事务编排 ctx.DB().Transaction │
|
||||
│ • 领域事件 ctx.Events().Emit • 严禁 import gin / c.JSON │
|
||||
└─────────────────────────────────┬────────────────────────────────┘
|
||||
│ 调用 Repository 接口
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ Repository 层 (数据持久化 DAL) │
|
||||
│ • GORM CRUD 与查询 • EscapeLike 通配符安全转义 │
|
||||
│ • 严禁反向依赖 Service/Controller • 严禁越权读写其他插件数据表 │
|
||||
└─────────────────────────────────┬────────────────────────────────┘
|
||||
│ 映射
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ Model 层 (纯实体 & DTO) │
|
||||
│ • TableName() 带专属表前缀 • 请求/响应结构体 │
|
||||
│ • 零值与 DB 默认值匹配 • 无任何上层包依赖 │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
1. **表单一所有者原则 (Single Owner Principle)**：数据表有且仅由所属插件操作（表名统一前缀 `w_<plugin>_*`），跨插件一律通过公开契约 Interface 或 EventBus 协同。
|
||||
2. **LIKE 查询安全防注入**：所有涉及用户输入的模糊查询，必须经过 `util.EscapeLike` 转义通配符并显式声明 `ESCAPE '\\'` 语法。
|
||||
3. **Goroutine 安全**：并发任务统一使用 `util.Go`，杜绝直接使用裸 `go func()`。
|
||||
|
||||
|
||||
@@ -563,7 +563,10 @@ Wavelet/
|
||||
- **职责**：仅定义公开的 Go Interface 和公共 DTO。
|
||||
- **严禁**：严禁包含任何具体实现逻辑或 SQL 操作。
|
||||
3. **`plugins/`**：
|
||||
- **职责**：所有业务逻辑和驱动实现的归宿。每个插件扁平自包含。
|
||||
- **职责**：所有业务逻辑和驱动实现的归宿。遵循标准分层架构（Layered Architecture / MVC 变体）。
|
||||
- **分层模式选型**：
|
||||
- **模式 1（扁平自包含分层，简单业务推荐）**：单 package 内部通过文件划分职责（`plugin.go`, `handlers.go`, `service.go`, `repository.go`, `models.go`, `errs.go`, `migrations/`）。适用于代码量 < 3000 行、单聚合根的插件。
|
||||
- **模式 2（严格子包物理分层，复杂业务推荐）**：多 package 目录级物理隔离（`plugin.go`, `controller/`, `service/`, `repository/`, `model/`, `errs/`, `migrations/`）。编译器级约束 `controller -> service -> repository -> model` 单向依赖。适用于代码量 ≥ 3000 行、多聚合根的大型复杂插件。
|
||||
- **严禁**：插件之间严禁跨包 import 内部私有代码，跨插件调用一律走 `contracts` 接口或 `EventBus`。
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,124 @@
|
||||
# Cordis 架构插件标准分层设计规范 (Plugin Layered Architecture Spec)
|
||||
|
||||
- **文档状态**: 已敲定 (Approved)
|
||||
- **版本**: v1.0.0 (2026-08-28)
|
||||
- **适用范围**: Wavelet 官方插件 (`backend/plugins/`)、下游定制插件 (`downstream/custom_plugins/`)
|
||||
|
||||
---
|
||||
|
||||
## 1. 架构总览与分型原则 (Architecture & Selection Strategy)
|
||||
|
||||
在 Wavelet 的 Cordis 微内核架构中，系统通过 **微内核 (`core/`) + 服务契约 (`core/contracts/`) + 自包含插件 (`plugins/`)** 实现高度解耦与单向依赖。
|
||||
为了规范插件内部代码组织，插件遵循 **标准分层架构（Layered Architecture / MVC 变体）**，并根据业务复杂度提供两套标准物理包结构：
|
||||
|
||||
| 模式 | 适用场景 | 复杂度特征 | 物理结构形式 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **模式 1：扁平自包含分层**<br>(Flat Self-Contained) | 简单逻辑插件（推荐默认） | 代码量 < 3000 行、单聚合根、单一职责（如 `upload`, `cap`, `system`） | 单 Go package，文件级划分职责 |
|
||||
| **模式 2：严格子包分层**<br>(Strict Sub-packages) | 复杂业务插件 | 代码量 ≥ 3000 行、多聚合根、状态机流转复杂（如大型 `auth`, `order/billing`, `admin`） | 多 Go package，目录级物理隔离 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 模式 1：扁平自包含分层规范 (Flat Self-Contained Package)
|
||||
|
||||
适合中小型或单一功能插件。所有代码位于同个 package（如 `package order`），彻底避免 Go 子包循环导入。
|
||||
|
||||
### 2.1 目录结构
|
||||
```text
|
||||
backend/plugins/domain/<plugin_name>/
|
||||
├── plugin.go # [Cordis 接入层] 实现 core.Plugin，负责 Apply 组装、依赖注入与扩展点注册
|
||||
├── handlers.go # [Controller 层] Gin API Handler：参数校验、认证上下文提取、信封响应 (response.OK/Abort)
|
||||
├── service.go # [Service 层] 核心业务用例、事务编排、事件触发 (ctx.Events().Emit)，入参仅为 context.Context
|
||||
├── repository.go # [Repository 层] 数据持久化层：GORM / DB 操作、SQL 防注入与转义
|
||||
├── models.go # [Model 层] 数据表映射模型 (GORM)、入参/出参 DTO、请求响应结构体
|
||||
├── errs.go # [Error 层] 模块内专用错误常量 (camelCase 字符串)
|
||||
├── plugin_test.go # 插件单元与集成测试
|
||||
└── migrations/ # [Migration 层] 专属 Goose SQL 嵌入文件 (//go:embed)
|
||||
└── 20260828000001_init_<plugin_name>.sql
|
||||
```
|
||||
|
||||
### 2.2 横向文件扩展
|
||||
当某一职责文件变大时，按语义横向拆分（仍在同一 package 内）：
|
||||
- `handlers_admin.go`, `handlers_user.go`
|
||||
- `models_dto.go`, `models_entity.go`
|
||||
|
||||
---
|
||||
|
||||
## 3. 模式 2：严格子包分层规范 (Strict Sub-package Architecture)
|
||||
|
||||
适合重型业务插件，通过 Go package 物理隔离强制依赖方向（`controller -> service -> repository -> model`）。
|
||||
|
||||
### 3.1 目录结构
|
||||
```text
|
||||
backend/plugins/domain/<plugin_name>/
|
||||
├── plugin.go # [插件根入口] 实现 core.Plugin，装配各子包并向 Cordis 注册
|
||||
├── controller/ # package controller：HTTP API Handler
|
||||
│ ├── http.go # Gin 请求参数校验与信封响应
|
||||
│ └── router.go # 路由映射与中间件挂载函数
|
||||
├── service/ # package service：核心业务逻辑
|
||||
│ ├── service.go # 业务接口定义 (Service Interface)
|
||||
│ └── service_impl.go # 业务接口实现 (ServiceImpl)
|
||||
├── repository/ # package repository：数据持久化访问层
|
||||
│ ├── repository.go # 仓储接口定义 (Repository Interface)
|
||||
│ └── repository_impl.go # GORM 数据持久化实现
|
||||
├── model/ # package model：纯实体与 DTO（无外部依赖）
|
||||
│ ├── entity.go # 数据库映射实体 (TableName 带插件前缀)
|
||||
│ └── dto.go # 请求与响应 DTO
|
||||
├── errs/ # package errs：错误常量与错误码定义
|
||||
│ └── errs.go
|
||||
└── migrations/ # Goose SQL 独立迁移嵌入文件
|
||||
└── 20260828000001_init_<plugin_name>.sql
|
||||
```
|
||||
|
||||
### 3.2 依赖方向约束 (Strict Dependency Flow)
|
||||
```mermaid
|
||||
graph TD
|
||||
Plugin[plugin.go 入口] --> Controller[controller/]
|
||||
Plugin --> Service[service/]
|
||||
Plugin --> Repository[repository/]
|
||||
Controller --> Service
|
||||
Controller --> Model[model/]
|
||||
Controller --> Errs[errs/]
|
||||
Service --> Repository
|
||||
Service --> Model
|
||||
Service --> Errs
|
||||
Repository --> Model
|
||||
```
|
||||
* **禁止反向依赖**：`repository` 严禁依赖 `service` 或 `controller`；`service` 严禁依赖 `controller`；`model` 严禁依赖任何上层包。
|
||||
|
||||
---
|
||||
|
||||
## 4. 各层职责边界与编码守则 (Layer Responsibilities & Guardrails)
|
||||
|
||||
### 4.1 Controller / Handler 层 (接入层)
|
||||
1. **参数绑定**：使用 `c.ShouldBindJSON` 或 `c.ShouldBindQuery`。
|
||||
2. **上下文提取**：从 `*gin.Context` 提取登录态（如 `oauth.GetCurrentUser(c)`）。
|
||||
3. **调用下游**：调用 Service 方法，禁止直接调用 Repository 或编写 SQL。
|
||||
4. **统一信封响应**：
|
||||
- 成功：`c.JSON(http.StatusOK, response.OK(data))` 或 `response.OKNil()`。
|
||||
- 失败：使用 `backend/pkg/response` 的 `Abort*` 系列函数（如 `AbortBadRequest`、`AbortUnauthorized`、`AbortNotFound`、`AbortInternal`）。
|
||||
5. **Swagger 注释**：每个导出 Handler 必须编写完整的 OpenAPI/Swagger 注解。
|
||||
|
||||
### 4.2 Service 层 (业务用例层)
|
||||
1. **纯 Go 逻辑**：第一参数必须为 `ctx context.Context`，返回 `(result, error)`。
|
||||
2. **禁止依赖 Web 框架**：严禁 import `github.com/gin-gonic/gin`，严禁接收 `*gin.Context`，严禁调用 `c.JSON`/`Abort*`。
|
||||
3. **事务编排**：涉及插件内多表原子操作时，通过 `ctx.DB().Transaction(...)` 编排。
|
||||
4. **事件驱动解耦**：跨插件业务通知与状态联动统一通过 `ctx.Events().Emit(...)` 广播领域事件，杜绝直接跨插件调用私有方法。
|
||||
|
||||
### 4.3 Repository 层 (持久化访问层)
|
||||
1. **GORM / SQL 操作**：统一接收 `context.Context`，通过 `db.WithContext(ctx)` 操作数据。
|
||||
2. **SQL LIKE 防注入**：所有含用户输入的模糊查询必须调用 `backend/pkg/util.EscapeLike` 并显式声明 `ESCAPE '\\'`。
|
||||
3. **表单一所有者原则**：仅操作本插件所属表（前缀 `w_<plugin>_*`），严禁越权 DML/DDL 其他插件所有表。
|
||||
|
||||
### 4.4 Model 层 (实体与 DTO 层)
|
||||
1. **GORM 映射**：显式实现 `TableName() string` 返回带前缀表名。
|
||||
2. **零值对齐**：Go 结构体字段零值必须与数据库默认值匹配。
|
||||
3. **无物理外键**：禁止物理外键约束，显式建立单列/复合索引。
|
||||
|
||||
### 4.5 Plugin 入口 (Cordis 生命周期与装配)
|
||||
1. 实现 `core.Plugin` 接口（`Name() string` 与 `Apply(ctx *core.Context) error`）。
|
||||
2. 在 `Apply` 中完成：
|
||||
- 依赖注入与解析（`core.Provide` / `core.Inject` / `ctx.Using`）
|
||||
- 路由与中间件声明（`ctx.Router().Group(...)`）
|
||||
- 异步与定时任务注册（`ctx.Task().Register` / `ctx.Schedule().RegisterCron`）
|
||||
- 配置与设置声明（`ctx.Settings().Register` / `ctx.Config().Bind`）
|
||||
- 数据库迁移注册（`ctx.Migrations().Register`）
|
||||
Reference in New Issue
Block a user