单体最佳实践的由来
- 对于很多初创公司来说，业务的早期我们更应该关注于业务价值的交付，并且此时用户体量也很小，
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 的语法还是比较能自解释的，含义如下：
-
syntax = “v1”表示这是zero-api的v1语法 -
type DownloadRequest定义了Download的请求格式 -
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)
}
解释如下：
-
syntax = “v1”表示这是zero-api的v1语法 -
type UploadResponse定义了Upload的返回格式 -
service file-api定义了Upload的请求路由
问题来了
Download 和 Upload 服务我们都定义好了，那怎么才能放到一个服务里给用户提供服务呢？
不知道细心的你有没注意到一些细节：
- 不管是
Download还是Upload我们在request和response数据定义的时候都加了前缀，并没有直接使用诸如Request或Response这样的 - 我们在
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 服务都导入进来了。但其中有几点需要注意的：
- 定义的结构体不能重名
- 所有文件里包含的
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 }
完整代码：https://github.com/zeromicro/zero-examples/tree/main/monolithic
我们可以通过启动 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 开发单体服务的完整流程归纳如下：
- 定义各个子模块的
API文件，比如：download.api和upload.api - 定义总的
API文件，比如：file.api。用来import步骤一定义的各个子模块的API文件 - 通过
goctl api go命令生成单体服务框架代码 - 增加和调整配置，实现对应的子模块的业务逻辑
另外，goctl 可以根据 SQL 一键生成 CRUD 以及 cache 代码，可以帮助大家更快速的开发单体服务。
项目地址
https://github.com/zeromicro/go-zero
欢迎使用 go-zero 并 star 支持我们！
微信交流群
关注『微服务实践』公众号并点击 交流群 获取社区群二维码。
