This resume is also available in English.

二、寫一個服務第 2 / 4 篇 · 全部目錄

專欄 › 二、寫一個服務 › 第 6 篇

分層架構與依賴注入

Layered Architecture and Dependency Injection in Go

把訂單服務拆成 handler、service、repository 三層:介面由使用的一方定義、相依物件從建構函式傳入、在 main 集中組裝,不靠任何框架也能寫出好測試、好替換的 Go 服務。

  • Go
  • Architecture
  • Dependency Injection
  • Interfaces
這篇的步驟
  1. 這篇要解決什麼
  2. 第 1 步:先分清楚三種職責
  3. 第 2 步:目錄與套件怎麼放
  4. 第 3 步:介面由使用的一方定義
  5. 第 4 步:建構函式注入
  6. 第 5 步:串起三層,讓錯誤跨層也不失真
  7. 第 6 步:在 main 集中組裝
  8. 第 7 步:收穫:替換實作與單元測試
  9. 常見陷阱
  10. 重點整理
  11. 下一篇

上一篇〈net/http 與中介層〉我們用標準函式庫替訂單服務寫出了路由、中介層與伺服器逾時;這篇接著處理那個越寫越胖的 handler,把它拆成職責清楚的三層,並用最樸素的方式把它們接起來。

這篇要解決什麼

上一篇的訂單服務能跑,但所有事情都擠在 handler 裡:解析 JSON、檢查欄位、計算總額、決定訂單狀態、把資料寫進 map,全部在同一個函式。服務只有兩個端點時這還能忍受,一旦需求變多,問題會一個接一個出現:

  • 測不了商業規則。 想驗證「總額計算」或「空的品項要被拒絕」,就得先組一個 HTTP 請求,再從回應的 JSON 裡挖結果。規則本身和 HTTP 綁死了。
  • 換不了儲存方式。 資料放在 map 裡,下一篇要換成資料庫時,得把每個 handler 都翻一遍。
  • 規則散落各處。 同樣的驗證邏輯被複製到建立訂單、修改訂單、後台匯入三個地方,改一處忘兩處。
  • 錯誤語意混亂。 資料庫的 sql.ErrNoRows 一路漏到 handler,handler 得知道底層用的是哪種資料庫,才能決定要回 404。

分層架構與依賴注入就是為了解決這些問題。這兩個詞聽起來很重,在 Go 裡卻可以寫得非常輕:不需要任何框架,只需要三個習慣:依職責分層、介面由使用的一方定義、相依物件從建構函式傳進來。這篇會一步步把訂單服務改造成這個樣子,並說明每個決定背後的理由。

第 1 步:先分清楚三種職責

把一個請求從進來到出去的過程拆開來看,其實有三種性質完全不同的工作:

層負責不該知道的事
handler(傳輸層)解析路徑參數與 JSON、檢查格式、呼叫 service、把結果或錯誤翻譯成 HTTP 狀態碼總額怎麼算、資料存在哪裡
service(商業規則層)訂單的規則:總額計算、狀態從 pending 到 paid 或 cancelled 的轉換、需要哪些資料一起成功或一起失敗請求是 HTTP 還是 gRPC、資料庫是哪一種
repository(儲存層)把領域物件存進去、讀出來;把底層錯誤翻譯成領域錯誤為什麼要存、存完要做什麼

另外還有一塊所有層都會用到的東西:領域型別,也就是 Order、Item、訂單狀態,以及 ErrNotFound、ErrInvalid 這類領域錯誤。它們是純資料與純函式,不依賴任何一層,反而是每一層都可以依賴它們。

handler(傳輸層) 解析請求、檢查格式、錯誤轉成狀態碼 只認得 orderService 介面 service(商業規則) 計算總額、狀態轉換、決定交易邊界 只認得 OrderRepository 介面 MemoryRepo 示範與測試用 PostgresRepo 下一篇的資料庫實作 領域型別 Order、Item pending/paid/cancelled ErrNotFound、ErrInvalid 每一層都可以用它 它不依賴任何一層 箭頭方向就是依賴方向:上層只認得自己定義的介面,不認得下層的具體型別。

圖:依賴只往下走;每一層只認得自己需要的介面,領域型別則被所有層共用。

