17 | 实现简洁架构的 Biz 层

提示：

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

Biz 层依赖 Store 层，所以实现了 Store 层代码之后，便可以实现 Biz 层代码。Biz 层代码，主要用来实现系统中 REST 资源的各类业务操作，例如用户资源的增删改查等。

整个 fastgo 项目的设计较为规范，规范化的项目设计带来的优点之一是开发方式的一致性和开发效率的提升。fastgo 项目 Biz 层的开发方式与 Store 层的开发方式保持一致。

API 接口定义

在开发 Biz 层代码之前，需要先定义好 API 接口的请求入参和返回参数。为此，新建了 pkg/api/apiserver/v1/post.go 文件和 pkg/api/apiserver/v1/user.go 文件，分别保存了用户接口和博客接口的请求入参和返回参数。

因为请求入参和返回参数（例如 CreateUserRequest 和 CreateUserResponse）会提供给接口调用方（客户端），所以需要将接口定义保存在 pkg/api 目录下。另外，考虑到未来 fastgo 可能会加入多个服务，每个服务都有自己的 API 定义，fastgo 项目选择了将每个服务的 API 定义保存在独立的服务目录下，例如 pkg/api/apiserver。

考虑到未来 API 接口的版本升级，fastgo 项目将接口进行了版本化处理，v1 版本的接口保存在 pkg/api/apiserver/v1 目录下，v2 版本的接口保存在 pkg/api/apiserver/v2 目录下。

IBiz 接口定义及实现

Biz 层代码保存 internal/apiserver/biz/biz.go 文件中，接口名为 IBiz，定义如下：

// IBiz 定义了业务层需要实现的方法.
type IBiz interface {
    // 获取用户业务接口.
    UserV1() userv1.UserBiz
    // 获取帖子业务接口.
    PostV1() postv1.PostBiz
    // 获取帖子业务接口（V2版本）.
    // PostV2() post.PostBiz
}

IBiz 接口包含了 User 资源和 Post 资源 v1 版本的接口，通过抽象工厂设计模式返回对应资源的接口。在 Go 项目开发中，业务层代码的代码量通常最大、变动最频繁，并且随着项目的迭代，可能会出现不兼容的变更。

这时需要对外暴露 v2 版本的 API 接口。因此，为了提高代码的可维护性并保留未来的扩展能力，Biz 层代码的存放结构如下：

internal/apiserver/biz/
├── biz.go
├── v1/ # v1 版本代码实现
│   ├── post/ # 提高代码可维护性，不同资源的代码实现分别存放在不同的目录中
│   │   └── post.go
│   └── user/
│       └── user.go
└── v2/ # 保留扩展能力：v2 代码保存目录

上述代码，将不同版本的代码保存在不同的版本化目录中，不同 REST 资源的业务逻辑实现保存在跟资源对应的目录中。不同资源的业务逻辑代码均在其对应的目录中实现，可以在目录级别隔离不同资源的代码实现，有利于提高代码的稳定性，并降低维护的复杂度。

Biz 层依赖于 Store 层的实现，所以在创建 IBiz 实例时，需要传入 IStore 类型的实例，IBiz 实例由 NewBiz 函数创建：

// biz 是 IBiz 的一个具体实现.
type biz struct {
    store store.IStore
}

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

// NewBiz 创建一个 IBiz 类型的实例.
func NewBiz(store store.IStore) *biz {
    return &biz{store: store}
}

IBiz 的实现跟 IStore 的实现是保持一致，其他代码，本节不再详解。

UserBiz 接口定义及实现

User 资源的 Biz 层代码实现位于 internal/apiserver/biz/v1/user/user.go 文件中，其接口定义为 UserBiz，代码如下：

// UserBiz 定义处理用户请求所需的方法.
type UserBiz interface {
    Create(ctx context.Context, rq *apiv1.CreateUserRequest) (*apiv1.CreateUserResponse, error)
    Update(ctx context.Context, rq *apiv1.UpdateUserRequest) (*apiv1.UpdateUserResponse, error)
    Delete(ctx context.Context, rq *apiv1.DeleteUserRequest) (*apiv1.DeleteUserResponse, error)
    Get(ctx context.Context, rq *apiv1.GetUserRequest) (*apiv1.GetUserResponse, error)
    List(ctx context.Context, rq *apiv1.ListUserRequest) (*apiv1.ListUserResponse, error)

    UserExpansion
}

// UserExpansion 定义用户操作的扩展方法.
type UserExpansion interface {
}

UserBiz 接口中的方法，同样也分为了两大类：标准资源 CURD 接口和扩展接口，扩展接口中实现了用户登录、Token 刷新、密码修改等方法。实现 UserBiz 接口的 Go 结构体是 *userBiz。

创建用户：Create 方法实现

userBiz 结构体的 Create 方法实现如下：

// Create 实现 UserBiz 接口中的 Create 方法.
func (b *userBiz) Create(ctx context.Context, rq *apiv1.CreateUserRequest) (*apiv1.CreateUserResponse, error) {
    var userM model.User
    _ = copier.Copy(&userM, rq)

    if err := b.store.User().Create(ctx, &userM); err != nil {
        return nil, err
    }

    return &apiv1.CreateUserResponse{UserID: userM.UserID}, nil
}

