单体最佳实践的由来

• 对于很多初创公司来说，业务的早期我们更应该关注于业务价值的交付，并且此时用户体量也很小，​​QPS​​ 也非常低，我们应该使用更简单的技术架构来加速业务价值的交付，此时单体的优势就体现出来了。
• 正如我直播分享时经常提到，我们在使用单体快速交付业务价值的同时，也需要为业务的发展预留可能性，我们可以在单体里面清晰的拆分业务模块。
• ​​go-zero​​ 社区里也有很多小伙伴在问，咱们单体开发的最佳实践应该是怎样的。

而 ​​go-zero​​ 作为一个被广泛使用的渐进式微服务框架来说，也是我在多个大型项目完整发展过程中沉淀出来的，自然我们也充分考虑了单体服务开发的场景。

如图所示的使用 ​​go-zero​​​ 的单体架构，也可以支撑很大体量的业务规模，其中 ​​Service​​​ 是单体服务的多个 ​​Pod​​。

我就通过本文详细跟大家分享一下如何使用 ​​go-zero​​ 快速开发一个有多个模块的单体服务。

单体示例

我们用一个上传下载的单体服务来讲解 ​​go-zero​​ 单体服务开发的最佳实践，为啥用这么个示例呢？

• ​​go-zero​​​ 社区里经常有同学会问上传文件怎么定义 ​​API​​ 文件，然后用 ​​goctl​​ 自动生成。初见此类问题会觉得比较奇怪，为啥不用 ​​OSS​​ 之类的服务呢？发现很多场景是用户需要上传一个excel，然后服务端解析完也就丢弃此文件了。一是文件较小，二是用户量也不大，就不用那么复杂的通过 ​​OSS​​ 来绕一圈了，我觉得也挺合理的。
• ​​go-zero​​​ 社区也有同学问下载文件怎么通过定义一个 ​​API​​ 文件然后 ​​goctl​​ 自动生成。此类问题之所以通过 Go 来做，问下来一般两个原因，一是业务刚开始，能简单点布一个服务搞定就一个吧；二是希望能吃上 ​​go-zero​​ 的内置 ​​JWT​​ 自动鉴权。

仅以此为示例，无需深入探讨上传下载是否应该通过 ​​Go​​​ 来实现。那么接下来我们就看看我们怎么通过 ​​go-zero​​ 来解决这么一个单体服务，我们称之为文件（file）服务。架构如下图：

单体实现

​​API​​ 定义

使用过 ​​go-zero​​​ 的同学都知道，我们提供了一个 ​​API​​​ 格式的文件来描述 ​​RESTful API​​​，然后可以通过 ​​goctl​​​ 一键生成对应的代码，我们只需要在 ​​logic​​​ 文件里填写对应的业务逻辑即可。我们就来看看 ​​download​​​ 和 ​​upload​​​ 服务怎么定义 ​​API​​.

​​Download​​ 服务定义

示例需求如下：

• 通过​​/static/<filename>​​​ 路径下载名为​​<filename>​​ 的文件
• 直接返回文件内容即可

我们在 ​​api​​​ 目录下创建一个名为 ​​download.api​​ 的文件，内容如下：

syntax = "v1"

type DownloadRequest {
  File string `path:"file"`
}

service file-api {
  @handler DownloadHandler
  get /static/:file(DownloadRequest)
}

​​zero-api​​ 的语法还是比较能自解释的，含义如下：

1. ​​syntax = “v1”​​​ 表示这是​​zero-api​​​ 的​​v1​​ 语法
2. ​​type DownloadRequest​​​ 定义了​​Download​​ 的请求格式
3. ​​service file-api​​​ 定义了​​Download​​ 的请求路由

​​Upload​​ 服务定义

示例需求如下：

• 通过​​/upload​​ 路径上传文件
• 通过​​json​​​ 返回上传状态，其中的​​code​​​ 可用于表达比​​HTTP code​​ 更丰富的场景

我们在 ​​api​​​ 目录下创建一个名为 ​​upload.api​​ 的文件，内容如下：

syntax = "v1"

type UploadResponse {
  Code int `json:"code"`
}

service file-api {
  @handler UploadHandler
  post /upload returns (UploadResponse)
}