這樣分的好處,是每一層變動的原因不同。API 的欄位命名改了,只動 handler;折扣規則改了,只動 service;從記憶體換成資料庫,只動 repository。軟體設計常說的「單一職責」,在這裡的具體意思就是:一個檔案只因為一種原因而修改。

要注意的是,分層不是越多越好。有些教材會在三層之外再加 DTO 轉換層、use case 層、domain service 層,對一個只有幾個端點的服務來說,這些多出來的層只會讓每次修改都要跨越更多檔案。三層是一個合理的起點,等某一層真的變得複雜,再把它拆細也不遲。

第 2 步:目錄與套件怎麼放

沿用〈工程結構與 Go Modules〉的規劃,模組是 example.com/shop,每個可執行的服務在 cmd/ 底下有自己的進入點,業務程式碼放在 internal/,讓模組外的程式無法匯入:

shop/
├── go.mod                      # module example.com/shop
├── cmd/
│   └── order/
│       └── main.go             # 組裝根:建立所有物件、啟動伺服器
└── internal/
    ├── order/
    │   ├── order.go            # 領域型別:Order、Item、狀態、領域錯誤
    │   ├── handler.go          # HTTP 傳輸層
    │   ├── service.go          # 商業規則,並定義它需要的 Repository 介面
    │   └── repository.go       # 儲存實作(記憶體版、資料庫版)
    └── platform/
        └── httpx/              # 共用的中介層:RequestID、Logging、Recover

這裡刻意採用「依領域分套件」,而不是「依技術角色分套件」。很多從其他語言轉過來的專案會建立 controllers/、services/、models/、repositories/ 這種目錄,把所有領域的 handler 放一起、所有 service 放一起。在 Go 裡這通常是壞主意,原因有三:

  1. 套件名稱會變得沒有意義。 呼叫端寫出來是 services.OrderService、models.Order,套件名稱完全沒提供資訊;改成 order.Service、order.Order 讀起來更自然。
  2. 容易出現循環匯入。 Go 不允許套件互相匯入,services 要用 models、models 又想呼叫 services 的某個輔助函式,就卡住了。依領域分套件時,同一個領域的東西都在同一個套件裡,自然不會互相匯入。
  3. 改一個功能要跨四個目錄。 依領域分的話,訂單相關的修改幾乎都集中在 internal/order/ 一個目錄裡。

一個套件裡放三層會不會太擠?只要檔案依職責切開,一個領域套件有五六個檔案很正常。當某個領域長到需要更細的切分,或者後面〈什麼時候該拆:邊界與拆分策略〉決定把它變成獨立服務時,因為它早就是一個邊界清楚的套件,搬出去的成本也很低。

第 3 步:介面由使用的一方定義

這是 Go 和許多語言最不一樣、也最重要的一個習慣。在 Java 或 C# 裡,常見的寫法是儲存層先宣告一個 IOrderRepository 介面,再寫一個類別明確地 implements 它,使用者去引用那個介面。Go 的介面是隱式實作的:只要一個型別擁有介面要求的所有方法,它就自動滿足該介面,不需要任何宣告。

這個語言特性帶來一個設計原則:介面應該放在使用它的那一方,而且只列出使用者真正需要的方法。 service 需要「存一筆訂單」與「讀一筆訂單」兩個能力,它就在自己的檔案裡宣告一個只有這兩個方法的介面:

// 片段:internal/order/service.go
package order

import (
	"context"
	"fmt"
	"time"
)

// Repository 是 service 需要的儲存能力:由使用的一方(service)定義,
// 只列出它真的會呼叫的方法。
type Repository interface {
	Create(ctx context.Context, o *Order) error
	Get(ctx context.Context, id int64) (Order, error)
}

type Service struct {
	repo Repository
	now  func() time.Time
}

func NewService(repo Repository, now func() time.Time) *Service {
	if repo == nil || now == nil {
		panic("order.NewService: nil dependency")
	}
	return &Service{repo: repo, now: now}
}

func (s *Service) Place(ctx context.Context, userID int64, items []Item) (Order, error) {
	total, err := Total(items)
	if err != nil {
		return Order{}, err
	}
	o := Order{UserID: userID, Items: items, Total: total, Status: StatusPending, CreatedAt: s.now()}
	if err := s.repo.Create(ctx, &o); err != nil {
		return Order{}, fmt.Errorf("place order: %w", err)
	}
	return o, nil
}

