This resume is also available in English.

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

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

net/http 與中介層

net/http and Middleware in Go

只用標準函式庫寫出一個訂單服務的 HTTP 入口:Go 1.22 起的方法與路徑萬用字元路由、可組合的中介層(請求編號、slog 記錄、panic 復原、本文限制),以及 http.Server 的逾時設定。

  • Go
  • HTTP
  • Middleware
  • net/http
  • slog
這篇的步驟
  1. 這篇要解決什麼
  2. 第 1 步:先搞懂 Handler 這個介面
  3. 第 2 步:Go 1.22 的路由規則
  4. 第 3 步:中介層只是一個函式
  5. 第 4 步:攔截狀態碼,寫一個記錄中介層
  6. 第 5 步:組出完整的中介層鏈
  7. 第 6 步:設定 http.Server 的逾時
  8. 常見陷阱
  9. 重點整理
  10. 下一篇

上一篇〈context:取消、逾時與資料傳遞〉我們學會讓取消訊號與逾時沿著呼叫鏈一路傳下去;這篇接著把前四篇的零件組起來,替網路商店的訂單服務寫出第一個真正能接 HTTP 請求的入口,而 context 會在這裡第一次以 r.Context() 的身分登場。

這篇要解決什麼

前面四篇把 Go 的基本功打好了:〈工程結構與 Go Modules〉決定了模組 example.com/shop 與 cmd/、internal/ 的目錄規劃,〈錯誤處理:包裝、哨兵、自訂型別〉講了錯誤怎麼包裝與判斷,〈Goroutine、Channel 與並發模式〉講了並發,上一篇講了 context。從這一篇開始進入第二部分「寫一個服務」,我們要把這些零件組成一個真的能接請求的後端程式。整個第二部分沿用同一個例子:網路商店的訂單服務(cmd/order/main.go),能建立訂單、查詢訂單,之後再接上資料庫與測試。訂單的欄位從頭到尾都是 ID、UserID、Items、Total(以分為單位的整數)與 Status(pending、paid、cancelled)。

很多人一開始寫 Go 的 HTTP 服務,第一個反射動作是去找框架。這在以前有它的道理:Go 1.22 以前,標準函式庫的 http.ServeMux 只能比對路徑前綴,不能限制 HTTP 方法,也不能從路徑取出參數,像 /orders/42 這種最常見的 RESTful 路徑,都得自己切字串。但從 Go 1.22 開始,ServeMux 支援了 GET /orders/{id} 這種寫法,方法比對、路徑萬用字元、自動回應 405 都內建了。對大多數服務來說,標準函式庫已經足夠,少一個相依套件,就少一份要追版本、要讀原始碼、要擔心停止維護的負擔。

這篇會一步一步完成以下幾件事:

  • 用 net/http 寫出最小可運作的訂單 API,理解 Handler、HandlerFunc、ResponseWriter 三個核心角色。
  • 搞懂 Go 1.22 新路由規則:方法、萬用字元、{path...}、{$} 與優先順序。
  • 理解「中介層」其實只是 func(http.Handler) http.Handler,並親手寫出請求編號、記錄、panic 復原與本文大小限制。
  • 把中介層串成一條鏈,弄清楚順序為什麼重要。
  • 設定 http.Server 的各種逾時,避免服務被慢速連線拖垮。

第 1 步:先搞懂 Handler 這個介面

net/http 整個設計的核心只有一個介面:

  • http.Handler:只有一個方法 ServeHTTP(w http.ResponseWriter, r *http.Request)。

任何型別只要實作這個方法,就能處理 HTTP 請求。伺服器收到請求後,會為每個請求開一個 goroutine,呼叫你給它的那個 Handler 的 ServeHTTP。這代表兩件事:第一,你的 handler 一定會被並發呼叫,共用的狀態必須自己加鎖或用其他同步手段保護;第二,每個請求彼此獨立,一個請求卡住不會直接卡住別人,但會佔用一個 goroutine 與一條連線。

為了不用每次都宣告一個新型別,標準函式庫提供了 http.HandlerFunc。它是一個函式型別,而且本身實作了 ServeHTTP,所以任何簽章符合的函式,轉型成 http.HandlerFunc 就變成 Handler。這個「函式也能實作介面」的小技巧,等一下寫中介層時會一直用到。

