4. 领域服务层
插件领域服务层架构
插件领域服务层是Coze Studio中处理插件业务逻辑的核心层,负责插件资源的编辑、更新和业务规则实现。该层采用领域驱动设计(DDD)模式,将业务逻辑与数据访问分离,确保代码的可维护性和可扩展性。
插件领域服务接口定义
文件位置:backend/domain/plugin/service/service.go
插件领域服务接口定义了插件管理的核心业务能力,包括插件资源的编辑和更新功能。
go
type PluginService interface {
// 创建插件草稿
CreateDraftPlugin(ctx context.Context, req *CreateDraftPluginRequest) error
// 获取插件草稿
GetDraftPlugin(ctx context.Context, pluginID int64) (*entity.PluginInfo, bool, error)
// 更新插件草稿
UpdateDraftPlugin(ctx context.Context, req *UpdateDraftPluginRequest) error
// 通过代码更新插件草稿
UpdateDraftPluginWithCode(ctx context.Context, req *UpdateDraftPluginWithCodeRequest) error
// 更新工具
UpdateDraftTool(ctx context.Context, req *UpdateDraftToolRequest) error
// 删除插件草稿
DeleteDraftPlugin(ctx context.Context, pluginID int64) error
// 获取插件工具列表
GetDraftPluginTools(ctx context.Context, pluginID int64) ([]*entity.ToolInfo, error)
// 检查插件名称是否重复
CheckPluginNameDuplicate(ctx context.Context, req *CheckPluginNameDuplicateRequest) (bool, error)
// 更新插件状态
UpdatePluginStatus(ctx context.Context, req *UpdatePluginStatusRequest) error
}
核心接口功能:
- 插件资源管理:获取、更新、删除用户自定义的插件资源
- 编辑操作核心:UpdateDraftPluginWithCode方法是编辑插件的核心业务接口
- 工具管理:支持单个工具的独立更新操作
- 业务规则封装:封装插件编辑相关的业务逻辑和验证规则
- 数据一致性:确保插件数据的完整性和一致性
- 多版本支持:维护插件的不同版本状态
插件领域服务实现
文件位置:backend/domain/plugin/service/plugin_draft.go
插件服务实现类包含了所有插件相关业务逻辑的具体实现,依赖于仓储层进行数据持久化。
go
type pluginServiceImpl struct {
pluginRepo repository.PluginRepository
toolRepo repository.ToolRepository
}
func NewService(pluginRepo repository.PluginRepository, toolRepo repository.ToolRepository) PluginService {
return &pluginServiceImpl{
pluginRepo: pluginRepo,
toolRepo: toolRepo,
}
}
编辑操作核心实现:
go
// UpdateDraftPluginWithCode 通过代码更新插件草稿
// 文件位置:backend/domain/plugin/service/plugin_draft.go
func (p *pluginServiceImpl) UpdateDraftPluginWithCode(ctx context.Context, req *UpdateDraftPluginWithCodeRequest) (err error) {
// 验证OpenAPI文档和Manifest
var doc *openapi3.T
doc, err = req.OpenapiDoc.Validate(ctx)
if err != nil {
return errorx.Wrapf(err, "validate openapi doc failed")
}
var mf *pluginModel.PluginManifest
mf, err = req.Manifest.Validate(false)
if err != nil {
return errorx.Wrapf(err, "validate manifest failed")
}
// 获取当前插件草稿
draftPlugin, exist, err := p.pluginRepo.GetDraftPlugin(ctx, req.PluginID)
if err != nil {
return errorx.Wrapf(err, "GetDraftPlugin failed, pluginID=%d", req.PluginID)
}
if !exist {
return errorx.New(errno.ErrPluginRecordNotFound)
}
// 处理服务器URL变更
if doc.Servers != nil && len(doc.Servers) > 0 && draftPlugin.GetServerURL() != doc.Servers[0].URL {
// URL变更时需要重置调试状态
// ...
}
// 获取当前工具列表
oldDraftTools, err := p.toolRepo.GetDraftPluginTools(ctx, req.PluginID)
if err != nil {
return errorx.Wrapf(err, "GetDraftPluginTools failed, pluginID=%d", req.PluginID)
}
// 构建工具映射
oldDraftToolsMap := make(map[model.APIKey]*entity.ToolInfo)
for i := range oldDraftTools {
oldDraftToolsMap[model.NewAPIKey(*oldDraftTools[i].Method, *oldDraftTools[i].SubURL)] = oldDraftTools[i]
}
// 构建新的API映射
apis := make([]model.APIKey, 0, len(doc.Paths))
apiSchemas := make(map[model.APIKey]*openapi3.Operation)
for path, pathItem := range doc.Paths {
for method, operation := range pathItem.Operations() {
apiKey := model.NewAPIKey(strings.ToUpper(method), path)
apis = append(apis, apiKey)
apiSchemas[apiKey] = operation
}
}
// 1. 删除工具 -> 关闭启用
for api, oldTool := range oldDraftToolsMap {
_, ok := apiSchemas[api]
if !ok {
oldTool.DebugStatus = ptr.Of(common.APIDebugStatus_DebugWaiting)
oldTool.ActivatedStatus = ptr.Of(model.DeactivateTool)
}
}
newDraftTools := make([]*entity.ToolInfo, 0, len(apis))
for api, newOp := range apiSchemas {
oldTool, ok := oldDraftToolsMap[api]
if ok { // 2. 更新工具 -> 覆盖
oldTool.ActivatedStatus = ptr.Of(model.ActivateTool)
oldTool.Operation = newOp
if needResetDebugStatusTool(ctx, newOp, oldTool.Operation) {
oldTool.DebugStatus = ptr.Of(common.APIDebugStatus_DebugWaiting)
}
continue
}
// 3. 新增工具
newDraftTools = append(newDraftTools, &entity.ToolInfo{
PluginID: req.PluginID,
ActivatedStatus: ptr.Of(model.ActivateTool),
DebugStatus: ptr.Of(common.APIDebugStatus_DebugWaiting),
SubURL: ptr.Of(api.SubURL),
Method: ptr.Of(api.Method),
Operation: newOp,
})
}
// 调用仓储层更新插件
err = p.pluginRepo.UpdateDraftPluginWithCode(ctx, &repository.UpdatePluginDraftWithCode{
PluginID: req.PluginID,
SpaceID: req.SpaceID,
DeveloperID: req.DeveloperID,
PluginType: req.PluginType,
IconURI: req.IconURI,
ServerURL: req.ServerURL,
AppID: req.AppID,
OpenapiDoc: doc,
Manifest: mf,
UpdatedTools: oldDraftTools,
NewDraftTools: newDraftTools,
EditVersion: req.EditVersion,
})
if err != nil {
return errorx.Wrapf(err, "UpdateDraftPluginWithCode failed, pluginID=%d", req.PluginID)
}
return nil
}
调试状态重置判断:
go
// needResetDebugStatusTool 判断是否需要重置调试状态
func needResetDebugStatusTool(ctx context.Context, newOp, oldOp *openapi3.Operation) bool {
// 当请求或响应结构发生变化时,重置调试状态
if reflect.DeepEqual(newOp.RequestBody, oldOp.RequestBody) {
return false
}
if reflect.DeepEqual(newOp.Parameters, oldOp.Parameters) && reflect.DeepEqual(newOp.Responses, oldOp.Responses) {
return false
}
return true
}
更新操作实现特点:
- 依赖注入:通过Repository接口注入数据访问能力,实现松耦合
- 仓储模式:使用Repository模式进行数据访问抽象,隔离业务逻辑与数据层
- 数据验证:完整的数据验证机制,确保更新数据的有效性
- 业务隔离:领域服务层专注于业务逻辑,数据操作委托给仓储层
- 工具状态管理:智能处理工具的删除、更新和新增三种状态
- 调试状态重置:根据API结构变化自动重置相关工具的调试状态
UpdateDraftPluginWithCode方法详解:
- 参数丰富:接收UpdateDraftPluginWithCodeRequest参数,包含插件更新所需的完整信息
- 数据验证:验证OpenAPI文档和Manifest的完整性和有效性
- 插件获取:获取当前插件草稿信息,用于比较和更新
- 工具管理:智能管理工具的三种状态(删除、更新、新增)
- 调试状态:根据API结构变化自动重置调试状态
- 错误处理:完善的错误处理和传播机制,确保更新异常的正确处理
- 业务纯净:不包含权限验证等应用层逻辑,专注于领域层的更新操作
插件实体定义
文件位置:backend/domain/plugin/entity/plugin.go
插件实体定义了插件资源的核心数据结构,包含了插件的所有关键属性。
go
type PluginInfo struct {
ID int64 // 插件唯一标识
PluginType common.PluginType // 插件类型(本地/远程)
SpaceID int64 // 所属空间ID,支持多租户隔离
DeveloperID int64 // 开发者ID
APPID *int64 // 关联应用ID
IconURI *string // 插件图标URI
ServerURL *string // 服务器URL
Manifest *model.PluginManifest // 插件清单信息
OpenapiDoc *model.Openapi3T // OpenAPI文档
Version *string // 版本号(用于发布)
VersionDesc *string // 版本描述(用于发布)
CreatedAt int64 // 创建时间戳
UpdatedAt int64 // 更新时间戳
}
实体设计特点:
- 基础信息:包含ID、类型、空间等基本属性,满足插件的基本信息需求
- 类型支持:PluginType字段支持本地和远程插件类型,灵活适配不同场景
- 多租户支持:SpaceID字段支持多租户和空间隔离,确保数据安全
- 开发者管理:DeveloperID字段支持开发者权限控制和资源归属管理
- 应用关联:APPID字段支持插件与应用的关联关系
- 配置管理:Manifest和OpenapiDoc字段存储插件的配置和API文档
- 版本管理:Version和VersionDesc字段支持插件的版本管理
- 时间追踪:CreatedAt和UpdatedAt支持创建和更新时间追踪,便于审计和版本管理
5. 数据访问层
5.1 仓储接口定义
插件仓储接口
文件位置:backend/domain/plugin/repository/plugin.go
go
type PluginRepository interface {
// 获取插件草稿
GetDraftPlugin(ctx context.Context, pluginID int64) (*entity.PluginInfo, bool, error)
// 创建插件草稿
CreateDraftPlugin(ctx context.Context, req *CreateDraftPluginRequest) error
// 更新插件草稿
UpdateDraftPlugin(ctx context.Context, req *UpdateDraftPluginRequest) error
// 通过代码更新插件草稿
UpdateDraftPluginWithCode(ctx context.Context, req *UpdatePluginDraftWithCode) error
// 获取插件工具列表
GetDraftPluginTools(ctx context.Context, pluginID int64) ([]*entity.ToolInfo, error)
// 删除插件草稿
DeleteDraftPlugin(ctx context.Context, pluginID int64) error
// 检查插件名称是否重复
CheckPluginNameDuplicate(ctx context.Context, spaceID int64, name string, excludePluginID ...int64) (bool, error)
}
type ToolRepository interface {
// 获取插件工具列表
GetDraftPluginTools(ctx context.Context, pluginID int64) ([]*entity.ToolInfo, error)
}
type UpdatePluginDraftWithCode struct {
PluginID int64
SpaceID int64
DeveloperID int64
PluginType int32
IconURI string
ServerURL string
AppID int64
OpenapiDoc *model.Openapi3T
Manifest *model.PluginManifest
UpdatedTools []*entity.ToolInfo
NewDraftTools []*entity.ToolInfo
EditVersion int32
}
接口功能特点:
- 数据操作抽象:将插件数据的更新、查询等操作抽象为接口方法
- 完整生命周期:支持插件数据的获取、更新等核心操作
- 事务支持:特别是UpdateDraftPluginWithCode方法,支持复杂的事务操作
- 解耦设计:通过接口实现业务层与数据层的解耦,便于测试和替换实现
- 批量操作支持:支持插件和工具的批量操作,提高数据处理效率
- 查询能力:提供获取插件和工具列表的查询能力
5.2 数据访问对象(DAO)
插件编辑的具体实现
文件位置:backend/domain/plugin/repository/plugin_impl.go
插件编辑操作涉及数据验证、事务管理和数据更新,需要通过事务确保数据一致性:
go
type pluginRepositoryImpl struct {
pluginDraftDAO dao.PluginDraftDAO
toolDraftDAO dao.ToolDraftDAO
db db.DB
idGenerator idgen.IDGenerator
cache cache.Cache
}
func NewPluginRepository(
pluginDraftDAO dao.PluginDraftDAO,
toolDraftDAO dao.ToolDraftDAO,
db db.DB,
idGenerator idgen.IDGenerator,
cache cache.Cache,
) PluginRepository {
return &pluginRepositoryImpl{
pluginDraftDAO: pluginDraftDAO,
toolDraftDAO: toolDraftDAO,
db: db,
idGenerator: idGenerator,
cache: cache,
}
}
// UpdateDraftPluginWithCode 通过代码更新插件草稿
func (r *pluginRepositoryImpl) UpdateDraftPluginWithCode(ctx context.Context, req *UpdatePluginDraftWithCode) error {
// 开始事务
tx, err := r.db.Begin(ctx)
if err != nil {
return errorx.Wrapf(err, "Begin transaction failed")
}
defer func() {
if err != nil {
tx.Rollback()
return
}
err = tx.Commit()
}()
// 1. 更新插件信息
pluginDO := &dao.PluginDraftDO{
ID: req.PluginID,
OpenapiDoc: req.OpenapiDoc,
Manifest: req.Manifest,
UpdatedAt: time.Now().Unix(),
}
err = r.pluginDraftDAO.UpdateWithTX(ctx, tx, pluginDO)
if err != nil {
return errorx.Wrapf(err, "Update plugin draft failed, pluginID=%d", req.PluginID)
}
// 2. 更新已有工具
for i := range req.UpdatedTools {
toolDO := &dao.ToolDraftDO{
ID: req.UpdatedTools[i].ID,
PluginID: req.UpdatedTools[i].PluginID,
Operation: req.UpdatedTools[i].Operation,
ActivatedStatus: req.UpdatedTools[i].ActivatedStatus,
DebugStatus: req.UpdatedTools[i].DebugStatus,
SubURL: req.UpdatedTools[i].SubURL,
Method: req.UpdatedTools[i].Method,
UpdatedAt: time.Now().Unix(),
}
// 检查工具是否存在
_, exist, err := r.toolDraftDAO.GetByID(ctx, toolDO.ID)
if err != nil {
return errorx.Wrapf(err, "Get tool draft failed, toolID=%d", toolDO.ID)
}
if exist {
// 更新已有工具
err = r.toolDraftDAO.UpdateWithTX(ctx, tx, toolDO)
if err != nil {
return errorx.Wrapf(err, "Update tool draft failed, toolID=%d", toolDO.ID)
}
}
}
// 3. 创建新工具
for i := range req.NewDraftTools {
toolDO := &dao.ToolDraftDO{
ID: r.idGenerator.GenID(),
PluginID: req.NewDraftTools[i].PluginID,
Operation: req.NewDraftTools[i].Operation,
ActivatedStatus: req.NewDraftTools[i].ActivatedStatus,
DebugStatus: req.NewDraftTools[i].DebugStatus,
SubURL: req.NewDraftTools[i].SubURL,
Method: req.NewDraftTools[i].Method,
CreatedAt: time.Now().Unix(),
UpdatedAt: time.Now().Unix(),
}
err = r.toolDraftDAO.CreateWithTX(ctx, tx, toolDO)
if err != nil {
return errorx.Wrapf(err, "Create new tool draft failed")
}
}
// 4. 删除缓存
cacheKey := fmt.Sprintf("plugin:%d:draft", req.PluginID)
err = r.cache.Del(ctx, cacheKey)
if err != nil {
// 缓存删除失败不影响主流程,只记录日志
log.Error("delete plugin draft cache failed", err, log.Int64("pluginID", req.PluginID))
}
return nil
}
更新操作的关键特点:
- 事务保证:使用数据库事务确保所有更新操作的原子性
- 多表协调:协调更新插件和相关工具的数据
- 错误处理:完善的错误处理和事务回滚机制
- 缓存管理:更新后删除相关缓存,确保数据一致性
- ID生成:为新创建的工具生成唯一ID
更新涉及的数据表:
- plugin_draft:插件草稿表
- tool_draft:工具草稿表
- plugin_cache:插件缓存(删除操作)
PluginDraftDAO结构体
文件位置:backend/domain/plugin/internal/dal/plugin_draft.go
PluginDraftDAO是插件草稿数据访问的具体实现,负责与数据库进行交互,处理插件草稿资源的更新操作。
go
package dal
type PluginDraftDAO interface {
// Update 更新插件草稿
Update(ctx context.Context, req *PluginDraftDO) error
// UpdateWithTX 使用事务更新插件草稿
UpdateWithTX(ctx context.Context, tx db.TX, req *PluginDraftDO) error
// GetByID 根据ID获取插件草稿
GetByID(ctx context.Context, id int64) (*PluginDraftDO, bool, error)
// GetBySpaceIDAndDeveloperID 根据空间ID和开发者ID获取插件草稿列表
GetBySpaceIDAndDeveloperID(ctx context.Context, spaceID, developerID int64) ([]*PluginDraftDO, error)
// GetByName 根据名称获取插件草稿
GetByName(ctx context.Context, name string, spaceID int64) (*PluginDraftDO, bool, error)
}
type ToolDraftDAO interface {
// CreateWithTX 使用事务创建工具草稿
CreateWithTX(ctx context.Context, tx db.TX, req *ToolDraftDO) error
// UpdateWithTX 使用事务更新工具草稿
UpdateWithTX(ctx context.Context, tx db.TX, req *ToolDraftDO) error
// GetByID 根据ID获取工具草稿
GetByID(ctx context.Context, id int64) (*ToolDraftDO, bool, error)
// GetByPluginID 根据插件ID获取工具草稿列表
GetByPluginID(ctx context.Context, pluginID int64) ([]*ToolDraftDO, error)
// DeleteByPluginID 根据插件ID删除所有工具草稿
DeleteByPluginID(ctx context.Context, tx db.TX, pluginID int64) error
// BatchCreateWithTX 批量创建工具草稿
BatchCreateWithTX(ctx context.Context, tx db.TX, reqs []*ToolDraftDO) error
}
插件更新操作实现
更新插件草稿:
go
// UpdateWithTX 使用事务更新插件草稿
func (dao *pluginDraftDAOImpl) UpdateWithTX(ctx context.Context, tx db.TX, req *PluginDraftDO) error {
// 构建更新参数
updates := map[string]interface{}{}
// 只更新非零值字段
if req.OpenapiDoc != nil {
updates["openapi_doc"] = req.OpenapiDoc
}
if req.Manifest != nil {
updates["manifest"] = req.Manifest
}
if req.IconURI != "" {
updates["icon_uri"] = req.IconURI
}
if req.ServerURL != "" {
updates["server_url"] = req.ServerURL
}
if req.AppID > 0 {
updates["app_id"] = req.AppID
}
if req.RefProductID > 0 {
updates["ref_product_id"] = req.RefProductID
}
if req.EditVersion > 0 {
updates["edit_version"] = req.EditVersion
}
// 始终更新时间戳
updates["updated_at"] = req.UpdatedAt
// 执行更新操作
result := tx.Model(&dao.PluginDraftPO{}).Where("id = ?", req.ID).Updates(updates)
if result.Error != nil {
return errorx.Wrapf(result.Error, "update plugin draft failed, id=%d", req.ID)
}
if result.RowsAffected == 0 {
return errorx.Wrapf(errno.ErrRecordNotFound, "plugin draft not found, id=%d", req.ID)
}
return nil
}
}
// UpdateDraftPluginWithCode 实现插件草稿更新的核心数据访问逻辑
func (dao *pluginDraftDAOImpl) UpdateDraftPluginWithCode(ctx context.Context, req *UpdateDraftPluginWithCodeRequest) error {
// 检查插件是否存在
_, exist, err := dao.GetByID(ctx, req.PluginID)
if err != nil {
return errorx.Wrapf(err, "get plugin draft failed, id=%d", req.PluginID)
}
if !exist {
return errorx.New(errno.ErrPluginRecordNotFound)
}
// 验证OpenAPI文档和Manifest
err = req.OpenapiDoc.Validate(ctx)
if err != nil {
return errorx.Wrapf(err, "validate openapi doc failed")
}
err = req.Manifest.Validate(false)
if err != nil {
return errorx.Wrapf(err, "validate manifest failed")
}
// 构建插件更新数据
pluginDO := &PluginDraftDO{
ID: req.PluginID,
OpenapiDoc: req.OpenapiDoc,
Manifest: req.Manifest,
UpdatedAt: time.Now().Unix(),
}
// 更新插件信息
err = dao.Update(ctx, pluginDO)
if err != nil {
return errorx.Wrapf(err, "update plugin draft failed, id=%d", req.PluginID)
}
return nil
}
更新操作特点:
- 事务更新:UpdateWithTX方法支持事务操作,确保数据一致性
- 参数构建:智能构建更新参数,优化数据库操作
- 数据验证:更新前进行数据验证,确保数据有效性
- 错误处理:完善的错误处理和日志记录
- 缓存管理:支持缓存的删除操作,保持数据一致性
更新插件的完整数据访问流程:
在编辑插件的场景中,数据访问层的操作流程如下:
- 事务开始:首先开启数据库事务,确保操作的原子性
- 参数准备:准备更新所需的参数和数据结构
- 插件更新:更新插件的基本信息、OpenAPI文档和Manifest
- 工具处理 :
- 更新已有的工具信息
- 创建新的工具记录
- 缓存清理:删除相关的缓存数据,确保一致性
- 事务提交:所有操作成功后提交事务
- 错误处理:任何步骤失败时回滚事务并返回错误
这种设计确保了编辑操作的安全性、可靠性和数据完整性。
数据访问层更新操作总结:
更新插件在数据访问层的实现具有以下特点:
- 事务保证:所有更新操作在事务中执行,确保数据一致性
- 多表协调:同时更新插件和相关工具数据
- 类型安全:使用参数化查询,避免SQL注入风险
- 错误处理:完善的错误处理和事务回滚机制
- 数据验证:更新前进行数据验证,确保插件数据的完整性
- 缓存管理:更新后删除相关缓存,确保数据一致性
- 性能优化:通过批量更新和高效查询,确保更新操作的高效执行
5.3 插件数据模型
PluginDraft数据模型
文件位置:backend/domain/plugin/internal/dal/model/plugin_draft.gen.go
该文件由GORM代码生成工具自动生成,定义了与数据库表对应的Go结构体。在创建插件操作中,该模型定义了数据库记录的结构,为创建操作提供了数据映射基础。
go
// Code generated by gorm.io/gen. DO NOT EDIT.
package model
const TableNamePluginDraft = "plugin_draft"
// PluginDraft plugin_draft
type PluginDraft struct {
ID int64 `gorm:"column:id;primaryKey;autoIncrement:true;comment:id" json:"id"` // id
SpaceID int64 `gorm:"column:space_id;not null;comment:space id" json:"space_id"` // space id
DeveloperID int64 `gorm:"column:developer_id;not null;comment:developer id" json:"developer_id"` // developer id
PluginType int32 `gorm:"column:plugin_type;not null;comment:plugin type" json:"plugin_type"` // plugin type
IconURI string `gorm:"column:icon_uri;comment:icon uri" json:"icon_uri"` // icon uri
ServerURL string `gorm:"column:server_url;comment:server url" json:"server_url"` // server url
AppID int64 `gorm:"column:app_id;comment:app id" json:"app_id"` // app id
RefProductID int64 `gorm:"column:ref_product_id;comment:reference product id" json:"ref_product_id"` // reference product id
Manifest *PluginManifest `gorm:"column:manifest;type:json;comment:plugin manifest" json:"manifest"` // plugin manifest
OpenapiDoc *Openapi3T `gorm:"column:openapi_doc;type:json;comment:openapi document" json:"openapi_doc"` // openapi document
CreatedAt int64 `gorm:"column:created_at;not null;autoCreateTime:milli;comment:Create Time in Milliseconds" json:"created_at"` // Create Time in Milliseconds
UpdatedAt int64 `gorm:"column:updated_at;not null;autoUpdateTime:milli;comment:Update Time in Milliseconds" json:"updated_at"` // Update Time in Milliseconds
EditVersion int32 `gorm:"column:edit_version;default:0;comment:edit version" json:"edit_version"` // edit version
}
// TableName PluginDraft's table name
func (*PluginDraft) TableName() string {
return TableNamePluginDraft
}
ToolDraft数据模型
文件位置:backend/domain/plugin/internal/dal/model/tool_draft.gen.go
go
// ToolDraft tool_draft
type ToolDraft struct {
ID int64 `gorm:"column:id;primaryKey;autoIncrement:true;comment:id" json:"id"` // id
PluginID int64 `gorm:"column:plugin_id;not null;comment:plugin id" json:"plugin_id"` // plugin id
SubURL string `gorm:"column:sub_url;comment:sub url" json:"sub_url"` // sub url
Method string `gorm:"column:method;comment:http method" json:"method"` // http method
ActivatedStatus int32 `gorm:"column:activated_status;comment:activated status" json:"activated_status"` // activated status
DebugStatus int32 `gorm:"column:debug_status;comment:debug status" json:"debug_status"` // debug status
Operation *Operation `gorm:"column:operation;type:json;comment:operation info" json:"operation"` // operation info
CreatedAt int64 `gorm:"column:created_at;not null;autoCreateTime:milli;comment:Create Time in Milliseconds" json:"created_at"` // Create Time in Milliseconds
UpdatedAt int64 `gorm:"column:updated_at;not null;autoUpdateTime:milli;comment:Update Time in Milliseconds" json:"updated_at"` // Update Time in Milliseconds
}
创建操作中的模型特点:
- 主键生成:ID字段作为主键,通过ID生成器自动生成唯一标识
- 开发者标识:DeveloperID字段标识插件的创建者,用于权限管理
- 关联关系:PluginID字段建立插件与工具的关联关系,支持工具的创建
- 字段映射:通过gorm标签定义字段与数据库列的映射关系,为创建操作提供准确的数据存储
- 约束定义:包含主键、非空、注释等数据库约束,确保创建数据的完整性
- 复杂类型:Manifest和OpenapiDoc字段存储JSON格式的插件配置和API文档
- 审计追踪:CreatedAt和UpdatedAt字段记录创建和更新时间,便于追踪
- JSON序列化:通过json标签支持JSON序列化,便于创建操作的API响应和日志记录
5.4 GORM生成的查询接口
插件查询接口
文件位置:backend/domain/plugin/internal/dal/query/plugin_draft.gen.go
GORM Gen工具生成的类型安全查询接口,为创建插件操作提供了强大的数据访问能力。这些接口确保了创建操作的类型安全性和执行效率。
go
// pluginDraft plugin_draft
type pluginDraft struct {
pluginDraftDo
ALL field.Asterisk
ID field.Int64 // id
SpaceID field.Int64 // space id
DeveloperID field.Int64 // developer id
PluginType field.Int32 // plugin type
IconURI field.String // icon uri
ServerURL field.String // server url
AppID field.Int64 // app id
Manifest field.Field // plugin manifest
OpenapiDoc field.Field // openapi document
CreatedAt field.Int64 // Create Time in Milliseconds
UpdatedAt field.Int64 // Update Time in Milliseconds
fieldMap map[string]field.Expr
}
工具查询接口
文件位置:backend/domain/plugin/internal/dal/query/tool_draft.gen.go
go
// 文件位置:backend/domain/plugin/internal/dal/query/plugin.gen.go
// plugin Latest Plugin
type plugin struct {
pluginDo
ALL field.Asterisk
ID field.Int64 // id
SpaceID field.Int64 // space_id
DeveloperID field.Int64 // developer_id
AppID field.Int64 // app_id
IconURI field.String // icon_uri
ServerURL field.String // server_url
Manifest field.Field // manifest
OpenapiDoc field.Field // openapi_doc
PluginType field.Int32 // plugin_type
CreatedAt field.Int64 // created_at
UpdatedAt field.Int64 // updated_at
fieldMap map[string]field.Expr
}
// 文件位置:backend/domain/plugin/internal/dal/query/tool.gen.go
// tool Latest Tool
type tool struct {
toolDo
ALL field.Asterisk
ID field.Int64 // id
PluginID field.Int64 // plugin_id
SubURL field.String // sub_url
Method field.String // method
ActivatedStatus field.Int32 // activated_status
DebugStatus field.Int32 // debug_status
Operation field.Field // operation
CreatedAt field.Int64 // created_at
UpdatedAt field.Int64 // updated_at
fieldMap map[string]field.Expr
}
查询接口定义
go
// 文件位置:backend/domain/plugin/internal/dal/query/plugin.gen.go
type IPluginDo interface {
gen.SubQuery
Debug() IPluginDo
WithContext(ctx context.Context) IPluginDo
WithResult(fc func(tx gen.Dao)) gen.ResultInfo
ReplaceDB(db *gorm.DB)
ReadDB() IPluginDo
WriteDB() IPluginDo
// 创建操作相关方法
Create(values ...*model.Plugin) error
CreateInBatches(values []*model.Plugin, batchSize int) error
Save(values ...*model.Plugin) error
// 查询操作相关方法
Where(conds ...gen.Condition) IPluginDo
First() (*model.Plugin, error)
Find() ([]*model.Plugin, error)
FindInBatches(result *[]*model.Plugin, batchSize int, fc func(tx gen.Dao, batch int) error) error
// 更新操作相关方法
Update(column field.Expr, value interface{}) (info gen.ResultInfo, err error)
Updates(value interface{}) (info gen.ResultInfo, err error)
// 删除操作相关方法
Delete(...*model.Plugin) (info gen.ResultInfo, err error)
}
// 文件位置:backend/domain/plugin/internal/dal/query/tool.gen.go
type IToolDo interface {
gen.SubQuery
Debug() IToolDo
WithContext(ctx context.Context) IToolDo
// 创建操作相关方法
Create(values ...*model.Tool) error
CreateInBatches(values []*model.Tool, batchSize int) error
Save(values ...*model.Tool) error
// 查询操作相关方法
Where(conds ...gen.Condition) IToolDo
First() (*model.Tool, error)
Find() ([]*model.Tool, error)
// 删除操作相关方法
Delete(...*model.Tool) (info gen.ResultInfo, err error)
}
创建操作相关接口特点:
- Create方法:提供类型安全的创建操作,支持单条和批量数据插入
- Where条件:支持复杂的查询条件构建,确保数据查询的准确性
- 上下文支持:WithContext方法支持请求上下文传递
- 事务支持:支持在事务中执行创建操作,确保数据一致性
- 调试支持:Debug方法便于创建操作的SQL调试和优化
- 关联创建:Tool通过PluginID字段支持工具的关联创建
- 批量操作:CreateInBatches方法支持高效的批量插入操作
- 保存操作:Save方法支持插入或更新操作,根据主键自动判断
5.5 统一查询入口
文件位置:backend\domain\plugin\internal\dal\query\gen.go
该文件为创建插件操作提供了统一的查询入口和事务支持,确保创建操作的一致性和可靠性。
核心代码:
go
// Code generated by gorm.io/gen. DO NOT EDIT.
// Code generated by gorm.io/gen. DO NOT EDIT.
// Code generated by gorm.io/gen. DO NOT EDIT.
package query
import (
"context"
"database/sql"
"gorm.io/gorm"
"gorm.io/gen"
"gorm.io/plugin/dbresolver"
)
var (
Q = new(Query)
Plugin *plugin
Tool *tool
)
func SetDefault(db *gorm.DB, opts ...gen.DOOption) {
*Q = *Use(db, opts...)
Plugin = &Q.Plugin
Tool = &Q.Tool
}
func Use(db *gorm.DB, opts ...gen.DOOption) *Query {
return &Query{
db: db,
Plugin: newPlugin(db, opts...),
Tool: newTool(db, opts...),
}
}
type Query struct {
db *gorm.DB
Plugin plugin
Tool tool
}
func (q *Query) Available() bool { return q.db != nil }
func (q *Query) clone(db *gorm.DB) *Query {
return &Query{
db: db,
Plugin: q.Plugin.clone(db),
Tool: q.Tool.clone(db),
}
}
func (q *Query) ReadDB() *Query {
return q.ReplaceDB(q.db.Clauses(dbresolver.Read))
}
func (q *Query) WriteDB() *Query {
return q.ReplaceDB(q.db.Clauses(dbresolver.Write))
}
func (q *Query) ReplaceDB(db *gorm.DB) *Query {
return &Query{
db: db,
Plugin: q.Plugin.replaceDB(db),
Tool: q.Tool.replaceDB(db),
}
}
type queryCtx struct {
Plugin IPluginDo
Tool IToolDo
}
func (q *Query) WithContext(ctx context.Context) *queryCtx {
return &queryCtx{
Plugin: q.Plugin.WithContext(ctx),
Tool: q.Tool.WithContext(ctx),
}
}
func (q *Query) Transaction(fc func(tx *Query) error, opts ...*sql.TxOptions) error {
return q.db.Transaction(func(tx *gorm.DB) error { return fc(q.clone(tx)) }, opts...)
}
func (q *Query) Begin(opts ...*sql.TxOptions) *QueryTx {
tx := q.db.Begin(opts...)
return &QueryTx{Query: q.clone(tx), Error: tx.Error}
}
type QueryTx struct {
*Query
Error error
}
func (q *QueryTx) Commit() error {
return q.db.Commit().Error
}
func (q *QueryTx) Rollback() error {
return q.db.Rollback().Error
}
func (q *QueryTx) SavePoint(name string) error {
return q.db.SavePoint(name).Error
}
func (q *QueryTx) RollbackTo(name string) error {
return q.db.RollbackTo(name).Error
}
创建操作查询入口特点:
- 全局查询对象:提供全局的Plugin和Tool查询对象,便于创建操作的统一管理
- 事务支持:Transaction方法支持在事务中执行创建操作,确保数据一致性
- 读写分离:ReadDB和WriteDB方法支持数据库读写分离,创建操作使用WriteDB
- 上下文传递:WithContext方法支持请求上下文在创建操作中的传递
- 数据库切换:ReplaceDB方法支持动态切换数据库连接,便于多环境部署
- 事务管理:Begin、Commit、Rollback等方法提供完整的事务管理能力
- 多表支持:同时支持Plugin和Tool两个表的创建操作
- 连接池管理:支持数据库连接池的动态管理和优化
5.6 数据访问层创建操作架构总结
创建插件在数据访问层的实现体现了现代Go应用的最佳实践:
技术特点:
- 类型安全:使用GORM Gen生成类型安全的查询接口,避免SQL注入和类型错误
- 分层设计:Repository接口抽象数据访问,DAO实现具体的数据库操作
- 错误处理:统一的错误码包装机制,便于上层进行错误分类和处理
- 事务支持:完整的事务支持,确保创建操作的原子性
- 性能优化:合理的索引设计和批量插入,确保创建操作的高效执行
- ID生成:支持插件及其关联工具的唯一ID生成操作
安全保障:
- 权限验证:通过DeveloperID字段确保插件创建者的身份标识
- 数据验证:创建前验证插件数据的完整性和有效性
- 唯一性保证:通过ID生成器确保插件ID的唯一性
- 审计追踪:完整的时间戳记录,支持创建操作的审计和追踪
- 关联创建:确保创建插件时正确建立相关的工具数据关联
创建操作流程:
- 接口调用:上层通过Repository接口调用CreateDraftPlugin方法
- ID生成:生成唯一的插件ID,避免ID冲突
- 事务开启:开启数据库事务确保操作的原子性
- 数据插入:将插件数据插入到plugin_draft表中
- 事务提交:所有创建操作成功后提交事务
- 错误处理:任何步骤失败都会回滚事务并返回错误
这种设计确保了创建插件操作的安全性、可靠性和高性能,为上层业务逻辑提供了坚实的数据访问基础。
数据模型与查询文件依赖关系
数据库表结构 (schema.sql)(plugin_draft、tool_draft表)
↓ gen_orm_query.go
模型文件 (model/plugin_draft.gen.go, model/tool_draft.gen.go) - 生成模型
↓
查询文件 (query/plugin_draft.gen.go, query/tool_draft.gen.go) - 依赖对应模型
↓
统一入口 (query/gen.go) - 依赖所有查询文件
数据访问层架构总结
分层架构:
业务服务层 (Service)
↓
仓储接口层 (Repository Interface)
↓
数据访问层 (DAO Implementation)
↓
GORM查询层 (Generated Query)
↓
数据模型层 (Generated Model)
↓
数据库层 (MySQL)
创建插件在数据访问层的完整流程:
- 接口定义 :
PluginRepository.CreateDraftPlugin(ctx, plugin)
定义创建操作契约 - DAO实现 :
PluginDraftDAO.Create(ctx, plugin)
和PluginDraftDAO.CreateWithTX(tx, plugin)
实现具体创建逻辑 - ID生成:使用ID生成器为插件生成唯一标识
- 事务管理:使用事务确保插件数据的一致性创建
- 数据插入:将插件数据插入到plugin_draft表中
- 错误处理:包装创建异常为统一错误码
- 结果返回:创建成功返回插件ID,失败返回包装后的错误
设计优势:
- 接口抽象:通过Repository接口实现数据访问的抽象化
- 代码生成:使用GORM Gen自动生成类型安全的查询代码
- 错误处理:统一的错误包装和处理机制
- 事务支持:通过context传递支持数据库事务
- 创建安全:通过ID生成器确保唯一性,避免ID冲突
- 性能优化:合理的索引设计和批量插入优化
- 可测试性:清晰的分层结构便于单元测试
- 可维护性:代码生成减少手工编写,降低维护成本
- 关联创建:支持插件及其关联数据的一致性创建
创建操作的技术特点:
- 数据插入:当前实现为数据插入,将新插件记录存储到数据库中
- 事务操作:使用数据库事务确保插件数据的一致性创建
- 索引优化:基于主键ID的插入操作,具有最佳的写入性能
- 错误分类:通过错误码区分不同类型的创建异常
- 审计支持:可通过数据库日志追踪创建操作的执行情况
- 关联建立:确保创建插件时正确建立相关的数据关联