当前位置： 首页 > article >正文

16 | 实现简洁架构的 Store 层

article 2025/3/15 20:53:27

提示：

  • 所有体系课见专栏：Go 项目开发极速入门实战课；
  • 欢迎加入 云原生 AI 实战 星球，12+ 高质量体系课、20+ 高质量实战项目助你在 AI 时代建立技术竞争力（聚焦于 Go、云原生、AI Infra）；
  • 本节课最终源码位于 fastgo 项目的 feature/s12 分支；
  • 更详细的课程版本见：Go 项目开发中级实战课：25 | 业务实现（2）：实现 Store 层代码

上一节课我们实现了 Store 层依赖的数据结构。本节课，我们就可以来实现 Store 层的代码。

Store 层代码用来跟数据库或者其他第三方微服务进行交互，实现 Store 层的思路如下：

  1. 定义一个 Store 层接口，用来定义 Store 层需要实现的方法。在 Go 开发中接口通常会被命名为 XXXer、XXXInterface、IXXX，其中 XXX 是接口的功能描述符。这里，将 Store 层的接口命名为 IStore。Biz 层的接口同样使用了该命名方式，命名为 IBiz，以保持整个项目接口命名方式的统一；
  2. 创建一个结构体，该结构体用来实现 Store 层的核心方法。通常会在该结构体中包含一个 *gorm.DB 对象，用于与数据库交互进行 CRUD 操作；
  3. 实现一个 NewStore 函数，用于创建 Store 层的实例；
  4. 为了方便直接通过 store 包引用 Store 层实例，我们可以设置一个包级别的 Store 实例。访问 Store 层的全局实例在项目开发中很少，也不建议使用。但在某些场景下还是挺好用的。这里，保留灵活的扩展能力；
  5. 为了避免实例被重复创建，通常需要使用 sync.Once 来确保实例只被初始化一次。

IStore 接口定义及实现

Store 层的代码实现位于 feature/s12 分支的 internal/apiserver/store/ 目录下。核心实现位于 internal/apiserver/store/store.go 文件中，代码如代码清单 16-1 所示：

代码清单 16-1：Store 层代码实现

package store

import (
    "context"
    "sync"

    "github.com/onexstack/onexstack/pkg/store/where"
    "gorm.io/gorm"
)

var (
    once sync.Once
    // 全局变量，方便其它包直接调用已初始化好的 datastore 实例.
    S *datastore
)

// IStore 定义了 Store 层需要实现的方法.
type IStore interface {
    // 返回 Store 层的 *gorm.DB 实例，在少数场景下会被用到.
    DB(ctx context.Context, wheres ...where.Where) *gorm.DB
    TX(ctx context.Context, fn func(ctx context.Context) error) error

    User() UserStore
    Post() PostStore
}

// transactionKey 用于在 context.Context 中存储事务上下文的键.
type transactionKey struct{}

// datastore 是 IStore 的具体实现.
type datastore struct {
    core *gorm.DB

    // 可以根据需要添加其他数据库实例
    // fake *gorm.DB
}

// 确保 datastore 实现了 IStore 接口.
var _ IStore = (*datastore)(nil)

// NewStore 创建一个 IStore 类型的实例.
func NewStore(db *gorm.DB) *datastore {
    // 确保 S 只被初始化一次
    once.Do(func() {
        S = &datastore{db}
    })

    return S
}

// DB 根据传入的条件（wheres）对数据库实例进行筛选.
// 如果未传入任何条件，则返回上下文中的数据库实例（事务实例或核心数据库实例）.
func (store *datastore) DB(ctx context.Context, wheres ...where.Where) *gorm.DB {
    db := store.core
    // 从上下文中提取事务实例
    if tx, ok := ctx.Value(transactionKey{}).(*gorm.DB); ok {
        db = tx
    }

    // 遍历所有传入的条件并逐一叠加到数据库查询对象上
    for _, whr := range wheres {
        db = whr.Where(db)
    }
    return db
}

// TX 返回一个新的事务实例.
// nolint: fatcontext
func (store *datastore) TX(ctx context.Context, fn func(ctx context.Context) error) error {
    return store.core.WithContext(ctx).Transaction(
        func(tx *gorm.DB) error {
            ctx = context.WithValue(ctx, transactionKey{}, tx)
            return fn(ctx)
        },
    )
}

