單體最佳實踐的由來
- 對於很多初創公司來說，業務的早期我們更應該關注於業務價值的交付，並且此時用戶體量也很小，
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同名，去掉了後綴-apiinternal/config目錄：服務的配置定義internal/handler目錄：API文件裏定義的路由對應的handler實現internal/logic目錄：用來放每個路由對應的業務處理邏輯，之所以區分handler和logic是爲了讓業務處理部分儘可能減少依賴，把HTTP requests和邏輯處理代碼隔離開，便於後續按需拆分成RPC serviceinternal/svc目錄：用來定義業務邏輯處理的依賴，我們可以在main裏面創建依賴的資源，然後通過ServiceContext傳遞給handler和logicinternal/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 支持我們！
微信交流羣
關注『微服務實踐』公衆號並點擊 交流羣 獲取社區羣二維碼。