http.ResponseWriter 是你寫回應的地方,有三個方法,順序很重要:

方法作用注意事項
Header()取得回應標頭的 map必須在 WriteHeader 或第一次 Write 之前設定,之後再改不會送出
WriteHeader(code)送出狀態碼與標頭只能有效呼叫一次,第二次會在記錄裡看到 superfluous 警告
Write(b)寫入本文若還沒呼叫 WriteHeader,會自動先送出 200

最常見的初學者錯誤,就是先 Write 了一段內容,才想起要設定 Content-Type 或改狀態碼,結果客戶端收到的永遠是 200。養成「先設標頭、再寫狀態碼、最後寫本文」的順序,大部分的怪問題都不會發生。

下面是訂單服務的第一版,先全部寫在 cmd/order/main.go 一個檔案裡,資料放在記憶體的 map,重點在路由與回應的寫法;下一篇才會把它拆進 internal/order/。

package main

import (
	"encoding/json"
	"log"
	"net/http"
	"strconv"
	"sync"
)

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"` // pending / paid / cancelled
}

type store struct {
	mu     sync.Mutex
	nextID int64
	orders map[int64]Order
}

func (s *store) getOrder(w http.ResponseWriter, r *http.Request) {
	id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
	if err != nil {
		http.Error(w, "id 必須是數字", http.StatusBadRequest)
		return
	}
	s.mu.Lock()
	o, ok := s.orders[id]
	s.mu.Unlock()
	if !ok {
		http.Error(w, "找不到訂單", http.StatusNotFound)
		return
	}
	writeJSON(w, http.StatusOK, o)
}

func (s *store) createOrder(w http.ResponseWriter, r *http.Request) {
	var in Order
	if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
		http.Error(w, "JSON 格式錯誤", http.StatusBadRequest)
		return
	}
	if in.UserID <= 0 || len(in.Items) == 0 {
		http.Error(w, "user_id 與 items 為必填", http.StatusBadRequest)
		return
	}
	in.Total = 0
	for _, it := range in.Items {
		in.Total += it.Price * int64(it.Qty)
	}
	in.Status = "pending"

	s.mu.Lock()
	s.nextID++
	in.ID = s.nextID
	s.orders[in.ID] = in
	s.mu.Unlock()

	w.Header().Set("Location", "/orders/"+strconv.FormatInt(in.ID, 10))
	writeJSON(w, http.StatusCreated, in)
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.WriteHeader(status)
	if err := json.NewEncoder(w).Encode(v); err != nil {
		log.Printf("寫入回應失敗:%v", err)
	}
}

func main() {
	s := &store{orders: make(map[int64]Order)}

	mux := http.NewServeMux()
	mux.HandleFunc("GET /orders/{id}", s.getOrder)
	mux.HandleFunc("POST /orders", s.createOrder)
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("ok"))
	})

	log.Println("listening on :8080")
	log.Fatal(http.ListenAndServe(":8080", mux))
}

幾個值得注意的細節:Total 由伺服器依品項計算,不相信客戶端送來的值,而且用整數的「分」存,避免浮點數在加總時出現 0.1 + 0.2 這類誤差;新訂單一律從 pending 狀態開始;建立成功回 201 Created 並附上 Location 標頭,指向新資源的位址,這是 HTTP 語意上正確的做法;writeJSON 把「設定 Content-Type、寫狀態碼、編碼 JSON」三件事集中在一處,handler 裡就不會到處重複,也不容易寫錯順序。

可以用 curl 試一下:

go run .
curl -i -X POST localhost:8080/orders \
  -d '{"user_id":7,"items":[{"product_id":1,"qty":2,"price":600}]}'
curl -i localhost:8080/orders/1
curl -i -X DELETE localhost:8080/orders/1   # 405 Method Not Allowed,並附 Allow: GET, HEAD

提示:http.ListenAndServe 直接用了一個沒有任何逾時設定的伺服器,只適合練習。正式環境請一定要自己建立 http.Server,第 6 步會說明原因。

第 2 步:Go 1.22 的路由規則

上一步的 "GET /orders/{id}" 就是 Go 1.22 新增的路由語法。一個模式(pattern)的完整形式是 [方法] [主機]/[路徑],三個部分都可以視需要省略。

