Go 編碼風格指南

這些規則旨在指導生成簡單、可讀且可維護的 Go 程式碼，遵循 Go 的慣用寫法與務實的工程原則。

1. 最少抽象原則

你的主要目標是清晰，而不是耍巧。從最簡單的解法開始。

• 規則 1.1：預設使用單一函式：先在一個函式中解決問題。不要過早建立輔助函式、新型別或新套件。
• 規則 1.2：證明每個抽象都有必要：在建立新函式、結構體或套件之前，你必須依據以下規則證明其合理性，例如函式長度、參數數量或三次法則。如果沒有強而有力的抽象理由，就不要抽象。

2. 函式設計與粒度

函式是基本的建構單位。它們必須清楚且聚焦。

• 規則 2.1：函式只做一件事：每個函式都應該只有一個明確職責。如果你無法用一句簡單的話描述某個函式的用途，表示它做得太多了。
• 規則 2.2：嚴格限制函式長度：函式很少應超過 50 行。如果一個函式變得更長，立即將它拆成更小的私有輔助函式。這些輔助函式應保留在同一個檔案中，以維持局部性。
• 規則 2.3：嚴格限制參數數量：一個函式不能超過四個參數。
  • 如果需要更多參數，請將相關參數整理成一個結構體。
  • 如果函式需要操作共享狀態，請把它設計成某個持有該狀態之結構體的方法。這比在多個函式之間傳遞一堆參數更好。
• 規則 2.4：回傳值：直接回傳一個或兩個值。如果需要回傳三個以上彼此相關的值，請使用具名結構體來提供上下文與清晰性。避免回傳 map 或多個值的裸 tuple。

3. 重複與抽象

避免倉促抽象。重複通常比錯誤的抽象更好。

• 規則 3.1：三次法則：不要在第一次或第二次出現重複程式碼時就重構。只有在你遇到第三次時，才應該考慮建立共享抽象，例如新增一個函式。
• 規則 3.2：確認那是真正的重複：在重構之前，先確認這些重複程式碼代表的是相同的核心邏輯。如果程式碼表面上看起來相似，但實際處理的是可能獨立變動的不同業務規則，就必須保持分離。在這種情況下建立抽象，只會形成緊密耦合但邏輯上無關的依賴。

4. 套件與介面哲學

依照 Go 的慣例處理套件與介面。

• 規則 4.1：套件只做一件事：一個套件應該代表單一概念，例如 http、user、models。不要建立泛用的 utilities、common 或 helpers 套件。把相關型別與函式放在同一個高內聚的套件中。
• 規則 4.2：介面由使用方定義：不要定義大型、單體式介面。相反地，使用相依物件的函式應自行定義一個小介面，只描述它實際需要的行為。這符合 Go 的一句格言：「介面越大，抽象越弱。」
• 規則 4.3：保持介面精簡：理想情況下，一個介面只應有一個方法。超過三個方法的介面是一個警訊，應重新評估設計。