// Users 返回一个实现了 UserStore 接口的实例.
func (store *datastore) User() UserStore {
    return newUserStore(store)
}

// Posts 返回一个实现了 PostStore 接口的实例.
func (store *datastore) Post() PostStore {
    return newPostStore(store)
}

DB 方法会尝试从 context 中获取事务实例，如果没有则直接返回 *gorm.DB 类型的实例。TX 方法则将*gorm.DB 类型的实例注入到 context 中。通过 DB 和 TX 在 Biz 层实现事务，在 Store 层执行事务。

IStore 接口中的 User() 方法和 Post() 方法，分别返回 User 资源的 Store 层方法和 Post 资源的 Store 层方法。这种设计方式其实是软件开发中的抽象工厂模式。通过使用不同的方法，创建不同的对象，对象之间相互独立，以此提高代码的可维护性。另外使用这种方法，也能有效提高资源接口的标准化。标准化的资源接口更易理解和使用。

代码清单 16-1 中，使用以下代码创建 *datastore 类型的实例：

// NewStore 创建一个 IStore 类型的实例.
func NewStore(db *gorm.DB) *datastore {
    // 确保 S 只被初始化一次
    once.Do(func() {
        S = &datastore{db}
    })

    return S
}

上述代码使用了 sync.Once 来确保实例只被初始化一次。实例创建完成后，将其赋值给包级变量 S，以便通过 store.S.User().Create() 来调用 Store 层接口。在 Go 的最佳实践中，建议尽量减少使用包级变量，因为包级变量的状态通常难以感知，会增加维护的复杂度。然而，这并非绝对规则，可以根据实际需要选择是否设置包级变量来简化开发。

UserStore 接口定义及实现

为了提高代码的可维护性，将 User 资源的 Store 代码单独存放在 internal/apiserver/store/user.go 文件中。UserStore 接口定义如下：

// UserStore 定义了 user 模块在 store 层所实现的方法.
type UserStore interface {
    Create(ctx context.Context, obj *model.UserM) error
    Update(ctx context.Context, obj *model.UserM) error
    Delete(ctx context.Context, opts *where.Options) error
    Get(ctx context.Context, opts *where.Options) (*model.UserM, error)
    List(ctx context.Context, opts *where.Options) (int64, []*model.UserM, error)

    UserExpansion
}

// UserExpansion 定义了用户操作的附加方法.
type UserExpansion interface{}

UserStore 接口中的方法分为两大类：资源标准 CURD 方法和扩展方法。通过将方法分类，可以进一步提高接口中方法的可维护性和代码的可读性。将方法分为标准方法和扩展方法的开发技巧，在 Kuberentes client-go 项目中被大量使用，fastgo 的设计思路正是来源于 client-go 的设计。

创建用户：Create 方法实现

userStore 结构体实现了 UserStore 接口。userStore 结构体的 Create 方法实现如下：

// userStore 是 UserStore 接口的实现.
type userStore struct {
    store *datastore
}

// 确保 userStore 实现了 UserStore 接口.
var _ UserStore = (*userStore)(nil)

// newUserStore 创建 userStore 的实例.
func newUserStore(store *datastore) *userStore {
    return &userStore{store}
}

// Create 插入一条用户记录.
func (s *userStore) Create(ctx context.Context, obj *model.UserM) error {
    if err := s.store.DB(ctx).Create(&obj).Error; err != nil {
        slog.Error("Failed to insert user into database", "err", err, "user", obj)
        return errorsx.ErrDBWrite.WithMessage(err.Error())
    }

    return nil
}

在 Create 方法中，会调用 s.store.DB(ctx) 方法尝试从 context 中获取事务实例，如果没有则直接返回*gorm.DB 类型的实例，并调用 *gorm.DB 提供的 Create 方法，完成数据库表记录的插入操作。

在 Create 方法中，如果插入失败，根据本课程第 13 节课的 fastgo 错误返回规范，直接返回了 errorsx.ErrorX 类型的错误 errno.ErrDBWrite，并设置了自定义错误消息：err.Error()。

在 Go 项目开发中，直接返回 gorm 包的错误，可能会暴露一些敏感信息，但绝大部分项目中，可以直接返回 gorm 包的报错信息。将 gorm 包的报错信息，直接在接口中返回，可以大幅提高接口失败时的排障效率。