GET /orders/42 進來的請求 ServeMux 比對方法與路徑 POST /orders 方法不符,不採用 GET /orders/{id} 符合:id = "42" GET /healthz 路徑不符,不採用 handler 內以 r.PathValue("id") 取得 "42";路徑對但方法不對時回 405 並附 Allow 標頭

圖:ServeMux 同時比對方法與路徑,命中後可用 r.PathValue 取出萬用字元的值。

方法比對

模式最前面寫上方法,就只有該方法的請求會命中。有兩個貼心的預設行為:寫 GET 時,HEAD 請求也會自動命中同一個 handler(伺服器會丟掉本文,只送標頭);如果路徑有符合的模式、但方法都不對,ServeMux 會回 405 Method Not Allowed,並自動帶上 Allow 標頭列出允許的方法。以前這些都要自己寫判斷,現在全部內建。

路徑萬用字元

  • {id}:比對一整段路徑(兩個斜線之間的內容),不會跨越斜線。/orders/{id} 符合 /orders/42,但不符合 /orders/42/items。
  • {path...}:只能放在最後一段,會吃掉剩下的所有路徑,包含斜線。適合做檔案伺服或代理。
  • {$}:表示路徑必須剛好在這裡結束。/ 這個模式本來會符合所有路徑(因為它以斜線結尾,代表前綴比對),寫成 /{$} 就只符合根路徑本身。

在 handler 裡用 r.PathValue("id") 取出值,回傳的一定是字串,轉型與驗證是你的責任。值會先經過 URL 解碼,所以 %20 這類編碼不用自己處理。

優先順序與衝突

當多個模式都符合同一個請求時,ServeMux 選「最具體」的那個。所謂具體,是指它能符合的請求集合是另一個的子集合。例如 /orders/new 比 /orders/{id} 具體,所以 /orders/new 會交給前者;GET /orders/{id} 比 /orders/{id} 具體,因為多限制了方法。

如果兩個模式符合的集合互相重疊、卻沒有誰比誰具體(例如 /orders/{id} 與 /{kind}/42),註冊時就會直接 panic。這是刻意的設計:路由衝突在程式啟動時就爆出來,總比上線後某個請求莫名其妙走錯 handler 好。

模式/orders/42/orders/42/items/orders/說明
/orders/{id}符合不符合不符合萬用字元只吃一段,且不能是空的
/orders/{rest...}符合符合符合吃掉剩下所有內容,可以是空的
/orders/符合符合符合結尾斜線代表前綴比對
/orders/{$}不符合不符合符合只符合剛好 /orders/

提示:Go 1.23 起 http.Request 多了 Pattern 欄位,記錄的是實際命中的模式字串(例如 GET /orders/{id})。在記錄與指標裡用它分組,比用原始路徑好得多,因為 /orders/1 到 /orders/99999 會被歸成同一類,不會讓指標的標籤數量爆炸。

第 3 步:中介層只是一個函式

服務有了路由之後,馬上會遇到一類「每個請求都要做」的事:記錄請求花了多久、回了什麼狀態碼;給每個請求一個編號方便追查;某個 handler panic 時不要整個連線斷掉;限制上傳本文的大小;檢查驗證權杖;加上 CORS 或安全標頭。如果每個 handler 都自己做一遍,不只重複,還一定會有人忘記。

中介層(middleware)就是把這些橫切關注點抽出來的方法。在 Go 裡它沒有任何魔法,只是一個這樣的函式:

// 片段
type Middleware func(http.Handler) http.Handler

它接收「下一個」handler,回傳一個新的 handler。新的 handler 在被呼叫時,可以在呼叫下一個之前做事(例如記下開始時間)、決定要不要呼叫下一個(例如驗證失敗就直接回 401)、在下一個回來之後做事(例如計算耗時並寫記錄)。因為輸入輸出都是 http.Handler,中介層可以無限疊加,ServeMux 本身也只是一個 Handler,可以被包在最裡面。

這種一層包一層的結構常被比喻成洋蔥:請求從最外層一路往內穿過每一層,到達真正的 handler;回應再從內往外一層層穿出來。

RequestID:產生或沿用請求編號 Logging:計時、記錄狀態碼 Recover:攔下 panic LimitBody:限制本文 ServeMux → 你的 handler 請求往內 回應往外

圖:每一層中介層都包住內層,請求由外往內、回應由內往外經過同一組中介層。