這樣做有幾個實際的好處:

  • 介面很小。 儲存層的具體型別可能有十幾個方法(列表、分頁、統計、後台用的批次更新),但 service 只依賴它用到的兩個。介面越小,越容易寫出替身來測試,也越不容易因為儲存層加了新方法而被迫修改。
  • 依賴方向正確。 service 不匯入儲存層的套件,反而是儲存層去「配合」service 定義的形狀。當儲存實作放在別的套件(例如共用的 internal/platform/postgres)時,這一點特別重要:商業規則不會因為資料庫套件的變動而重新編譯,也不會間接依賴到資料庫驅動。
  • 不同使用者可以有不同的介面。 後台報表需要的是「依日期區間列出訂單」,它可以在自己的套件定義另一個只有那個方法的介面,同一個具體型別同時滿足兩者。

Go 社群常說的「接受介面,回傳結構體」(accept interfaces, return structs)就是這個意思:函式的參數用介面,讓呼叫者可以傳任何符合條件的實作;建構函式回傳具體型別,讓使用者能拿到完整的方法集合,要不要把它當成某個介面來用,由使用者決定。所以 NewService 回傳的是 *Service,而不是某個 OrderService 介面。

提示:不要為了「以後可能會換」而預先替每個型別配一個介面。只有一個實作、也沒有測試需要替換的地方,直接用具體型別就好。等真的出現第二個使用情境,再從使用方抽出介面,這在 Go 裡是成本很低的重構,因為實作方不需要做任何修改。

第 4 步:建構函式注入

「依賴注入」這個詞的意思其實很單純:一個物件需要的東西,由外面交給它,而不是它自己去建立或去全域變數裡拿。 在 Go 裡,最直接的方式就是建構函式的參數:

  • NewService(repo Repository, now func() time.Time):service 需要儲存能力與「現在幾點」,都由呼叫者提供。
  • NewHandler(svc orderService, logger *slog.Logger):handler 需要 service 與記錄器,同樣由外面傳入。

注意 now func() time.Time 這個參數。訂單的建立時間本來直接呼叫 time.Now() 就好,但那樣一來,測試永遠無法驗證「建立時間被正確設定」,因為每次執行的時間都不一樣。把「取得現在時間」也當成一個相依物件注入,正式環境傳 time.Now,測試傳一個回傳固定時間的函式,問題就解決了。同樣的思路適用於亂數、編號產生器、外部 API 用戶端:凡是會讓結果不可預測的東西,都值得被注入。

和其他注入方式比較:

方式做法問題
全域變數var DB *sql.DB,大家直接用測試無法替換、執行順序隱含相依、平行測試互相干擾
套件的 init() 自行建立匯入時就連線資料庫匯入套件就有副作用,測試與工具程式都被迫連線
setter 注入先建立物件,再 SetRepo(r)物件在被設定前處於不完整狀態,忘了設定就在執行時 nil panic
建構函式注入NewService(repo, now)參數多時建構函式會變長,但缺什麼在編譯期就看得出來

建構函式注入最大的優點是:物件一被建立出來就是完整、可用的。 不存在「已建立但還沒設定好」的中間狀態。上面的 NewService 還多做了一件事:參數是 nil 就直接 panic。這是在程式啟動時就暴露組裝錯誤,總比在第一個請求進來時才因為 nil 指標崩潰好。

當某個建構函式的參數變得很多(例如超過五六個),通常代表兩種情況之一:這個物件職責太多,應該拆開;或者其中幾個參數是「選用設定」而非「必要相依」。前者就拆,後者可以把選用設定收進一個 Config 結構體,或使用 functional options 模式。不管哪一種,必要的相依物件仍然應該是建構函式的必填參數,不要藏進選項裡。

第 5 步:串起三層,讓錯誤跨層也不失真

把前面幾步組合起來,下面是一個能直接執行的完整版本。為了能單檔編譯,三層暫時放在同一個檔案,用註解標出它們在正式專案裡分別屬於哪個檔案;在實際專案裡,它們就是第 2 步目錄中的 order.go、service.go、repository.go、handler.go 與 cmd/order/main.go。

