Go RESTful API 项目模板介绍

0x00 引言

疫情期间学的东西比较杂（比如学习了如何在市场行情不好的时候还盲目加仓 ），没什么干货值得分享。不过考虑到很久都没有更新了，还是要强迫自己写一点东西，不然容易变懒。总之，多思考，多实践还是很重要。

今天主要是想把三个月前就放到 GitHub 上的 go-rest-api-starter 项目介绍下，目的有两个：

1. 分享下我们目前的工程实践；
2. 给 portal 增加点曝光度 。虽然我在 Go 语言中如何以优雅的姿势实现对象序列化 做过介绍，不过一直没有给过我们在真实环境中的具体用法，今天提供的示例也刚好可以帮助感兴趣的同学了解下它的用法。

0x01 为什么？

好的工程规范是在项目实践中不断踩坑总结出来的，期间我们也遇到各种写起来不够优雅的地方，自然就需要想办法解决这些问题。经过若干项目的实践，结合遇到的问题，也造了些轮子便于提升开发幸福度。沉淀和提炼的结果，便是一套可以沿袭的项目脚手架，集成了一些我们认为的「最佳实践」。

笔者相信不同的团队有不同的想法，但本质上都是更好的服务于业务。我们希望能够以一致、清晰的方式来编写代码，并且保证项目结构不被随意破坏，项目的可维护性大于一切。另外，对于业务框架，也不应该一味地排斥。合理地使用业务框架，既有利于简化业务代码编写，又有利于理解和维护。

0x02 是什么？

go-rest-api-starter 是一个完整的 RESTful API 项目（商品管理后台+前台接口，源自 aizoo 管理后台），演示了我们目前的工程实践是什么样的。当然，团队内部版本使用了一些非开源框架，不过同样的理念换成别的框架依然可行。所以，在该项目中，笔者将一些内部框架换成了开源框架，方便大家参考。

从这个项目中可以了解到什么？

1. 整体的项目结构，分层情况；
2. Model 层怎么编写，关联资源如何以属性方式暴露；
3. Schema 层怎么编写，表单校验逻辑放在什么位置；
4. 复杂业务逻辑如何在 Controller 层实现；
5. 如何保证 Handler 层整洁清晰；
6. portal 所扮演的角色，如何简化字段格式化逻辑。

首先来看下项目结构：

├── .env（环境变量配置，资源连接串等）
├── .env_unittest（跑单元测试使用的测试资源配置）
├── LICENSE
├── Makefile
├── README.md
├── bin
│   ├── starter-admin（面向管理后台的 RESTful API 服务器）
│   └── starter-web（面向客户端、PC 等前台的 RESTful API 服务器）
├── cmd（各个服务启动的入口）
│   ├── admin（管理后台）
│   │   └── main.go
│   ├── bee（离线异步任务）
│   │   └── main.go
│   ├── service（RPC 服务）
│   │   └── main.go
│   └── web（客户端、PC、小程序等前台）
│       └── main.go
├── go.mod（依赖包 go modules）
├── pkg
│   ├── admin（管理后台服务）
│   │   ├── handler
│   │   ├── router.go
│   │   ├── schema（和返回的 JSON 数据关联的资源结构体定义）
│   │   └── validator（通用的校验代码）
│   ├── config（资源配置）
│   │   ├── fixture.go
│   │   ├── init.go
│   │   └── mysql.go
│   ├── constant（常量、枚举定义）
│   │   ├── enum.go
│   │   ├── gen_enum.go
│   │   └── macro.go
│   ├── controller（复杂业务逻辑）
│   │   ├── company.go
│   │   ├── company_test.go
│   │   └── product.go
│   ├── job（异步离线任务业务逻辑）
│   │   └── after_product_created.go
│   ├── middleware（可复用的中间件）
│   │   └── cors.go
│   ├── model（Models，可能还会聚合来自 RPC 等数据源，数据模型抽象）
│   │   ├── company.go
│   │   ├── doc.go
│   │   ├── init.go
│   │   └── product.go
│   ├── util（工具集）
│   │   ├── orderby.go
│   │   ├── pic
│   │   ├── rest
│   │   ├── seqgen
│   │   └── toolkit
│   └── web（前台服务）
│       ├── handler
│       ├── router.go
│       └── schema
├── script（一些脚本文件）
│   └── 20200101
└── testdata（单元测试有关测试数据、表结构定义）
    ├── fixtures
    │   ├── company.yml
    │   ├── doc.yml
    │   └── product.yml
    └── schema.sql

0x03 说 Handler

我们希望 Handler 层的逻辑不要太过复杂，曾经在看某后台项目时，某 Handler 足足近百行代码，糅杂了大量的字段校验逻辑、业务逻辑、数据格式化逻辑等，极度啰嗦，难以修改和维护，这个是我们不太想要的。

