Coze源码分析-资源库-编辑插件-后端源码-领域/数据访问层

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
}

核心接口功能

  1. 插件资源管理:获取、更新、删除用户自定义的插件资源
  2. 编辑操作核心:UpdateDraftPluginWithCode方法是编辑插件的核心业务接口
  3. 工具管理:支持单个工具的独立更新操作
  4. 业务规则封装:封装插件编辑相关的业务逻辑和验证规则
  5. 数据一致性:确保插件数据的完整性和一致性
  6. 多版本支持:维护插件的不同版本状态
插件领域服务实现

文件位置: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
}

更新操作实现特点

  1. 依赖注入:通过Repository接口注入数据访问能力,实现松耦合
  2. 仓储模式:使用Repository模式进行数据访问抽象,隔离业务逻辑与数据层
  3. 数据验证:完整的数据验证机制,确保更新数据的有效性
  4. 业务隔离:领域服务层专注于业务逻辑,数据操作委托给仓储层
  5. 工具状态管理:智能处理工具的删除、更新和新增三种状态
  6. 调试状态重置:根据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                    // 更新时间戳
}

实体设计特点

  1. 基础信息:包含ID、类型、空间等基本属性,满足插件的基本信息需求
  2. 类型支持:PluginType字段支持本地和远程插件类型,灵活适配不同场景
  3. 多租户支持:SpaceID字段支持多租户和空间隔离,确保数据安全
  4. 开发者管理:DeveloperID字段支持开发者权限控制和资源归属管理
  5. 应用关联:APPID字段支持插件与应用的关联关系
  6. 配置管理:Manifest和OpenapiDoc字段存储插件的配置和API文档
  7. 版本管理:Version和VersionDesc字段支持插件的版本管理
  8. 时间追踪: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
}

接口功能特点

  1. 数据操作抽象:将插件数据的更新、查询等操作抽象为接口方法
  2. 完整生命周期:支持插件数据的获取、更新等核心操作
  3. 事务支持:特别是UpdateDraftPluginWithCode方法,支持复杂的事务操作
  4. 解耦设计:通过接口实现业务层与数据层的解耦,便于测试和替换实现
  5. 批量操作支持:支持插件和工具的批量操作,提高数据处理效率
  6. 查询能力:提供获取插件和工具列表的查询能力

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
}

更新操作的关键特点

  1. 事务保证:使用数据库事务确保所有更新操作的原子性
  2. 多表协调:协调更新插件和相关工具的数据
  3. 错误处理:完善的错误处理和事务回滚机制
  4. 缓存管理:更新后删除相关缓存,确保数据一致性
  5. 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
}

更新操作特点

  1. 事务更新:UpdateWithTX方法支持事务操作,确保数据一致性
  2. 参数构建:智能构建更新参数,优化数据库操作
  3. 数据验证:更新前进行数据验证,确保数据有效性
  4. 错误处理:完善的错误处理和日志记录
  5. 缓存管理:支持缓存的删除操作,保持数据一致性

更新插件的完整数据访问流程

在编辑插件的场景中,数据访问层的操作流程如下:

  1. 事务开始:首先开启数据库事务,确保操作的原子性
  2. 参数准备:准备更新所需的参数和数据结构
  3. 插件更新:更新插件的基本信息、OpenAPI文档和Manifest
  4. 工具处理
    • 更新已有的工具信息
    • 创建新的工具记录
  5. 缓存清理:删除相关的缓存数据,确保一致性
  6. 事务提交:所有操作成功后提交事务
  7. 错误处理:任何步骤失败时回滚事务并返回错误

这种设计确保了编辑操作的安全性、可靠性和数据完整性。

数据访问层更新操作总结

更新插件在数据访问层的实现具有以下特点:

  1. 事务保证:所有更新操作在事务中执行,确保数据一致性
  2. 多表协调:同时更新插件和相关工具数据
  3. 类型安全:使用参数化查询,避免SQL注入风险
  4. 错误处理:完善的错误处理和事务回滚机制
  5. 数据验证:更新前进行数据验证,确保插件数据的完整性
  6. 缓存管理:更新后删除相关缓存,确保数据一致性
  7. 性能优化:通过批量更新和高效查询,确保更新操作的高效执行

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
}

创建操作中的模型特点

  1. 主键生成:ID字段作为主键,通过ID生成器自动生成唯一标识
  2. 开发者标识:DeveloperID字段标识插件的创建者,用于权限管理
  3. 关联关系:PluginID字段建立插件与工具的关联关系,支持工具的创建
  4. 字段映射:通过gorm标签定义字段与数据库列的映射关系,为创建操作提供准确的数据存储
  5. 约束定义:包含主键、非空、注释等数据库约束,确保创建数据的完整性
  6. 复杂类型:Manifest和OpenapiDoc字段存储JSON格式的插件配置和API文档
  7. 审计追踪:CreatedAt和UpdatedAt字段记录创建和更新时间,便于追踪
  8. 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)
}

创建操作相关接口特点

  1. Create方法:提供类型安全的创建操作,支持单条和批量数据插入
  2. Where条件:支持复杂的查询条件构建,确保数据查询的准确性
  3. 上下文支持:WithContext方法支持请求上下文传递
  4. 事务支持:支持在事务中执行创建操作,确保数据一致性
  5. 调试支持:Debug方法便于创建操作的SQL调试和优化
  6. 关联创建:Tool通过PluginID字段支持工具的关联创建
  7. 批量操作:CreateInBatches方法支持高效的批量插入操作
  8. 保存操作: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
}