package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log/slog"
	"net/http"
	"os"
	"strconv"
	"sync"
	"time"
)

// ===== 領域(domain):純資料與錯誤,不依賴任何人 =====

type Item struct {
	ProductID int64 `json:"product_id"`
	Qty       int   `json:"qty"`
	Price     int64 `json:"price"` // 單位:分
}

type Order struct {
	ID        int64     `json:"id"`
	UserID    int64     `json:"user_id"`
	Items     []Item    `json:"items"`
	Total     int64     `json:"total"`
	Status    string    `json:"status"`
	CreatedAt time.Time `json:"created_at"`
}

const (
	StatusPending   = "pending"
	StatusPaid      = "paid"
	StatusCancelled = "cancelled"
)

var (
	ErrNotFound = errors.New("order not found")
	ErrInvalid  = errors.New("invalid order")
)

// ===== 服務層(service):商業規則;需要什麼,就在這裡宣告介面 =====

// OrderRepository 由使用者(service)定義,只列出它真正會用到的方法。
type OrderRepository interface {
	Create(ctx context.Context, o *Order) error
	Get(ctx context.Context, id int64) (Order, error)
}

type OrderService struct {
	repo OrderRepository
	now  func() time.Time
}

func NewOrderService(repo OrderRepository, now func() time.Time) *OrderService {
	return &OrderService{repo: repo, now: now}
}

func (s *OrderService) Place(ctx context.Context, userID int64, items []Item) (Order, error) {
	if userID <= 0 {
		return Order{}, fmt.Errorf("%w: user_id is required", ErrInvalid)
	}
	if len(items) == 0 {
		return Order{}, fmt.Errorf("%w: at least one item", ErrInvalid)
	}
	var total int64
	for _, it := range items {
		if it.Qty <= 0 || it.Price < 0 {
			return Order{}, fmt.Errorf("%w: bad item %d", ErrInvalid, it.ProductID)
		}
		total += it.Price * int64(it.Qty)
	}
	o := Order{UserID: userID, Items: items, Total: total, Status: StatusPending, CreatedAt: s.now()}
	if err := s.repo.Create(ctx, &o); err != nil {
		return Order{}, fmt.Errorf("place order: %w", err)
	}
	return o, nil
}

func (s *OrderService) Get(ctx context.Context, id int64) (Order, error) {
	return s.repo.Get(ctx, id)
}

// ===== 儲存層(repository):這裡先用記憶體實作,下一篇換成資料庫 =====

type MemoryRepo struct {
	mu     sync.Mutex
	nextID int64
	data   map[int64]Order
}

func NewMemoryRepo() *MemoryRepo { return &MemoryRepo{data: make(map[int64]Order)} }

func (m *MemoryRepo) Create(_ context.Context, o *Order) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	m.nextID++
	o.ID = m.nextID
	m.data[o.ID] = *o
	return nil
}

func (m *MemoryRepo) Get(_ context.Context, id int64) (Order, error) {
	m.mu.Lock()
	defer m.mu.Unlock()
	o, ok := m.data[id]
	if !ok {
		return Order{}, ErrNotFound
	}
	return o, nil
}

// ===== 傳輸層(handler):HTTP 進出、狀態碼對應 =====

type orderService interface {
	Place(ctx context.Context, userID int64, items []Item) (Order, error)
	Get(ctx context.Context, id int64) (Order, error)
}

type OrderHandler struct {
	svc    orderService
	logger *slog.Logger
}

func NewOrderHandler(svc orderService, logger *slog.Logger) *OrderHandler {
	return &OrderHandler{svc: svc, logger: logger}
}

func (h *OrderHandler) Register(mux *http.ServeMux) {
	mux.HandleFunc("POST /orders", h.create)
	mux.HandleFunc("GET /orders/{id}", h.get)
}

func (h *OrderHandler) create(w http.ResponseWriter, r *http.Request) {
	var in struct {
		UserID int64  `json:"user_id"`
		Items  []Item `json:"items"`
	}
	if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
		http.Error(w, "invalid JSON", http.StatusBadRequest)
		return
	}
	o, err := h.svc.Place(r.Context(), in.UserID, in.Items)
	if err != nil {
		h.fail(w, r, err)
		return
	}
	writeJSON(w, http.StatusCreated, o)
}