理解了這個結構,有幾個推論就很自然:

  • 外層看得到內層的結果,內層看不到外層的後續動作。 記錄中介層放在 panic 復原外面,才記得到復原後寫出的 500;反過來放,panic 會直接穿過記錄層,記錄就漏掉了。
  • 任何一層都可以「短路」。 驗證中介層發現權杖無效時直接寫 401 並 return,不呼叫 next,內層完全不會執行。
  • 傳資料給內層要靠 context。 中介層可以用 r.WithContext(context.WithValue(...)) 產生新的請求往下傳,內層從 r.Context() 取值。這就是〈context:取消、逾時與資料傳遞〉裡提到的請求範圍資料,key 要用不對外公開的型別,避免和其他套件撞名。

第 4 步:攔截狀態碼,寫一個記錄中介層

記錄中介層要記下狀態碼,但 http.ResponseWriter 沒有提供「讀回剛剛寫了什麼狀態碼」的方法。標準做法是包一層自己的 ResponseWriter,把 WriteHeader 與 Write 攔下來記住,再轉交給真正的那一個。

// 片段
type statusRecorder struct {
	http.ResponseWriter
	status int
	bytes  int
}

func (r *statusRecorder) WriteHeader(code int) {
	if r.status == 0 {
		r.status = code
	}
	r.ResponseWriter.WriteHeader(code)
}

func (r *statusRecorder) Write(b []byte) (int, error) {
	if r.status == 0 {
		r.status = http.StatusOK // 沒呼叫 WriteHeader 就直接 Write,等同 200
	}
	n, err := r.ResponseWriter.Write(b)
	r.bytes += n
	return n, err
}

// Unwrap 讓 http.ResponseController 找得到底層的 Flusher 等功能。
func (r *statusRecorder) Unwrap() http.ResponseWriter { return r.ResponseWriter }

這裡用到了結構體嵌入:statusRecorder 嵌入了 http.ResponseWriter,所以 Header() 會自動轉給底層,我們只覆寫需要攔截的兩個方法。

為什麼需要 Unwrap

包裝 ResponseWriter 有一個經典的副作用:底層的 writer 往往還實作了其他介面,例如 http.Flusher(串流回應時把緩衝送出去)或 http.Hijacker(WebSocket 接管連線)。包了一層之後,外面用型別斷言 w.(http.Flusher) 就會失敗,因為 statusRecorder 自己沒有 Flush 方法。

Go 1.20 加入的 http.ResponseController 解決了這個問題:它會沿著 Unwrap() http.ResponseWriter 方法一層層往內找,直到找到支援該功能的 writer。所以只要你的包裝型別提供 Unwrap,handler 改用 http.NewResponseController(w).Flush(),就不怕被中介層擋住。這也是寫中介層時值得養成的習慣。

用 slog 記錄

Go 1.21 起標準函式庫有了結構化記錄 log/slog。比起把所有資訊拼成一行字串,結構化記錄把每個欄位分開輸出(例如 JSON),記錄平台可以直接依欄位篩選、彙總。記錄中介層的核心就是:記下開始時間、用 statusRecorder 包住 w、呼叫下一層、最後輸出方法、命中的模式、狀態碼、位元組數與耗時。完整寫法在下一步的程式裡。

提示:logger.LogAttrs 搭配 slog.String、slog.Int 這類具型別的屬性,比 logger.Info("msg", "key", value) 這種交替傳 key 與 value 的寫法少一些記憶體配置,也不會因為少寫一個參數而讓欄位錯位。熱路徑上的記錄建議用前者。

第 5 步:組出完整的中介層鏈

現在把常用的幾個中介層寫齊,再用一個小小的 Chain 函式把它們串起來:

  • RequestID:沿用上游(例如閘道)傳來的 X-Request-ID,沒有就自己產生一個,放進 context 並寫回回應標頭。之後所有記錄都帶上這個編號,就能把同一個請求在不同服務的記錄串起來。
  • Logging:上一步的記錄中介層。
  • Recover:攔下 handler 的 panic,記下堆疊並回 500,不讓單一請求的程式錯誤影響連線。
  • LimitBody:用 http.MaxBytesReader 限制請求本文大小,防止有人上傳巨大的內容把記憶體吃光。
package main

import (
	"context"
	"crypto/rand"
	"encoding/hex"
	"fmt"
	"log/slog"
	"net/http"
	"os"
	"runtime/debug"
	"time"
)