创建操作查询入口特点

  1. 全局查询对象:提供全局的Plugin和Tool查询对象,便于创建操作的统一管理
  2. 事务支持:Transaction方法支持在事务中执行创建操作,确保数据一致性
  3. 读写分离:ReadDB和WriteDB方法支持数据库读写分离,创建操作使用WriteDB
  4. 上下文传递:WithContext方法支持请求上下文在创建操作中的传递
  5. 数据库切换:ReplaceDB方法支持动态切换数据库连接,便于多环境部署
  6. 事务管理:Begin、Commit、Rollback等方法提供完整的事务管理能力
  7. 多表支持:同时支持Plugin和Tool两个表的创建操作
  8. 连接池管理:支持数据库连接池的动态管理和优化

5.6 数据访问层创建操作架构总结

创建插件在数据访问层的实现体现了现代Go应用的最佳实践:

技术特点

  1. 类型安全:使用GORM Gen生成类型安全的查询接口,避免SQL注入和类型错误
  2. 分层设计:Repository接口抽象数据访问,DAO实现具体的数据库操作
  3. 错误处理:统一的错误码包装机制,便于上层进行错误分类和处理
  4. 事务支持:完整的事务支持,确保创建操作的原子性
  5. 性能优化:合理的索引设计和批量插入,确保创建操作的高效执行
  6. ID生成:支持插件及其关联工具的唯一ID生成操作

安全保障

  1. 权限验证:通过DeveloperID字段确保插件创建者的身份标识
  2. 数据验证:创建前验证插件数据的完整性和有效性
  3. 唯一性保证:通过ID生成器确保插件ID的唯一性
  4. 审计追踪:完整的时间戳记录,支持创建操作的审计和追踪
  5. 关联创建:确保创建插件时正确建立相关的工具数据关联

创建操作流程

  1. 接口调用:上层通过Repository接口调用CreateDraftPlugin方法
  2. ID生成:生成唯一的插件ID,避免ID冲突
  3. 事务开启:开启数据库事务确保操作的原子性
  4. 数据插入:将插件数据插入到plugin_draft表中
  5. 事务提交:所有创建操作成功后提交事务
  6. 错误处理:任何步骤失败都会回滚事务并返回错误

这种设计确保了创建插件操作的安全性、可靠性和高性能,为上层业务逻辑提供了坚实的数据访问基础。

数据模型与查询文件依赖关系
复制代码
数据库表结构 (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)

创建插件在数据访问层的完整流程

  1. 接口定义PluginRepository.CreateDraftPlugin(ctx, plugin) 定义创建操作契约
  2. DAO实现PluginDraftDAO.Create(ctx, plugin)PluginDraftDAO.CreateWithTX(tx, plugin) 实现具体创建逻辑
  3. ID生成:使用ID生成器为插件生成唯一标识
  4. 事务管理:使用事务确保插件数据的一致性创建
  5. 数据插入:将插件数据插入到plugin_draft表中
  6. 错误处理:包装创建异常为统一错误码
  7. 结果返回:创建成功返回插件ID,失败返回包装后的错误

设计优势

  1. 接口抽象:通过Repository接口实现数据访问的抽象化
  2. 代码生成:使用GORM Gen自动生成类型安全的查询代码
  3. 错误处理:统一的错误包装和处理机制
  4. 事务支持:通过context传递支持数据库事务
  5. 创建安全:通过ID生成器确保唯一性,避免ID冲突
  6. 性能优化:合理的索引设计和批量插入优化
  7. 可测试性:清晰的分层结构便于单元测试
  8. 可维护性:代码生成减少手工编写,降低维护成本
  9. 关联创建:支持插件及其关联数据的一致性创建

创建操作的技术特点

  • 数据插入:当前实现为数据插入,将新插件记录存储到数据库中
  • 事务操作:使用数据库事务确保插件数据的一致性创建
  • 索引优化:基于主键ID的插入操作,具有最佳的写入性能
  • 错误分类:通过错误码区分不同类型的创建异常
  • 审计支持:可通过数据库日志追踪创建操作的执行情况
  • 关联建立:确保创建插件时正确建立相关的数据关联
相关推荐
做运维的阿瑞8 小时前
从入门到精通:Django的深度探索之旅
开发语言·后端·python·系统架构·django
l1t14 小时前
在duckdb 1.4中编译和使用postgresql协议插件duckdb-pgwire
开发语言·数据库·c++·postgresql·插件·duckdb
做运维的阿瑞14 小时前
Python原生数据结构深度解析:从入门到精通
开发语言·数据结构·后端·python·系统架构
lypzcgf1 天前
Coze源码分析-资源库-编辑插件-后端源码-安全与错误处理
安全·插件·coze·coze源码分析·智能体平台·ai应用平台·agent平台
文火冰糖的硅基工坊1 天前
[创业之路-640]:通信行业供应链 - 通信网的发展趋势:IP化统一 、云网融合 、算网协同 、FMC(固定移动融合)、空天地一体化
网络·网络协议·tcp/ip·系统架构·通信·产业链
努力还债的学术吗喽1 天前
pycharm找不到Tencent Cloud CodeBuddy如何安装[windows]?pycharm插件市场找不到插件如何安装?
ide·windows·pycharm·插件·plugin·codebuddy
谱写秋天1 天前
软考-系统架构设计师*数据库基本概念详细讲解
数据库·系统架构·软考架构师
腾飞开源1 天前
01_系统架构设计
人工智能·系统架构·情感分析·工具调用·ai智能体·意图识别·智能路由
WPG大大通1 天前
从数据到模型:Label Studio 开源标注工具完整实施指南
经验分享·笔记·ai·系统架构·开源·大大通