func (h *OrderHandler) get(w http.ResponseWriter, r *http.Request) {
	id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
	if err != nil {
		http.Error(w, "id must be a number", http.StatusBadRequest)
		return
	}
	o, err := h.svc.Get(r.Context(), id)
	if err != nil {
		h.fail(w, r, err)
		return
	}
	writeJSON(w, http.StatusOK, o)
}

// fail 是領域錯誤翻譯成 HTTP 狀態碼的唯一地方。
func (h *OrderHandler) fail(w http.ResponseWriter, r *http.Request, err error) {
	switch {
	case errors.Is(err, ErrInvalid):
		http.Error(w, err.Error(), http.StatusUnprocessableEntity)
	case errors.Is(err, ErrNotFound):
		http.Error(w, "order not found", http.StatusNotFound)
	default:
		h.logger.ErrorContext(r.Context(), "request failed", slog.Any("err", err))
		http.Error(w, "internal error", http.StatusInternalServerError)
	}
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(v)
}

// ===== 組裝(composition root):唯一知道所有具體型別的地方 =====

func main() {
	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

	repo := NewMemoryRepo()
	svc := NewOrderService(repo, time.Now)
	h := NewOrderHandler(svc, logger)

	mux := http.NewServeMux()
	h.Register(mux)

	srv := &http.Server{Addr: ":8080", Handler: mux, ReadHeaderTimeout: 5 * time.Second}
	logger.Info("listening", slog.String("addr", srv.Addr))
	if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
		logger.Error("server stopped", slog.Any("err", err))
		os.Exit(1)
	}
}

錯誤怎麼跨層

這段程式最值得細看的,是錯誤在三層之間的流動方式,它直接應用了〈錯誤處理:包裝、哨兵、自訂型別〉的技巧:

  1. 領域錯誤定義在領域型別旁邊。 ErrNotFound 與 ErrInvalid 是哨兵錯誤,屬於訂單這個領域,而不屬於任何一層。
  2. repository 負責翻譯底層錯誤。 記憶體版找不到資料時回 ErrNotFound;下一篇的資料庫版遇到 sql.ErrNoRows 時,也要翻譯成同一個 ErrNotFound。這樣 service 與 handler 永遠不需要知道 database/sql 的存在。
  3. service 用 %w 補充脈絡。 fmt.Errorf("%w: user_id is required", ErrInvalid) 讓錯誤訊息更具體,同時保留可以被 errors.Is 判斷的身分。
  4. handler 是唯一把錯誤翻譯成 HTTP 的地方。 fail 方法集中處理:ErrInvalid 對應 422、ErrNotFound 對應 404,其他未預期的錯誤記錄下來並回 500,而且不把內部錯誤訊息直接送給客戶端,避免洩漏實作細節。

這樣安排之後,如果未來同一個 service 也要透過 gRPC 對外(〈gRPC 與 Protocol Buffers〉會做這件事),只需要再寫一個 gRPC 的傳輸層,把同樣的領域錯誤翻譯成 gRPC 狀態碼,service 與 repository 一行都不用改。

handler 也只依賴介面

handler 裡的 orderService 介面是小寫開頭、不公開的。它只屬於 handler 自己,用來表達「我需要一個能下單、能查單的東西」。正式環境傳進來的是 *OrderService,測試時可以傳一個假的實作,直接控制 service 回傳什麼結果或錯誤,用來驗證 handler 的狀態碼對應是否正確,這正是〈測試:表格驅動、httptest、整合測試〉會示範的寫法。

第 6 步:在 main 集中組裝

所有物件都靠建構函式接收相依物件,那總得有一個地方負責真的把它們「建出來、接起來」。這個地方叫做組裝根(composition root),在 Go 服務裡就是 cmd/order/main.go。

cmd/order/main.go:唯一知道所有具體型別的地方 1. 建立 repo NewMemoryRepo() 2. 建立 service NewOrderService 3. 建立 handler NewOrderHandler 4. 啟動伺服器 http.Server 每一步把上一步建好的物件當參數傳進建構函式: 沒有全域變數、沒有反射、沒有容器,換實作只要改這一個檔案。

