14 KiB

Raw Blame History

name	description
golang-patterns	道地的 Go 語言模式、最佳實踐與慣例，用於建構穩健、高效且易於維護的 Go 應用程序。

Go 開發模式 (Go Development Patterns)

道地的 Go 語言模式與最佳實踐，用於建構穩健、高效且易於維護的應用程序。

何時啟用

撰寫新的 Go 程式碼。
審查 Go 程式碼。
重構現有的 Go 程式碼。
設計 Go 套件 (Packages) 或模組 (Modules)。

核心原則

1. 簡潔與清晰 (Simplicity and Clarity)

Go 語言偏好簡潔而非精巧。程式碼應該是顯而易見且易於閱讀的。

// 推薦 (Good)：清晰且直接
func GetUser(id string) (*User, error) {
    user, err := db.FindUser(id)
    if err != nil {
        return nil, fmt.Errorf("獲取使用者 %s 失敗: %w", id, err)
    }
    return user, nil
}

// 不推薦 (Bad)：過於取巧
func GetUser(id string) (*User, error) {
    return func() (*User, error) {
        if u, e := db.FindUser(id); e == nil {
            return u, nil
        } else {
            return nil, e
        }
    }()
}

2. 讓零值 (Zero Value) 變得有用

設計型別時，應使其零值在無需初始化的情况下即可直接使用。

// 推薦 (Good)：零值很有用
type Counter struct {
    mu    sync.Mutex
    count int // 零值為 0，可直接使用
}

func (c *Counter) Inc() {
    c.mu.Lock()
    c.count++
    c.mu.Unlock()
}

// 推薦 (Good)：bytes.Buffer 的零值即可工作
var buf bytes.Buffer
buf.WriteString("hello")

// 不推薦 (Bad)：需要明確初始化
type BadCounter struct {
    counts map[string]int // 操作 nil map 會引發 panic
}

3. 接受介面，回傳結構體 (Accept Interfaces, Return Structs)

函式應接受介面 (Interface) 參數，並回傳具體型別 (Concrete Types/Structs)。

// 推薦 (Good)：接受介面，回傳具體型別
func ProcessData(r io.Reader) (*Result, error) {
    data, err := io.ReadAll(r)
    if err != nil {
        return nil, err
    }
    return &Result{Data: data}, nil
}

// 不推薦 (Bad)：回傳介面 (無謂地隱藏了實作細節)
func ProcessData(r io.Reader) (io.Reader, error) {
    // ...
}

錯誤處理模式 (Error Handling Patterns)

帶有上下文的錯誤包裝 (Error Wrapping)

// 推薦 (Good)：使用上下文包裝錯誤
func LoadConfig(path string) (*Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("載入配置檔案 %s 失敗: %w", path, err)
    }

    var cfg Config
    if err := json.Unmarshal(data, &cfg); err != nil {
        return nil, fmt.Errorf("解析配置檔案 %s 失敗: %w", path, err)
    }

    return &cfg, nil
}

自定義錯誤型別

// 定義領域特定的錯誤
type ValidationError struct {
    Field   string
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("欄位 %s 驗證失敗: %s", e.Field, e.Message)
}

// 常見案例的哨兵錯誤 (Sentinel errors)
var (
    ErrNotFound     = errors.New("找不到資源")
    ErrUnauthorized = errors.New("未經授權")
    ErrInvalidInput = errors.New("無效的輸入")
)

使用 errors.Is 與 errors.As 進行錯誤檢查

func HandleError(err error) {
    // 檢查特定的錯誤內容
    if errors.Is(err, sql.ErrNoRows) {
        log.Println("找不到紀錄")
        return
    }

    // 檢查錯誤型別
    var validationErr *ValidationError
    if errors.As(err, &validationErr) {
        log.Printf("欄位 %s 發生驗證錯誤: %s",
            validationErr.Field, validationErr.Message)
        return
    }

    // 未知錯誤
    log.Printf("發生非預期錯誤: %v", err)
}

絕不忽略錯誤

// 不推薦 (Bad)：使用空白識別字忽略錯誤
result, _ := doSomething()

// 推薦 (Good)：處理錯誤，或明確說明為何可以安全忽略
result, err := doSomething()
if err != nil {
    return err
}

// 可接受 (Acceptable)：當錯誤真的無關緊要時 (極少見)
_ = writer.Close() // 盡力清理資源，錯誤已在別處記錄

併發模式 (Concurrency Patterns)

工作池 (Worker Pool)

func WorkerPool(jobs <-chan Job, results chan<- Result, numWorkers int) {
    var wg sync.WaitGroup

    for i := 0; i < numWorkers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for job := range jobs {
                results <- process(job)
            }
        }()
    }

    wg.Wait()
    close(results)
}

使用 Context 處理取消與超時

