Go 服務工作規範
這些慣例確保分層式 Go 服務在並發與多租戶環境下保持正確性。請先閱讀所處的套件——一個一致應用的本地模式優於此處的任何規則。
寫程式碼之前
檢查工具鏈。go.mod 決定了可用的標準函式庫與語言功能,同一工作區內的服務可能使用不同版本。迴圈變數捕獲在 Go 1.22 以下是真正的錯誤,在以上則不是問題;errors.Join、slices 與 maps 需要 Go 1.21。請直接讀取版本號,不要假設為最新。
然後找出負責你即將修改決策的層。處理器負責將傳輸層轉換為領域模型,不做其他事。服務層負責決策。儲存庫持有查詢。在處理器中新增的驗證對服務的其他呼叫者是不可見的。
上下文
上下文屬於請求,並隨之消亡。
- 將
ctx作為第一個參數傳遞,一直傳到資料庫呼叫。不接受上下文的函數無法被取消,也無法攜帶截止時間。 - 絕不將
context.Context儲存在結構體欄位中。 - 絕不將請求上下文傳遞給一個會比處理器更長壽的 goroutine。獨立背景工作需要自己的上下文、自己的逾時設定,並在處理器返回前明確地複製出所需的數值。
- 同樣適用於任何從請求衍生出的資源——交易、連線、請求範圍的資料庫存取器。在處理器返回後繼續使用它們,是一種友善錯誤訊息的用完即丟行為。
錯誤
- 使用
%w包裝,並添加呼叫者無法自己知道的資訊:識別碼、操作。例如fmt.Errorf("load order %d: %w", id, err)。不要加上函數名稱作為前綴;那串東西讀起來只是噪音。 - 使用
errors.Is與errors.As進行比較。直接的==比較會在任何包裝行為發生時失效。 - 只在一個地方、即處理器邊界,將錯誤轉換為傳輸狀態碼。一個回傳 HTTP 狀態碼的儲存庫已經洩漏了兩個層次。
sql.ErrNoRows是領域層面的結果,不是失敗。在儲存庫邊界將其轉為領域的「找不到」,如此服務層就不需要匯入database/sql。- 絕不要為了滿足編譯器而丟棄錯誤。如果確實可以忽略,請賦值給
_並加上註解說明原因。
交易
在擁有變數的層級開啟交易——通常是服務層,絕不要在儲存庫層,因為一個自己開交易的儲存庫無法與更大的交易組合。將交易物件向下傳遞。
在每條路徑上都進行提交與回滾,包括恐慌狀況。成功提交後的回滾必須是無害的;這就是為什麼 defer tx.Rollback() 是安全的做法。
不要在不需與交易保持原子性的地方進行 I/O 操作。在未關閉的交易中向支付供應商發送 HTTP 呼叫,會因為他人服務中斷而鎖住資料庫連線。
租戶
如果服務是多租戶的,租戶識別碼應由程式碼強制執行,而非資料庫。每個儲存庫查詢——無論讀取或寫入——都必須攜帶租戶謂詞。僅依據主鍵過濾的查詢會愉快地回傳另一個租戶的資料列。從程式碼庫已有的請求上下文存取器具體取得租戶識別碼,並確認哪個存取器是正確的:一個代表子租戶動作的服務通常有兩個存取器,而明顯的那個往往是錯的。
Goroutine
每個 goroutine 都需要已知的生命週期與已知的所有者。在寫下 go 之前,回答:誰在等待它?它如何停止?它的錯誤會去哪裡?一個錯誤被丟棄的 goroutine 是沉默的失敗。
當呼叫者需要等待時,使用 errgroup。當不符合時,使用明確的 sync.WaitGroup 加上收集錯誤的通道。在請求處理中使用裸露的 go f() 幾乎總是缺陷。
測試
表格驅動測試,每個案例一個 t.Run,以行為命名而非輸入。每個案例陳述其輸入、期望結果,沒有其他東西;所有案例共用的設定應放在表格之前。
執行測試時務必加上逾時參數:
go test -count=1 -timeout 60s ./...
-count=1 用來關閉結果快取,否則快取會在你剛修改程式碼後仍然報告測試通過。逾時設定比看起來更重要:一個沒有逾時的鎖死測試會佔用記憶體直到機器停擺。
測試套件的匯出行為。一個觸及未匯出內部細節的測試會鎖死實作方式,並在每次誠實的重構時失敗。
當測試不穩定時,通常是報告真正的競爭條件。在得出其他結論之前,請先加上 -race 旗標執行,並且永遠不要透過增加 sleep 來修復。
完成之前
執行涵蓋該變更的最小範圍測試,如果共享合約有變動則擴大範圍。在服務目錄下執行 golangci-lint run,而不是使用可能吞掉結束碼的 make 目標。回報失敗時請連同輸出一起提供,而不是削弱測試。