圖:組裝根依序建立 repository、service、handler,再交給 http.Server;這是唯一知道所有具體型別的地方。

拆成多個套件之後,組裝根長這樣:

// 片段:cmd/order/main.go
package main

import (
	"context"
	"errors"
	"fmt"
	"log/slog"
	"net/http"
	"os"
	"time"

	"example.com/shop/internal/order"
	"example.com/shop/internal/platform/httpx"
)

func main() {
	if err := run(context.Background(), os.Getenv); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

// run 是組裝根:所有具體型別都在這裡建立並接起來。
func run(ctx context.Context, getenv func(string) string) error {
	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

	repo := order.NewMemoryRepository()
	svc := order.NewService(repo, time.Now)
	h := order.NewHandler(svc, logger)

	mux := http.NewServeMux()
	h.Register(mux)
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusNoContent)
	})

	addr := getenv("ORDER_ADDR")
	if addr == "" {
		addr = ":8080"
	}
	srv := &http.Server{
		Addr:              addr,
		Handler:           httpx.Chain(mux, httpx.RequestID, httpx.Logging(logger), httpx.Recover(logger)),
		ReadHeaderTimeout: 5 * time.Second,
	}
	logger.InfoContext(ctx, "order service listening", slog.String("addr", addr))
	if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
		return fmt.Errorf("serve: %w", err)
	}
	return nil
}

這裡有一個常見的小技巧:main 只負責呼叫 run 並處理結束碼,真正的組裝邏輯在 run 裡,而且 run 回傳 error。這樣做的好處是 run 裡可以放心使用 defer(os.Exit 會跳過所有 defer),也能在測試裡直接呼叫 run,傳入假的環境變數讀取函式,不需要真的去改行程的環境變數。設定的讀取方式與收到關閉訊號後如何結束,會在〈設定與優雅關閉〉完整處理。

為什麼不用 DI 框架

Go 生態系也有依賴注入工具,大致分成兩類:在編譯期產生組裝程式碼的工具(例如 Google 的 Wire),以及在執行期用反射自動解析相依關係的容器(例如 Uber 的 fx、dig)。

對多數 Go 服務來說,手寫組裝根已經足夠,而且有幾個框架給不了的優點:

  • 讀得懂。 新成員打開 main.go,從上讀到下就知道每個物件怎麼來的,不需要學框架的規則。
  • 錯誤在編譯期出現。 漏傳參數、型別不符,go build 就會告訴你;執行期容器的組裝錯誤則要等程式啟動才會發現。
  • 沒有魔法。 不會有「某個建構函式被自動呼叫了、但不知道是誰觸發的」這種情況。

組裝根長到幾百行、每次新增一個相依物件都要改很多地方時,才值得評估編譯期產生程式碼的工具。即使到那時候,它產生的也仍然是一般的 Go 程式碼,概念上與手寫組裝根完全相同。

第 7 步:收穫:替換實作與單元測試

做完這些,最直接的回報是可以只測 service,而且測試又快又穩定。測試不需要啟動 HTTP 伺服器、不需要資料庫,只要準備一個實作了 Repository 介面的替身,以及一個回傳固定時間的函式:

// 片段:internal/order/service_test.go
package order

import (
	"context"
	"errors"
	"testing"
	"time"
)

// stubRepo 只記住被存進來的訂單,或回傳預先設定的錯誤。
type stubRepo struct {
	saved *Order
	err   error
}

func (s *stubRepo) Create(_ context.Context, o *Order) error {
	if s.err != nil {
		return s.err
	}
	o.ID = 1
	s.saved = o
	return nil
}

func (s *stubRepo) Get(context.Context, int64) (Order, error) { return Order{}, nil }

func TestPlace(t *testing.T) {
	fixed := time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC)
	repo := &stubRepo{}
	svc := NewService(repo, func() time.Time { return fixed })

	o, err := svc.Place(context.Background(), 7, []Item{{ProductID: 1, Qty: 2, Price: 600}})
	if err != nil {
		t.Fatalf("Place() error = %v", err)
	}
	if o.Total != 1200 || o.Status != StatusPending || !o.CreatedAt.Equal(fixed) {
		t.Errorf("Place() = %+v", o)
	}
	if repo.saved == nil {
		t.Fatal("order was not saved")
	}

	_, err = svc.Place(context.Background(), 7, nil)
	if !errors.Is(err, ErrInvalid) {
		t.Errorf("empty items: error = %v, want ErrInvalid", err)
	}
}