理想情况下，Handler 层应该保证足够轻量，它就应该像是胶水，负责将 Model 层、Controller 层以及 Schema 层粘在一起。我们来看看下面的示例：

func GetProducts(c *rest.Context) (rest.Response, error) {
    // 1. 复杂逻辑下沉到 Controller 层实现
    products, total, err := controller.GetProducts(
        c.Query("title"),
        c.QueryWithFallback("order_by", "-created_at"),
        c.Offset(),
        c.Limit(),
    )

    // 2. Model -> Schema 渲染
    var schemas []schema.OutputProductSchema
    // 借助 portal.Only，可以在请求的时候指定只吐出需要的字段值
     err = portal.Dump(&schemas, products, portal.Only(strings.Split(c.QueryWithFallback("only", ""), ",")...))
    if err != nil {
        return nil, err
    }

    // 3. 返回结果
    return rest.NewPage(c, schemas, total), nil
}

func CreateProduct(c *rest.Context) (rest.Response, error) {
    // 1. 表单校验和处理
    var input schema.InputProductSchema
    err := c.BindJSON(&input)
    if err != nil {
        return nil, err
    }

    var product model.ProductModel
    err = portal.Dump(&product, input)
    if err != nil {
        return nil, err
    }

    // 2. 业务逻辑处理
    prodID, err := controller.CreateProduct(&product, &input)
    if err != nil {
        return nil, err
    }

    // 3. 返回处理结果
    return gin.H{"success": true, "product_id": cast.ToString(prodID)}, nil
}

总结来看，Handler 层无非执行如下几个步骤（Keep It Simple, Stupid）：

1. 输入参数校验和处理（实际逻辑要么封装在 Schema 层，要么在框架层解决）；
2. 业务逻辑处理（Controller 层负责）；
3. 结果返回。

0x04 讲 Schema 与 Model

这两个适合放在一起将，因为 Schema 的字段映射的正是对应的 Model 中相关字段。也许这里会有疑惑，为什么我们不直接在 Model 层，给某个 Field 加个 Tag json: field_name，直接序列化返回出去呢？为何非要生硬地写一个 Schema 结构体再做映射呢？

接下来将结合具体的场景来回答这个问题：

1. API 要求返回的字段类型和 Model 中实际类型不一致（如 model.ID 为 int 类型，但 API 要求返回 string 类型）；
2. 某些字段要求是可选返回字段（这时可以轻松地修改 Schema 中的字段为 *type 即可）。

总之，Model 层作为 Source of Truth，保持最原始的格式最好。Schema 层则根据具体的业务场景进行变动，对于不适配的场景，自定义 format 方法完成转换即可。这样可以将改动只聚焦在较小的范围，避免到处修改类型，想想也心累。

最后要提的一点是 Model 的关联资源，我们推荐的写法如下：

type ProductModel struct {
    ID        int64
    CompanyID int64
    // ... other fields ignored
}

// Company 返回商品关联的公司（来源于别的表）
func (pd *ProductModel) Company() (*CompanyModel, error) {
    var company CompanyModel
    err := DB.Where("id = ?", pd.CompanyID).Find(&company).Error
    if err != nil {
        if gorm.IsRecordNotFoundError(err) {
            return nil, nil
        }
        return nil, errors.WithStack(err)
    }
    return &company, nil
}

// Rate 返回商品关联的评分（来源于 RPC 调用）
func (pd *ProductModel) Rate() (float64, error) {
    return rpc.GetProductRate(pd.ID)
}

这样在 Schema 层，我们只需要声明需要映射的字段，在经过 portal.Dump 时，框架会自动完成相关字段映射，并将返回的值填充到对应的 Schema 字段中：

type OutputCompanySchema struct {
    ID        string           `json:"id"`
    // ...
}

type OutputProductSchema struct {
    ID            *string               `json:"id,omitempty"`
    // ...
    Company       *OutputCompanySchema  `json:"company,omitempty" portal:"nested;async"`
    CreatedAt     *field.Timestamp      `json:"created_at,omitempty"`
}

var output OutputProductSchema
portal.Dump(&output, product)

// 此时将 output json 序列化，就是想要得到的结果

0x05 碎碎念

最近几天在尝试重构某个项目的某个巨长的函数（接近 250 行，代码就不贴了，怕被打 ），每次修改它的时候心态都要崩。但说起来，它也没有多么复杂的业务逻辑，只是产品线类型较多，糅杂了资源获取逻辑、字段格式化逻辑等等。严格来说，完全可以使用上述的 Model & Schema 分层思路进行重构，但是该函数做了些优化：

1. 使用 batch_get_resource 接口替代 get_resource 接口；
2. 并发获取多个产品线的章节信息等。

因为这种优化的引入，会导致上述写法上存在一些不太优雅的地方。接下来举个栗子能够更好地说明现在遇到的问题：

先看看常规的 StudentModel & StudentSchema 定义：

type StudentModel struct {
    MemberID int64
}