// Middleware 接收下一個 handler,回傳包好的新 handler。
type Middleware func(http.Handler) http.Handler

// Chain 依「由外到內」的順序套用:Chain(h, a, b) 等於 a(b(h))。
func Chain(h http.Handler, mws ...Middleware) http.Handler {
	for i := len(mws) - 1; i >= 0; i-- {
		h = mws[i](h)
	}
	return h
}

type ctxKey struct{}

func RequestIDFrom(ctx context.Context) string {
	id, _ := ctx.Value(ctxKey{}).(string)
	return id
}

func RequestID(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		id := r.Header.Get("X-Request-ID")
		if id == "" || len(id) > 64 {
			b := make([]byte, 8)
			rand.Read(b)
			id = hex.EncodeToString(b)
		}
		w.Header().Set("X-Request-ID", id)
		next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), ctxKey{}, id)))
	})
}

type statusRecorder struct {
	http.ResponseWriter
	status int
	bytes  int
}

func (r *statusRecorder) WriteHeader(code int) {
	if r.status == 0 {
		r.status = code
	}
	r.ResponseWriter.WriteHeader(code)
}

func (r *statusRecorder) Write(b []byte) (int, error) {
	if r.status == 0 {
		r.status = http.StatusOK
	}
	n, err := r.ResponseWriter.Write(b)
	r.bytes += n
	return n, err
}

// Unwrap 讓 http.ResponseController 找得到底層的 Flusher 等功能。
func (r *statusRecorder) Unwrap() http.ResponseWriter { return r.ResponseWriter }

func Logging(logger *slog.Logger) Middleware {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			start := time.Now()
			rec := &statusRecorder{ResponseWriter: w}
			next.ServeHTTP(rec, r)
			logger.LogAttrs(r.Context(), slog.LevelInfo, "http request",
				slog.String("request_id", RequestIDFrom(r.Context())),
				slog.String("method", r.Method),
				slog.String("pattern", r.Pattern),
				slog.Int("status", rec.status),
				slog.Int("bytes", rec.bytes),
				slog.Duration("duration", time.Since(start)),
			)
		})
	}
}

func Recover(logger *slog.Logger) Middleware {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			defer func() {
				v := recover()
				if v == nil {
					return
				}
				if v == http.ErrAbortHandler {
					panic(v) // 刻意中止連線的訊號,交還給 net/http
				}
				logger.Error("panic recovered",
					slog.String("request_id", RequestIDFrom(r.Context())),
					slog.Any("panic", v),
					slog.String("stack", string(debug.Stack())),
				)
				http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
			}()
			next.ServeHTTP(w, r)
		})
	}
}

// LimitBody 限制請求本文大小,超過時 Read 會回傳 *http.MaxBytesError。
func LimitBody(n int64) Middleware {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			r.Body = http.MaxBytesReader(w, r.Body, n)
			next.ServeHTTP(w, r)
		})
	}
}

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

	mux := http.NewServeMux()
	mux.HandleFunc("GET /orders/{id}", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "order %s\n", r.PathValue("id"))
	})
	mux.HandleFunc("GET /boom", func(w http.ResponseWriter, r *http.Request) {
		panic("示範用的 panic")
	})

	handler := Chain(mux,
		RequestID,
		Logging(logger),
		Recover(logger),
		LimitBody(1<<20),
	)

	srv := &http.Server{
		Addr:              ":8080",
		Handler:           handler,
		ReadHeaderTimeout: 5 * time.Second,
		ReadTimeout:       10 * time.Second,
		WriteTimeout:      15 * time.Second,
		IdleTimeout:       60 * time.Second,
		ErrorLog:          slog.NewLogLogger(logger.Handler(), slog.LevelError),
	}
	logger.Info("listening", slog.String("addr", srv.Addr))
	if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
		logger.Error("server stopped", slog.Any("err", err))
		os.Exit(1)
	}
}

順序怎麼排

Chain 的參數順序就是由外到內的順序,讀起來和請求經過的順序一致。這個例子的排法有它的理由:

  1. RequestID 最外層:讓後面每一層,包括記錄與 panic 復原,都拿得到請求編號。
  2. Logging 在 Recover 外面:panic 被復原成 500 之後,記錄層才看得到這個 500。如果反過來,panic 會先穿過記錄層,這筆請求就從記錄裡消失了,偏偏它是最需要被看到的那一筆。
  3. Recover 盡量靠外:它只能救到「內層」的 panic,放越外面保護範圍越大。
  4. LimitBody 靠內:它只是換掉 r.Body,放在哪裡都行,但放在讀取本文的 handler 之前即可。