解释如下：

1. ​​syntax = “v1”​​​ 表示这是​​zero-api​​​ 的​​v1​​ 语法
2. ​​type UploadResponse​​​ 定义了​​Upload​​ 的返回格式
3. ​​service file-api​​​ 定义了​​Upload​​ 的请求路由

问题来了

​​Download​​​ 和 ​​Upload​​ 服务我们都定义好了，那怎么才能放到一个服务里给用户提供服务呢？

不知道细心的你有没注意到一些细节：

1. 不管是​​Download​​​ 还是​​Upload​​​ 我们在​​request​​​ 和​​response​​​ 数据定义的时候都加了前缀，并没有直接使用诸如​​Request​​​ 或​​Response​​ 这样的
2. 我们在​​download.api​​​ 和​​upload.api​​​ 里面定义​​service​​​ 的时候都是用的​​file-api​​​ 这个​​service name​​​，并没有分别用​​download-api​​​ 和​​upload-api​​

这么做的目的其实就是为了我们接下来把这两个服务放到同一个单体里自动生成对应的 ​​Go​​​ 代码。让我们来看看怎么把 ​​Download​​​ 和 ​​Upload​​ 合并起来~

定义单体服务接口

出于简单考虑，​​goctl​​​ 只支持接受单一 ​​API​​​ 文件作为参数，同时接受多个 ​​API​​ 文件的问题不在此讨论，如有简单高效的方案，后续可能支持。

我们在 ​​api​​​ 目录下创建一个新的 ​​file.api​​ 的文件，内容如下：

syntax = "v1"

import "download.api"
import "upload.api"

这样我们就像 ​​C/C++​​​ 的 ​​#include​​​ 一样把 ​​Download​​​ 和 ​​Upload​​ 服务都导入进来了。但其中有几点需要注意的：

1. 定义的结构体不能重名
2. 所有文件里包含的​​service name​​ 必须是同一个

最外层的 ​​API​​​ 文件也可以包含同一个 ​​service​​​ 的部分定义，但我们推荐保持对称，除非这些 ​​API​​​ 确实属于父层级，比如跟 ​​Download​​​ 和 ​​Upload​​​ 属于同一个逻辑层次，那么就不应该放到 ​​file.api​​ 里面定义。

至此，我们的文件结构如下：

.
└── api
    ├── download.api
    ├── file.api
    └── upload.api

生成单体服务

既然已经有了 ​​API​​​ 接口定义，那么对于 ​​go-zero​​​ 来说，接下来的事情就很简单直接了（当然，定义 ​​API​​​ 也挺简单的，不是吗？），让我们来使用 ​​goctl​​ 生成单体服务代码。

$ goctl api go -api api/file.api -dir .

我们来看看生成后的文件结构：

.
├── api
│   ├── download.api
│   ├── file.api
│   └── upload.api
├── etc
│   └── file-api.yaml
├── file.go
├── go.mod
├── go.sum
└── internal
    ├── config
    │   └── config.go
    ├── handler
    │   ├── downloadhandler.go
    │   ├── routes.go
    │   └── uploadhandler.go
    ├── logic
    │   ├── downloadlogic.go
    │   └── uploadlogic.go
    ├── svc
    │   └── servicecontext.go
    └── types
        └── types.go

我们来按目录解释一下项目代码的构成：

• ​​api​​​ 目录：我们前面定义的​​API​​ 接口描述文件，无需多言
• ​​etc​​​ 目录：这个是用来放置​​yaml​​​ 配置文件的，所有的配置项都可以写在​​file-api.yaml​​ 文件里
• ​​file.go​​​：​​main​​​ 函数所在文件，文件名跟​​service​​​ 同名，去掉了后缀​​-api​​
• ​​internal/config​​ 目录：服务的配置定义
• ​​internal/handler​​​ 目录：​​API​​​ 文件里定义的路由对应的​​handler​​ 实现
• ​​internal/logic​​​ 目录：用来放每个路由对应的业务处理逻辑，之所以区分​​handler​​​ 和​​logic​​​ 是为了让业务处理部分尽可能减少依赖，把​​HTTP requests​​​ 和逻辑处理代码隔离开，便于后续按需拆分成​​RPC service​​
• ​​internal/svc​​​ 目录：用来定义业务逻辑处理的依赖，我们可以在​​main​​​ 里面创建依赖的资源，然后通过​​ServiceContext​​​ 传递给​​handler​​​ 和​​logic​​
• ​​internal/types​​​ 目录：定义了​​API​​ 请求和返回数据结构