删除用户：Delete 方法实现

userStore 结构体的 Delete 接口代码实现如下：

// Delete 根据条件删除用户记录.
func (s *userStore) Delete(ctx context.Context, opts *where.Options) error {
    err := s.store.DB(ctx, opts).Delete(new(model.UserM)).Error
    if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
        slog.Error("Failed to delete user from database", "err", err, "conditions", opts)
        return errorsx.ErrDBWrite.WithMessage(err.Error())
    }

    return nil
}

在 Delete 方法中，会判断删除记录时的错误类型是否是 gorm.ErrRecordNotFound，如果不是会返回自定义错误，如果是则返回删除成功，以此实现幂等删除。在 Go 项目开发中，删除行为在绝大部分项目中是一个幂等的操作。

查询用户列表：List 方法实现

userStore 结构体的 List 方法实现如下：

// List 返回用户列表和总数.
// nolint: nonamedreturns
func (s *userStore) List(ctx context.Context, opts *where.Options) (count int64, ret []*model.UserM, err error) {
    err = s.store.DB(ctx, opts).Order("id desc").Find(&ret).Offset(-1).Limit(-1).Count(&count).Error
    if err != nil {
        slog.Error("Failed to list users from database", "err", err, "conditions", opts)
        err = errorsx.ErrDBRead.WithMessage(err.Error())
    }
    return
}

在 List 方法中，会调用 s.store.DB(ctx, opts) 方法，根据 opts 入参来配置 *gorm.DB 实例的查询条件。查询的记录会按数据库 id 字段降序排列（从大到小的顺序）。将最新的记录放在返回列表的最前面可以提高返回数据的阅读体验，也是大部分平台的默认排序规则。

整个 UserStore 接口中的方法实现较为简洁，仅直接对数据库记录进行增删改查操作，并未封装任何业务逻辑。Post 资源的 Store 层代码实现与 User 资源保持一致，故本课程不再解读 Post 资源的 Store 层实现。

在 Go 项目开发中，不少开发者会在 Store 层封装业务代码，为了实现不同的查询条件，会在 Store 层封装很多查询类方法，例如：ListUser、ListUserByName、ListUserByID 等。这都会使 Store 层代码变得臃肿，难以维护。其实 Store 层只需要对数据库记录进行简单的增删改查即可。对插入数据或查询数据的处理可以放在业务逻辑层。对查询条件的定制，可以通过提供灵活的查询参数来实现。

where 查询条件实现

为了实现在查询数据库记录时，配置灵活的查询参数，fastgo 项目引用了 onexstack 项目的 where 包，包名为 github.com/onexstack/onexstack/pkg/store/where。整个 OneX 技术体系，都通过 where 包来定制化查询条件。

where 包更多的设计方法、思考及使用方法可以参考 云原生 AI 实战营 中 Go 项目开发中级实战课 的第 25 | 讲 业务实现（2）：实现 Store 层代码。


http://www.kler.cn/a/586014.html

相关文章：

  • Element Ui - 编辑时表单校验信息未清空问题处理
  • 作物移栽机器人的结构设计的介绍
  • Web后端开发之Maven
  • 2025年AI搜索引擎开源项目全景指南：从核心框架到生态工具
  • ARM64 架构地址空间分配深度解析
  • 79. 单词搜索:题解
  • sap关账+策略模式（避免大量if elseif）
  • SpringBoot注解驱动CRUD工具：spring-avue-plus
  • BOE(京东方)携手微博举办“微博影像年”年度影像大展 创新科技赋能专业影像惊艳呈现
  • 芯谷D8563TS：低功耗CMOS实时时钟/日历电路的优选方案
  • CentOS-7安装Docker（更新时间：2025-03-12）
  • markdown 转 word 工具 ‌Pandoc‌
  • 谷歌手机LEA流程
  • Vue 中的 transition 组件如何处理动画效果？
  • 世界坐标到UV纹理坐标的映射
  • PinnDE：基于物理信息神经网络的微分方程求解库
  • RabbitMQ入门：从安装到高级消息模式
  • axios配置全局接口超时时间
  • 某乎x-zse-96加密算法分析与还原
  • Leetcode3340：检查平衡字符串