Go 單體服務開發最佳實踐

kevinwan發表於2022-06-03
Go

單體最佳實踐的由來

  • 對於很多初創公司來說，業務的早期我們更應該關注於業務價值的交付，並且此時使用者體量也很小，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
}

完整程式碼：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 開發單體服務的完整流程歸納如下：

  1. 定義各個子模組的 API 檔案，比如：download.api 和 upload.api
  2. 定義總的 API 檔案，比如：file.api。用來 import 步驟一定義的各個子模組的 API 檔案
  3. 通過 goctl api go 命令生成單體服務框架程式碼
  4. 增加和調整配置，實現對應的子模組的業務邏輯

另外，goctl 可以根據 SQL 一鍵生成 CRUD 以及 cache 程式碼，可以幫助大家更快速的開發單體服務。

專案地址

https://github.com/zeromicro/go-zero

歡迎使用 go-zero 並 star 支援我們！

微信交流群

關注『微服務實踐』公眾號並點選 交流群 獲取社群群二維碼。

如果你有 go-zero 的使用心得文章，或者原始碼學習筆記，歡迎通過公眾號聯絡投稿！

相關文章