這個測試能精準驗證三件事:總額有沒有算對、新訂單的狀態是不是 pending、建立時間是不是來自注入的時鐘。它在毫秒內跑完,也不會因為機器時區或執行時間而時好時壞。

替換實作的好處也不只在測試。下一篇把資料改存進資料庫時,只需要寫一個新的 repository 型別,在 main 裡把 NewMemoryRepository() 換成資料庫版本;service 與 handler 完全不用動。之後要在讀取路徑前面加一層快取,也可以寫一個同樣滿足 Repository 介面的「快取包裝器」,內部持有真正的 repository,這和〈net/http 與中介層〉的中介層是同一種「包裝」思路,只是換成用在儲存層。

提示:替身不一定要用 mock 套件產生。手寫一個只有幾行的 stub 或 fake 往往更清楚,而且當介面夠小(遵守第 3 步的原則),手寫替身的成本就非常低。替身寫起來很痛苦,通常代表介面太大了。

常見陷阱

  • 在實作方定義大介面。 在 repository 套件裡宣告一個包含所有方法的 OrderRepository 介面,再讓 service 引用它,等於把 Java 的習慣搬進 Go:service 被迫依賴它用不到的方法,替身也變得難寫。
  • 建構函式回傳介面。 func NewService(...) OrderService 會把具體型別藏起來,使用者拿不到其他方法,也讓編譯器難以內聯最佳化;除非有明確理由,回傳具體型別。
  • 把 HTTP 型別傳進 service。 service 的方法簽章出現 *http.Request 或 http.ResponseWriter,商業規則就又和傳輸層綁在一起了。service 只接收 context 與領域型別。
  • 讓 sql.ErrNoRows 漏出 repository。 上層一旦開始判斷資料庫的錯誤,換儲存方式時就得到處修改。
  • 偷偷呼叫 time.Now() 或讀全域變數。 它們是隱藏的相依物件,讓測試變得不可預測;凡是會變的東西都從建構函式注入。
  • 把 context 當成相依物件的容器。 從 ctx.Value 取出資料庫連線或 logger,等於把相依關係藏起來,編譯器也幫不上忙。context 只放請求範圍的資料。
  • 為了分層而分層。 每個函式都穿過五六層轉換,只是把資料從一個結構體複製到另一個結構體,這是過度設計。層數由實際的複雜度決定。
  • 依技術角色分套件。 controllers/、services/、models/ 的結構容易造成循環匯入,也讓一個功能的修改分散到多個目錄。

重點整理

  • 分成 handler、service、repository 三層,各自只因為一種原因而修改;領域型別與領域錯誤被所有層共用,本身不依賴任何層。
  • 依領域分套件(internal/order/),而不是依技術角色分套件,避免無意義的套件名稱與循環匯入。
  • Go 的介面是隱式實作的,所以介面應由使用的一方定義,而且只列出真正需要的方法。
  • 「接受介面,回傳結構體」:參數用介面,建構函式回傳具體型別。
  • 依賴注入在 Go 裡就是建構函式的參數;時間、亂數、外部用戶端這類會讓結果不可預測的東西也要注入。
  • 錯誤在 repository 被翻譯成領域錯誤,在 handler 被翻譯成 HTTP 狀態碼,中間用 %w 與 errors.Is 保留身分。
  • 在 cmd/order/main.go 集中組裝,main 只呼叫回傳 error 的 run;多數服務手寫組裝根就夠了,不需要 DI 框架。
  • 介面小、相依物件可注入,單元測試就能用幾行的手寫替身,快速而穩定。

下一篇

目前訂單仍然只存在記憶體裡,服務一重新啟動就全部消失,也無法保證「扣庫存」與「建立訂單」一起成功或一起失敗。〈database/sql、交易與連線池〉會寫出資料庫版的 repository,並說明交易與連線池該怎麼正確使用。