func FetchWithTimeout(ctx context.Context, url string) ([]byte, error) {
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
    if err != nil {
        return nil, fmt.Errorf("建立請求失敗: %w", err)
    }

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("獲取 %s 失敗: %w", url, err)
    }
    defer resp.Body.Close()

    return io.ReadAll(resp.Body)
}

優雅關機 (Graceful Shutdown)

func GracefulShutdown(server *http.Server) {
    quit := make(chan os.Signal, 1)
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)

    <-quit
    log.Println("正在關閉伺服器...")

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    if err := server.Shutdown(ctx); err != nil {
        log.Fatalf("伺服器被迫強制關閉: %v", err)
    }

    log.Println("伺服器已退出")
}

使用 errgroup 協調多個 Goroutine

import "golang.org/x/sync/errgroup"

func FetchAll(ctx context.Context, urls []string) ([][]byte, error) {
    g, ctx := errgroup.WithContext(ctx)
    results := make([][]byte, len(urls))

    for i, url := range urls {
        i, url := i, url // 捕捉迴圈變數
        g.Go(func() error {
            data, err := FetchWithTimeout(ctx, url)
            if err != nil {
                return err
            }
            results[i] = data
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        return nil, err
    }
    return results, nil
}

避免 Goroutine 洩漏

// 不推薦 (Bad)：若 Context 被取消，Goroutine 會洩漏
func leakyFetch(ctx context.Context, url string) <-chan []byte {
    ch := make(chan []byte)
    go func() {
        data, _ := fetch(url)
        ch <- data // 如果沒有接收者，會永遠阻塞在這裡
    }()
    return ch
}

// 推薦 (Good)：正確處理取消信號
func safeFetch(ctx context.Context, url string) <-chan []byte {
    ch := make(chan []byte, 1) // 具備緩衝的通道
    go func() {
        data, err := fetch(url)
        if err != nil {
            return
        }
        select {
        case ch <- data:
        case <-ctx.Done():
        }
    }()
    return ch
}

介面設計 (Interface Design)

小型、聚焦的介面

// 推薦 (Good)：單一方法的介面
type Reader interface {
    Read(p []byte) (n int, err error)
}

type Writer interface {
    Write(p []byte) (n int, err error)
}

type Closer interface {
    Close() error
}

// 根據需要組合介面
type ReadWriteCloser interface {
    Reader
    Writer
    Closer
}

在使用處定義介面

// 介面應定義在消費者套件中，而非生產者套件
package service

// UserStore 定義了此服務所需的功能
type UserStore interface {
    GetUser(id string) (*User, error)
    SaveUser(user *User) error
}

type Service struct {
    store UserStore
}

// 具體實作可以放在另一個套件中
// 它不需要知道這個介面的存在

使用型別斷言 (Type Assertions) 處理選用行為

type Flusher interface {
    Flush() error
}

func WriteAndFlush(w io.Writer, data []byte) error {
    if _, err := w.Write(data); err != nil {
        return err
    }

    // 如果支援 Flush，則執行之
    if f, ok := w.(Flusher); ok {
        return f.Flush()
    }
    return nil
}

套件組織 (Package Organization)

標準專案結構

myproject/
├── cmd/
│   └── myapp/
│       └── main.go           # 程式入口點
├── internal/
│   ├── handler/              # HTTP 處理常式
│   ├── service/              # 業務邏輯
│   ├── repository/           # 資料存取
│   └── config/               # 配置管理
├── pkg/
│   └── client/               # 公開的 API 客戶端
├── api/
│   └── v1/                   # API 定義 (proto, OpenAPI)
├── testdata/                 # 測試用的資料
├── go.mod
├── go.sum
└── Makefile

套件命名規則

// 推薦 (Good)：簡短、小寫、無底線
package http
package json
package user

// 不推薦 (Bad)：冗長、大小寫混合或重複
package httpHandler
package json_parser
package userService // 重複的 'Service' 後綴

避免套件層級的狀態 (Package-Level State)

// 不推薦 (Bad)：全域可變狀態
var db *sql.DB

func init() {
    db, _ = sql.Open("postgres", os.Getenv("DATABASE_URL"))
}

// 推薦 (Good)：依賴注入
type Server struct {
    db *sql.DB
}

func NewServer(db *sql.DB) *Server {
    return &Server{db: db}
}

結構體設計 (Struct Design)

功能選項模式 (Functional Options Pattern)

type Server struct {
    addr    string
    timeout time.Duration
    logger  *log.Logger
}

type Option func(*Server)

func WithTimeout(d time.Duration) Option {
    return func(s *Server) {
        s.timeout = d
    }
}

func WithLogger(l *log.Logger) Option {
    return func(s *Server) {
        s.logger = l
    }
}

func NewServer(addr string, opts ...Option) *Server {
    s := &Server{
        addr:    addr,
        timeout: 30 * time.Second, // 預設值
        logger:  log.Default(),    // 預設值
    }
    for _, opt := range opts {
        opt(s)
    }
    return s
}

// 用法
server := NewServer(":8080",
    WithTimeout(60*time.Second),
    WithLogger(customLogger),
)

使用嵌入 (Embedding) 進行組合

type Logger struct {
    prefix string
}

func (l *Logger) Log(msg string) {
    fmt.Printf("[%s] %s\n", l.prefix, msg)
}

type Server struct {
    *Logger // 嵌入 - Server 會繼承 Log 方法
    addr    string
}

func NewServer(addr string) *Server {
    return &Server{
        Logger: &Logger{prefix: "SERVER"},
        addr:   addr,
    }
}

// 用法
s := NewServer(":8080")
s.Log("正在啟動...") // 呼叫嵌入的 Logger.Log

記憶體與效能

在已知大小時預先配置 Slice

// 不推薦 (Bad)：導致 Slice 多次擴容
func processItems(items []Item) []Result {
    var results []Result
    for _, item := range items {
        results = append(results, process(item))
    }
    return results
}

// 推薦 (Good)：一次完成配置
func processItems(items []Item) []Result {
    results := make([]Result, 0, len(items))
    for _, item := range items {
        results = append(results, process(item))
    }
    return results
}

為頻繁配置使用 sync.Pool

var bufferPool = sync.Pool{
    New: func() interface{} {
        return new(bytes.Buffer)
    },
}

func ProcessRequest(data []byte) []byte {
    buf := bufferPool.Get().(*bytes.Buffer)
    defer func() {
        buf.Reset()
        bufferPool.Put(buf)
    }()

    buf.Write(data)
    // 處理中...
    return buf.Bytes()
}

避免在迴圈中直接拼接字串

// 不推薦 (Bad)：會產生大量的字串記憶體配置
func join(parts []string) string {
    var result string
    for _, p := range parts {
        result += p + ","
    }
    return result
}

// 推薦 (Good)：使用 strings.Builder 進行單次配置
func join(parts []string) string {
    var sb strings.Builder
    for i, p := range parts {
        if i > 0 {
            sb.WriteString(",")
        }
        sb.WriteString(p)
    }
    return sb.String()
}

// 最佳做法 (Best)：直接使用標準函式庫
func join(parts []string) string {
    return strings.Join(parts, ",")
}

Go 工具整合

核心指令

# 建置與執行
go build ./...
go run ./cmd/myapp

# 測試
go test ./...
go test -race ./...
go test -cover ./...

# 靜態分析
go vet ./...
staticcheck ./...
golangci-lint run

# 模組管理
go mod tidy
go mod verify

# 格式化
gofmt -w .
goimports -w .

建議的 Linter 配置 (.golangci.yml)

linters:
  enable:
    - errcheck
    - gosimple
    - govet
    - ineffassign
    - staticcheck
    - unused
    - gofmt
    - goimports
    - misspell
    - unconvert
    - unparam

linters-settings:
  errcheck:
    check-type-assertions: true
  govet:
    check-shadowing: true

issues:
  exclude-use-default: false

快速參考：Go 語言慣用語 (Idioms)

慣用語	描述
接受介面，回傳結構體	函式參數用介面，回傳值用具體型別
錯誤即值 (Errors are values)	將錯誤視為一等公民值處理，而非例外情況
不要透過共享記憶體來通訊	應使用通道 (Channels) 在 Goroutine 間進行協調
讓零值變得有用	型別應在不需顯式初始化的情況下即可運作
少量拷貝優於少量依賴	避免不必要的外部相依套件
清晰優於精巧	優先考量程式碼的可讀性
gofmt 是大家的朋友	務必始終使用 gofmt/goimports 手動格式化
提早回傳 (Return early)	先處理錯誤情況，保持正常路徑 (Happy Path) 不縮排

應避免的反模式

// 不推薦 (Bad)：在長函式中使用具名回傳值 (Naked returns)
func process() (result int, err error) {
    // ... 50 行程式碼 ...
    return // 到底回傳了什麼？
}

// 不推薦 (Bad)：將 panic 用於流程控制
func GetUser(id string) *User {
    user, err := db.Find(id)
    if err != nil {
        panic(err) // 絕對不要這樣做
    }
    return user
}

// 不推薦 (Bad)：在結構體中傳遞 Context
type Request struct {
    ctx context.Context // Context 應作為第一個參數
    ID  string
}

// 推薦 (Good)：Context 作為第一個參數
func ProcessRequest(ctx context.Context, id string) error {
    // ...
}

// 不推薦 (Bad)：混合使用數值與指標接收者 (Receivers)
type Counter struct{ n int }
func (c Counter) Value() int { return c.n }    // 數值接收者
func (c *Counter) Increment() { c.n++ }        // 指標接收者
// 請擇一使用並保持一致性

請記住：Go 程式碼應該以「無趣」為最高指導原則 — 意即它是可預測的、一致的且易於理解的。如有疑慮，請保持簡潔。

14 KiB Raw Blame History Unescape Escape