驗證、授權這類會「短路」的中介層,一般放在記錄之內、handler 之外:被拒絕的請求也該被記錄下來,但不需要走進業務邏輯。另外,路由也可以分組套用:例如只有 /admin/ 底下才需要管理員驗證,可以另外建一個 ServeMux 把管理路由包起來,再掛到主 mux 上,這樣就不用把驗證邏輯寫進每一個 handler 裡。

關於 panic 復原的兩個細節

第一,net/http 其實本身就會攔截 handler 的 panic,避免整個程式結束,但它只會把堆疊印到伺服器的錯誤記錄並關掉連線,客戶端看到的是連線被重置,而不是一個像樣的 500。自己寫復原層,可以輸出結構化記錄、帶上請求編號,並回一個正常的錯誤回應。

第二,http.ErrAbortHandler 是標準函式庫約定的「刻意中止」訊號,例如反向代理發現上游斷線時會用它。復原層遇到它應該原封不動地再 panic 出去,讓 net/http 照預期中止連線,而不是把它當成程式錯誤記錄下來。

還要記得:復原層只能救到同一個 goroutine 裡的 panic。如果 handler 自己另外開了 goroutine,那個 goroutine 裡的 panic 不會被任何中介層攔下,會直接讓整個程式結束。這也是〈Goroutine、Channel 與並發模式〉強調要管理好每個 goroutine 生命週期的原因之一。

本文大小限制

http.MaxBytesReader 包住 r.Body 後,讀超過上限時會回傳 *http.MaxBytesError,handler 可以用 errors.As 判斷出來,回應 413 Request Entity Too Large。它同時會告訴伺服器在回應後關閉連線,避免繼續讀取剩下的巨大內容。範例中設定的 1 MiB 只是示意,實際上限應依 API 的需求決定;上傳檔案這類端點可以在自己的 handler 裡另外放寬。

第 6 步:設定 http.Server 的逾時

http.ListenAndServe 用的是零值的 http.Server,所有逾時都是「不限」。這在正式環境是很危險的:一個惡意或網路很差的客戶端,可以極慢地一個位元組一個位元組送標頭,佔住連線與 goroutine 不放;大量這樣的連線就能耗盡伺服器資源,這類攻擊通常被稱為 Slowloris。

一條 keep-alive 連線上的時間軸 讀取標頭 讀取本文 handler 執行並寫回應 閒置等下一個請求 ReadHeaderTimeout ReadTimeout(標頭+本文) WriteTimeout(從讀完標頭算到寫完回應) IdleTimeout

圖:四個逾時各自管連線生命週期的不同區段,WriteTimeout 從讀完標頭開始計算。

欄位涵蓋範圍沒設定的後果
ReadHeaderTimeout從連線被接受(或上一個請求結束)到讀完請求標頭慢速送標頭就能佔住連線
ReadTimeout讀完整個請求,包含標頭與本文慢速上傳本文佔住連線
WriteTimeout從讀完標頭到寫完回應客戶端不讀回應,伺服器一直等
IdleTimeoutkeep-alive 連線等待下一個請求的時間閒置連線長期累積;未設定時沿用 ReadTimeout

幾個設定上的考量:

  • ReadHeaderTimeout 幾乎一定要設,而且可以設得短,正常客戶端送標頭只需要很短的時間。靜態分析工具也常把「沒設這個欄位」標成安全問題。
  • ReadTimeout 與 WriteTimeout 是整個伺服器共用的,對所有路由一視同仁。如果某些端點需要長時間串流(例如下載大檔、Server-Sent Events),全域的 WriteTimeout 會把它們切斷。這時可以在那個 handler 裡用 http.NewResponseController(w).SetWriteDeadline(...) 個別延長,這也是第 4 步要求包裝型別提供 Unwrap 的另一個理由。
  • 逾時只會切斷連線上的讀寫,不會自動停止你的 handler。handler 該在什麼時候放棄,應該靠 r.Context():客戶端斷線時這個 context 會被取消,handler 往下呼叫資料庫或其他服務時都帶著它,工作就能及早停下。這正是前一篇 context 的用武之地。
  • 若想給「業務處理」一個明確的時間上限並回傳 503,可以用 http.TimeoutHandler 包住 handler。它會在逾時後替你寫出 503,並取消請求的 context;但 handler 自己仍要尊重 context 才會真的停下來。