// Member 返回关联的账号详情
func (s *StudentModel) Member(ctx context.Member) *rpc.Member {
    // 注意，这里使用的是单次调用，而非批量调用
    return rpc.GetMemberByID(s.MemberID)
}

type MemberSchema struct { /*...*/ }

type StudentSchema struct {
    Member *MemberSchema `portal: nested`
}

假设一页需要获取 20 个学生信息，portal 序列化时，会默认启动 20 个 goroutine 分别处理 20 个 StudentSchema 的渲染。这样的话，具体到 StudentModel.Member 获取时，就会产生 20 个并发的 GetMemberByID 请求，相对串行执行，这种方式自然可以提高速度。但是代价也很明显，产生的请求较多。对于一些后台项目这样做还好，但是对于 C 端接口，如果请求量较高，那请求放大会比较严重。

students := DBGetStudents(20)

var output []StudentSchema
portal.Dump(&output, students)

假设上游为我们提供了类似 func BatchGetMemberByID(memberIDs []int64) map[int64]*Member 方法，那么我么可以通过批量调用的方式解决上面提到的问题。不过，此时我们需要同时修改原有的 Model 层和 Schema 层如下：

type StudentModel struct {
    MemberID int64
}

type StudentSchema struct {
    Member *MemberSchema `portal: nested`
}

func (s *StudentSchema) GetMember(ctx context.Context, student *StudentModel) *rpc.Member {
    // 假设外层批量调用结果放在 ctx 中传入
    v := ctx.Value("members").(map[int64]*rpc.Member)
    return v[student.MemberID]
}

然后在 Handler 层，我们需要手动调用 BatchGetMemberByID 接口：

students := DBGetStudents(20)

// 收集 member_ids
memberIDs := make([]int64, len(students))
for i, s := range students {
    memberIDs[i] = s.MemberID
}

// 批量调用一次
members := rpc.BatchGetMemberByID(memberIDs)
ctx = context.WithValue("members", members)

var output []StudentSchema
portal.DumpWithContext(ctx, &output, students)

嗯，似乎看起来并没有多么繁琐嘛。不过这样的法会容易导致 Handler 层膨胀，试想再加点别的关联资源获取呢？那各种 BatchGetShit 就怼进去了。

所以，我们究竟怎么才能做到原有的 Model 层依然保持简单的 rpc.GetResourceByID 这种简单的调用方式；Schema 层也不用做侵入式修改；Handler 层更不用忍受可能导致的代码膨胀问题呢？也许我们可以对 rpc.GetResourceByID 做点包装，在底层框架上，自动支持请求合并；而对于上层调用方无感知。

熟悉 HTTP/2 的同学应该也会了解到其中一个特色是多路复用，避免每次新的请求都要进行 TCP+TLS 握手。那么如果我们能够做到在底层将上层的 rpc.GetResourceByID 自动合并为 rpc.BatchGetResourceByID，也能很大程度上提高请求效率，减少上游服务的请求压力。虽然相对于并发 20 个 rpc.GetResourceByID 请求，自动合并技术可能因为优化不到位或者策略上的问题，响应时间可能稍长，但是相对于串行调用，速度理论上会有很大提升。

image

关于这个请求合并的策略如何实现呢？可以想象下 rpc.BatchGetResourceByID 就像一辆往返于两地的公共汽车，假设它有两个关键属性：

1. 车上乘客一旦坐满立刻出发（不许加塞，咱们要合法经营）；
2. 到达一定超时时间立刻出发；
3. 到达目的地后，还要在返程时将同一批乘客尽可能全部带回来（假设乘客们要么买到了想要的礼物 result 或者像笔者一样比较穷就什么也没买 error）。

基于这样的假设，尝试使用 Go 语言实现了一个简单的 Demo，感兴趣的同学可以前往 rpcx 查看。尝试引入了一个 Proxy 层，由 Proxy 层收集业务方的调用参数，并批量发起调用，最后将结果分派给业务方。当然，目前 Proxy 是以一个单独的 goroutine 部署；理想情况下，如果能用 sidecar 方式部署，甚至可以做到语言无关。

func getMembersAutoAgg(ctx context.Context, max int) {
    var wg sync.WaitGroup
    for i := 0; i <= max; i++ {
        wg.Add(1)
        // 底层自动将并发单次调用转换成批量调用
         go func(n int) {
            r, err := rsdk.GetMember(ctx, int64(n)+1)
            _, _ = r, err
            wg.Done()
        }(i)
    }
    wg.Wait()
}

当然，想要在生产环境搞事情，还有很长的路要走。比如 Proxy 监控怎么做？是否存在单点问题？是否会成为接口调用瓶颈？如何与公司现有的 RPC 框架结合？收益是否真的达到预期？

0x06 总结

以上分享了一些关于工程实践方面的思考，欢迎指正，有什么好的想法也欢迎留言交流~