为了提高开发效率，减少不必要的代码量，Create 方法使用了 [github.com/jinzhu/copier](https://github.com/jinzhu/copier) 的 Copy 函数给目标结构体变量 userM 赋值。

在 Create 方法中，通过 b.store.User().Create(ctx, &userM) 方法调用，将数据保存在数据库中。

在 Go 项目开发中，数据库禁止保存明文密码。用户密码在入库前需要进行加密处理。为了加密明文密码字符串，fastgo 引入了 github.com/onexstack/onexstack/pkg/auth 包，auth 包中的 Encrypt 函数可以用来加密一个明文密码字符串。

因为在入库前都需要对明文密码进行加密，所以，很自然的想到可以通过实现 GORM 框架的 BeforeCreate 钩子来实现。修改 internal/apiserver/model/hook.go 文件，添加以下代码：

import (
    ...
    "github.com/onexstack/onexstack/pkg/auth"
)

// BeforeCreate 在创建数据库记录之前加密明文密码.
func (m *User) BeforeCreate(tx *gorm.DB) error {
    // Encrypt the user password.
    var err error
    m.Password, err = auth.Encrypt(m.Password)
    if err != nil {
        return err
    }

    return nil
}

更新用户：Update 方法实现

userBiz 结构体的 Update 方法实现如下：

// Update 实现 UserBiz 接口中的 Update 方法.
func (b *userBiz) Update(ctx context.Context, rq *apiv1.UpdateUserRequest) (*apiv1.UpdateUserResponse, error) {
    userM, err := b.store.User().Get(ctx, where.T(ctx))
    if err != nil {
        return nil, err
    }

    if rq.Username != nil {
        userM.Username = *rq.Username
    }
    if rq.Email != nil {
        userM.Email = *rq.Email
    }
    if rq.Nickname != nil {
        userM.Nickname = *rq.Nickname
    }
    if rq.Phone != nil {
        userM.Phone = *rq.Phone
    }

    if err := b.store.User().Update(ctx, userM); err != nil {
        return nil, err
    }

    return &apiv1.UpdateUserResponse{}, nil
}

在更新用户时，根据是否传入待更新的字段来判断是否更新该字段。这样的设计方式，可以通过一个更新接口实现字段的选择性更新。

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

userBiz 结构体的 List 方法实现如下述代码所示：

// List 实现 UserBiz 接口中的 List 方法.
func (b *userBiz) List(ctx context.Context, rq *apiv1.ListUserRequest) (*apiv1.ListUserResponse, error) {
    whr := where.P(int(rq.Offset), int(rq.Limit))
    count, userList, err := b.store.User().List(ctx, whr)
    if err != nil {
        return nil, err
    }

    var m sync.Map
    eg, ctx := errgroup.WithContext(ctx)

    // 设置最大并发数量为常量 MaxConcurrency
    eg.SetLimit(known.MaxErrGroupConcurrency)

    // 使用 goroutine 提高接口性能
    for _, user := range userList {
        eg.Go(func() error {
            select {
                case <-ctx.Done():
                return nil
                default:
                count, _, err := b.store.Post().List(ctx, where.T(ctx))
                if err != nil {
                    return err
                }

                converted := conversion.UserodelToUserV1(user)
                converted.PostCount = count
                m.Store(user.ID, converted)

                return nil
            }
        })
    }

    if err := eg.Wait(); err != nil {
        slog.ErrorContext(ctx, "Failed to wait all function calls returned", "err", err)
        return nil, err
    }

    users := make([]*apiv1.User, 0, len(userList))
    for _, item := range userList {
        user, _ := m.Load(item.ID)
        users = append(users, user.(*apiv1.User))
    }

    slog.DebugContext(ctx, "Get users from backend storage", "count", len(users))

    return &apiv1.ListUserResponse{TotalCount: count, Users: users}, nil
}

List 方法会查询所有的用户列表，并统计用户所属的博客数，这种遍历多个列表，并且针对列表中每个元素都有耗时处理逻辑的代码，可能会导致 List 方法执行时间较久。为了提高 List 方法的性能，List 方法中使用了 errgroup 包，并发查询每个用户的博客数。

在上述代码中 eg.SetLimit 方法调用的作用是限制程序中同时运行的 Go 协程数量，以避免过多协程并发任务导致的系统资源过载（如高 CPU 和内存占用或高 I/O 消耗）。通过 eg.Go 启动的 goroutine 会按照 SetLimit 的限制规则执行。当已经有 MaxErrGroupConcurrency 个任务在运行时，新任务会阻塞，直到某个正在运行的任务完成。

因为会并发处理 userList 列表中的每个元素，所以需要一个并发安全的数据类型，保存处理后的数据。Go 标准库提供了 sync.Map 数据类型，该类型是并发安全的，可以直接在 Go 协程中使用 sync.Map 的 Store 方法添加 key-value 对。在上述代码中，使用 m.Store 保存了 *apiv1.User 类型的数据。

Store 层返回的数据类型为 *model.UserM，需要转换为 Biz 层使用的数据类型 *apiv1.User。*model.UserM 和 *apiv1.User 数据类型之间的相互转换，在 Biz 层经常会发生，为了提高代码的可维护性，将这类转换实现统一保存在 internal/apiserver/pkg/conversion 目录下的 conversion 包中。

Store 层返回的用户列表是降序排列的，为了保证 List 返回的列表也是降序排列的，上述代码的最后，使用以下代码段重新排列了 sync.Map 类型变量 m 中保存的数据：

for _, item := range userList {
    user, _ := m.Load(item.ID)
    users = append(users, user.(*apiv1.User))
}