範例裡的秒數只是示意,實際值要看服務的特性:純 JSON API 的回應通常很快,可以設得緊一點;有檔案上傳或報表匯出的服務就需要放寬,或者把慢的端點拆到另一個伺服器設定。至於伺服器收到關閉訊號時,如何讓進行中的請求做完再結束,會在〈設定與優雅關閉〉詳細處理。

最後,ErrorLog 欄位讓 net/http 內部的錯誤訊息(例如 TLS 交握失敗、handler panic)也走同一套 slog 記錄,slog.NewLogLogger 可以把 slog 的 handler 轉成舊式的 *log.Logger,這樣所有記錄的格式就一致了。

常見陷阱

  • 寫了本文才設標頭。 第一次 Write 就會送出狀態碼與標頭,之後再改 Header() 或呼叫 WriteHeader 都無效,記錄裡會出現 superfluous WriteHeader 的警告。
  • http.Error 之後忘了 return。 http.Error 只是寫回應,不會中止函式,後面的程式照樣執行,可能又寫一次本文或繼續做不該做的事。
  • 以為路由沒有衝突。 舊版 ServeMux 的寫法升級到 Go 1.22 後語意有變;若有相依舊行為的程式,可以暫時用 GODEBUG=httpmuxgo121=1 還原,但應盡快改寫。兩個模式重疊又分不出誰較具體時,註冊時會 panic。
  • 中介層順序放反。 記錄層放在復原層裡面,panic 的請求就不會被記錄;驗證層放在 RequestID 外面,被拒絕的請求就沒有編號可查。
  • 包裝 ResponseWriter 卻沒提供 Unwrap。 串流、SSE、WebSocket 會在加上中介層後突然失效,因為型別斷言找不到 Flusher 或 Hijacker。
  • 把 handler 當成單執行緒。 每個請求都在自己的 goroutine 裡,共用的 map、計數器都要保護,用 go test -race 很容易抓到。
  • 用 context 傳一般參數。 context 適合放請求編號、驗證過的使用者這類請求範圍的資料;handler 需要的相依物件(資料庫、服務)應該透過結構體欄位傳入,下一篇會詳細說明。
  • 直接用 http.ListenAndServe 上線。 沒有任何逾時設定,容易被慢速連線拖垮。
  • 相信客戶端送來的請求編號。 上游傳來的 X-Request-ID 要限制長度與字元,否則可能被拿來塞爆記錄或做記錄注入。

重點整理

  • net/http 的核心是 http.Handler 介面,http.HandlerFunc 讓普通函式也能當 handler;每個請求都在獨立的 goroutine 執行。
  • 回應的順序是:設定 Header()、呼叫 WriteHeader、再 Write 本文;http.Error 之後記得 return。
  • Go 1.22 起 ServeMux 支援 GET /orders/{id} 這種方法加萬用字元的模式,用 r.PathValue 取值,{path...} 吃掉剩餘路徑,{$} 表示精確結尾,路徑對但方法不對會自動回 405。
  • 多個模式同時符合時選最具體的;無法分辨時註冊就 panic,讓衝突在啟動時就曝光。
  • 中介層就是 func(http.Handler) http.Handler,可以在呼叫下一層前後做事、也可以短路;向內傳資料靠 context。
  • 包裝 ResponseWriter 來攔截狀態碼,並提供 Unwrap 讓 http.ResponseController 能找到底層功能。
  • 順序很重要:請求編號最外、記錄包住 panic 復原、驗證放在記錄之內。
  • 正式環境一定要自己建 http.Server 並設定 ReadHeaderTimeout、ReadTimeout、WriteTimeout、IdleTimeout;handler 何時停止要靠 r.Context()。

下一篇

現在訂單服務的路由、驗證、商業規則與資料存取全擠在同一個 handler 裡,既難測試、也無法替換儲存方式。〈分層架構與依賴注入〉會把它拆成 handler、service、repository 三層,並且不靠任何框架、只用建構函式把相依物件接起來。