Community程式設計與開發github.com

sk-go-service

實作、擴展或除錯 Go 後端服務中的處理器、服務或儲存庫,涵蓋上下文傳遞、錯誤包裝、交易邊界、租戶範圍以及表格驅動測試。適用於編寫或修改 Go 伺服器程式碼、新增端點或 gRPC 方法、更動儲存庫查詢,或診斷 Go 服務中的恐慌、記憶體洩漏或不穩定測試。

sk-go-service 是什麼?

此技能為在分層式 Go 後端服務中工作時,提供一套強制性的慣例與最佳實踐,以確保在並發與多租戶環境下的正確性。它指導開發者如何在新增處理器、服務或儲存庫時,正確地傳播上下文、包裝錯誤、管理交易邊界與租戶範圍。技能涵蓋所有主要層面:上下文應作為第一個參數傳遞且絕不儲存在結構體中;錯誤應使用 `%w` 包裝並透過 `errors.Is` 與 `errors.As` 進行比較,並在處理器邊界統一回傳傳輸狀態碼。交易應由服務層負責開關,而非儲存庫,以確保可組合性;多租戶服務中,所有查詢都必須強制攜帶租戶謂詞。在 goroutine 處理方面,需有明確的生命週期與所有權,避免遺失錯誤;測試方面採用表格驅動測試,每個案例以行為命名,並務必加上逾時與競態檢測旗標。此技能廣泛適用於所有 Go 後端平台(如標準 HTTP 服務、gRPC 服務),並透過清晰的 layer 分割與嚴格的編碼規範,顯著提升程式碼的可維護性、正確性與團隊協作效率。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-go-service

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 目標。回報失敗時請連同輸出一起提供,而不是削弱測試。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

相關技能