咱们什么也不改，先来跑一下看看效果。

$ go run file.go -f etc/file-api.yaml
Starting server at 0.0.0.0:8888...

实现业务逻辑

接下来我们需要实现相关的业务逻辑，但是这里的逻辑其实只是一个演示用途，无需过于关注实现细节，只需要理解我们应该把业务逻辑写在 ​​logic​​ 层即可。

这里一共做了以下几件事：

• 增加配置项里的​​Path​​ 设置，用来放置上传文件，默认值我写了当前目录，因为是示例，如下：

type Config struct {
  rest.RestConf
  // 新增
  Path string `json:",default=."`
}

• 调整了请求体的大小限制，如下：

Name: file-api
Host: localhost
Port: 8888
# 新增
MaxBytes: 1073741824

• 由于​​Download​​ 需要写文件给客户端，所以我们把 ​​ResponseWriter​​ 当成 ​​io.Writer​​ 传递给了 ​​logic​​ 层，修改后的代码如下：

func (l *DownloadLogic) Download(req *types.DownloadRequest) error {
  logx.Infof("download %s", req.File)
  body, err := ioutil.ReadFile(req.File)
  if err != nil {
    return err
  }

  n, err := l.writer.Write(body)
  if err != nil {
    return err
  }

  if n < len(body) {
    return io.ErrClosedPipe
  }

  return nil
}

• 由于​​Upload​​ 需要读取用户上传的文件，所以我们把 ​​http.Request​​ 传递给了 ​​logic​​ 层，修改后的代码如下：

func (l *UploadLogic) Upload() (resp *types.UploadResponse, err error) {
  l.r.ParseMultipartForm(maxFileSize)
  file, handler, err := l.r.FormFile("myFile")
  if err != nil {
    return nil, err
  }
  defer file.Close()

  logx.Infof("upload file: %+v, file size: %d, MIME header: %+v",
    handler.Filename, handler.Size, handler.Header)

  tempFile, err := os.Create(path.Join(l.svcCtx.Config.Path, handler.Filename))
  if err != nil {
    return nil, err
  }
  defer tempFile.Close()
  io.Copy(tempFile, file)

  return &types.UploadResponse{
    Code: 0,
  }, nil
}

完整代码：github.com/zeromicro/z…

我们可以通过启动 ​​file​​ 单体服务：

$ go run file.go -f etc/file-api.yaml

可以通过 ​​curl​​​ 来验证 ​​Download​​ 服务：

$ curl -i "http://localhost:8888/static/file.go"
HTTP/1.1 200 OK
Traceparent: 00-831431c47d162b4decfb6b30fb232556-dd3b383feb1f13a9-00
Date: Mon, 25 Apr 2022 01:50:58 GMT
Content-Length: 584
Content-Type: text/plain; charset=utf-8

...

示例仓库里包含了 ​​upload.html​​​，浏览器打开这个文件就可以尝试 ​​Upload​​ 服务了。

单体开发的总结

我把用 ​​go-zero​​ 开发单体服务的完整流程归纳如下：

1. 定义各个子模块的​​API​​​ 文件，比如：​​download.api​​​ 和​​upload.api​​
2. 定义总的​​API​​​ 文件，比如：​​file.api​​​。用来​​import​​​ 步骤一定义的各个子模块的​​API​​ 文件
3. 通过​​goctl api go​​ 命令生成单体服务框架代码
4. 增加和调整配置，实现对应的子模块的业务逻辑

另外，​​goctl​​​ 可以根据 ​​SQL​​​ 一键生成 ​​CRUD​​​ 以及 ​​cache​​ 代码，可以帮助大家更快速的开发单体服务。

项目地址

github.com/zeromicro/g…

欢迎使用 ​​go-zero​​ 并 star 支持我们！

关注『微服务实践』公众号