This resume is also available in English.

三、拆成微服務第 3 / 4 篇 · 全部目錄

專欄 › 三、拆成微服務 › 第 11 篇

API Gateway:路由、認證、限流

Building an API Gateway in Go: Routing, Authentication and Rate Limiting

用標準函式庫的 httputil.ReverseProxy 從零寫一個小型 API Gateway,依序加入請求 ID、API key 與 JWT 驗證、token bucket 限流,並說明什麼時候該改用現成的 Gateway 產品。

  • Go
  • Microservices
  • API Gateway
這篇的步驟
  1. 這篇要解決什麼
  2. 第 1 步:用 ReverseProxy 做路由
  3. 第 2 步:替每個請求加上請求 ID
  4. 第 3 步:認證:API key 與 JWT
  5. 第 4 步:用 token bucket 限流
  6. 第 5 步:組裝成完整的 Gateway
  7. 第 6 步:多個 Gateway 實例與分散式限流
  8. 第 7 步:什麼時候該用現成的 Gateway
  9. 常見陷阱
  10. 重點整理
  11. 下一篇

上一篇〈gRPC 與 Protocol Buffers〉讓 order、payment、inventory 之間有了型別安全的內部通訊。這篇接著處理系統的「大門」:瀏覽器、手機 App 與外部合作夥伴從哪裡進來?誰來檢查他們是誰、限制他們打多快?答案是放在所有服務前面的 api-gateway。

這篇要解決什麼

拆成多個服務之後,如果讓外部用戶端直接呼叫每個服務,會出現幾個問題:

  • 用戶端要知道每個服務的位址,內部一調整,所有用戶端都要改。
  • 每個服務都要自己實作認證、限流、CORS、請求日誌,重複又容易不一致。
  • 內部服務直接暴露在網路上,攻擊面變大。

API Gateway 是一個反向代理,站在所有服務前面,負責「跟業務無關、但每個請求都需要」的工作:

職責說明
路由依路徑把請求轉給對應的內部服務
認證確認呼叫者是誰(API key、JWT 等)
限流限制每個呼叫者的請求速率,保護後端
請求 ID替每個請求產生唯一 ID,串起跨服務的日誌
其他TLS 終止、CORS、壓縮、協定轉換(例如 HTTP/JSON 轉 gRPC)

〈什麼時候該拆:邊界與拆分策略〉裡的絞殺者路由層,其實就是一個最陽春的 Gateway。這篇把它擴充成一個能用的版本,全部只用標準函式庫,並在最後討論什麼時候該改用現成產品。

提示:Gateway 只做「橫切」的事,不放業務邏輯。一旦 Gateway 開始知道「訂單金額超過多少要額外檢查」,它就變成了一個所有團隊都要改、誰都不敢動的瓶頸。

第 1 步:用 ReverseProxy 做路由

Go 標準函式庫的 net/http/httputil.ReverseProxy 已經處理好反向代理最麻煩的部分:轉發請求本文與回應、移除不該轉發的 hop-by-hop 標頭(例如 Connection)、處理串流回應與連線重用。

從 Go 1.20 起,建議用 Rewrite 欄位取代舊的 Director 來改寫請求。差別在於 Rewrite 同時拿得到原始請求(pr.In)與要送出的請求(pr.Out),而且呼叫 Rewrite 之前,hop-by-hop 標頭已經被移除,用戶端無法利用 Connection 標頭偷偷讓 Gateway 刪掉你加的標頭。

路由表用一個簡單的切片描述:

對外路徑內部服務
/api/orders/order
/api/payments/payment
/api/inventory/inventory

每一條路由建立一個 ReverseProxy,註冊到 http.ServeMux。ServeMux 以「最長前綴」比對路徑,所以 /api/orders/123 會落到 /api/orders/。在 Rewrite 裡我們做三件事:pr.SetURL(target) 把目的地改成內部服務、pr.SetXForwarded() 設定 X-Forwarded-For 等標頭讓後端知道原始用戶端是誰,以及處理身分標頭(第 3 步說明)。

另外一定要設定 ErrorHandler。後端連不上或逾時時,預設行為只會回一個空白的 502;自訂之後可以記錄是哪個請求、哪個服務出問題,回應也能統一格式。

在範例裡,內部服務的位址先寫成本機的連接埠,方便在開發機上跑;部署時會改成服務名稱,例如 Docker Compose 或 Kubernetes 裡的 http://order:8080,那是〈服務發現與負載平衡〉要談的問題。

第 2 步:替每個請求加上請求 ID

一個使用者操作可能經過 Gateway、order、inventory、payment 四個服務,每個服務各自寫日誌。出問題時,你需要一個共同的鍵把這些日誌串起來,這就是請求 ID。

中介層的寫法和〈net/http 與中介層〉一樣:包住下一個 handler,在前後做事。規則是:

  1. 如果請求已經帶了 X-Request-ID(例如從更外層的負載平衡器來),沿用它;但要限制長度,避免有人塞進超長字串污染日誌。
  2. 沒有就用 crypto/rand 產生一個。
  3. 寫回請求標頭(往下游傳)與回應標頭(讓用戶端回報問題時可以附上)。
  4. 請求結束後用 log/slog 記一行結構化日誌:ID、方法、路徑、耗時。

下游的 Go 服務收到後,把它放進 context,往 gRPC 呼叫傳時再放進 metadata,就是上一篇攔截器範例做的事。之後在〈可觀測性:日誌、指標、追蹤〉,這個角色會由 OpenTelemetry 的 trace ID 接手,但「入口產生、一路傳遞」的原則不變。

第 3 步:認證:API key 與 JWT

Gateway 最重要的工作之一,是在請求抵達內部服務之前確認「你是誰」。範例支援兩種常見方式:

API key:適合伺服器對伺服器的整合,例如合作夥伴的系統。用戶端在 X-API-Key 標頭帶一把長字串,Gateway 查表確認對應的用戶。比對時要用 crypto/subtle.ConstantTimeCompare,避免攻擊者從比對時間的差異猜出金鑰。實務上,資料庫裡應該只存金鑰的雜湊值,而不是明文。

JWT(JSON Web Token):適合使用者登入後的請求。JWT 由三段 base64url 字串組成:標頭、內容(claims)、簽章。Gateway 驗證簽章正確、未過期後,就信任裡面的 sub(使用者 ID)。範例實作了 HS256(HMAC-SHA256)驗證,重點是:

  • 只接受預期的演算法。標頭裡的 alg 是攻擊者可以控制的;歷史上有不少漏洞是驗證程式「照標頭說的演算法驗」,結果被改成 none 或換成別的演算法就繞過了。範例直接拒絕 HS256 以外的值。
  • 用 hmac.Equal 比較簽章,它是常數時間比較。
  • 檢查 exp,過期就拒絕。正式環境通常還會檢查 iss(簽發者)、aud(受眾)與 nbf。

提示:範例為了只用標準函式庫,自己寫了 HS256 驗證。正式專案建議使用成熟的 JWT 函式庫,並優先考慮 RS256 或 ES256 這類非對稱演算法:只有認證服務持有私鑰,Gateway 只需要公鑰,即使 Gateway 被入侵也無法簽發新 token。

驗證通過後,Gateway 把使用者 ID 放進 context,在 Rewrite 裡寫成 X-User-ID 標頭傳給後端。這裡有一個關鍵的安全細節:先刪掉用戶端自己帶來的 X-User-ID,再寫入驗證過的值。否則攻擊者只要在請求裡加一行 X-User-ID: admin,後端就會相信他。同樣地,後端服務只應該接受來自 Gateway 的流量(用網路政策或 mTLS 限制),否則有人繞過 Gateway 直接打後端,這個標頭依然可以偽造。

認證失敗回傳 401 Unauthorized 並附上 WWW-Authenticate 標頭。注意「認證」(你是誰)和「授權」(你能做什麼)是兩回事:Gateway 適合做認證與粗粒度的授權(例如某個 API key 只能呼叫唯讀端點),而「這筆訂單是不是你的」這種細粒度判斷,屬於 order 服務自己的業務邏輯。

第 4 步:用 token bucket 限流

限流保護後端不被單一呼叫者的突發流量打垮,也是對外 API 公平使用的基礎。最常用的演算法是 token bucket(令牌桶):

  • 每個呼叫者有一個桶子,容量是 burst。
  • 桶子以固定速率 rate 補充 token,最多補到滿。
  • 每個請求要拿走一個 token;拿得到就放行,拿不到就回 429 Too Many Requests。
每秒補 5 個(示意) 容量 10 桶子(每位用戶一個) 請求 拿 1 個 token 有 token 放行 沒有 token 429+Retry-After

圖:桶子以固定速率補 token,每個請求拿走一個;桶子空了就回 429,並用 Retry-After 告訴用戶端多久後再試。

token bucket 的好處是同時控制兩件事:長期平均速率(rate)與可容忍的瞬間突發(burst)。例如設定每秒 5 個、容量 10(數字僅為示意),用戶端可以瞬間送出 10 個請求,之後就只能以每秒 5 個的速度繼續。

實作上不需要真的用計時器每秒往桶子裡放 token。只要記住上次更新的時間,每次有請求進來時,依「經過的秒數 × rate」一次補上,再判斷夠不夠,這種「惰性補充」的寫法只需要一把互斥鎖與幾行算術。拿不到 token 時,還可以算出還要等多久才會有下一個 token,放進 Retry-After 標頭。

另外兩個細節:

  • 以誰為單位限流:範例以認證後的使用者為單位,所以要放在認證之後。未登入的端點則常以來源 IP 為單位,但要注意 NAT 後面可能有很多使用者共用同一個 IP。
  • 記憶體回收:每個用戶一個桶子,map 會一直長大。範例用一個背景 goroutine 定期刪除閒置太久的桶子;桶子被刪掉後再出現,只是重新拿到一個滿的桶,對正確性沒有影響。

其他常見的演算法還有固定視窗(實作最簡單,但視窗交界處可能放行兩倍流量)、滑動視窗(較精確,成本較高)與 leaky bucket(輸出速率固定,適合整形流量)。對 API 限流來說,token bucket 通常是最平衡的選擇。如果不介意多一個依賴,golang.org/x/time/rate 提供了現成且經過充分測試的 token bucket 實作。

第 5 步:組裝成完整的 Gateway

把前面四步組起來,中介層的順序是:請求 ID → 認證 → 限流 → 路由。順序有它的道理:請求 ID 要最外層,連被拒絕的請求都有 ID 可查;認證要在限流之前,才知道要扣誰的桶子;被擋下的請求在 Gateway 就結束,不會浪費後端的資源。

用戶端 API Gateway 請求 ID 產生或沿用 認證 API key/JWT 限流 token bucket 路由 反向代理 訂單服務 付款服務 庫存服務 401/429 在這裡就擋掉 不會打到後端

圖:請求依序經過請求 ID、認證、限流與路由;未通過認證或超過速率的請求在 Gateway 就被擋下,不會打到後端。

完整程式如下,只用標準函式庫,可以直接 go run:

// 一個只用標準函式庫的小型 API Gateway:
// 請求 ID → 認證(API key 或 HS256 JWT)→ 限流(每個用戶一個 token bucket)→ 反向代理。
package main

import (
	"context"
	"crypto/hmac"
	"crypto/rand"
	"crypto/sha256"
	"crypto/subtle"
	"encoding/base64"
	"encoding/hex"
	"encoding/json"
	"errors"
	"log/slog"
	"math"
	"net/http"
	"net/http/httputil"
	"net/url"
	"os"
	"strconv"
	"strings"
	"sync"
	"time"
)

// ---------- 1. 路由表 ----------

type route struct {
	prefix   string // 對外路徑前綴,例如 /api/orders/
	upstream string // 內部服務位址
}

var routes = []route{
	{"/api/orders/", "http://127.0.0.1:9001"},
	{"/api/payments/", "http://127.0.0.1:9002"},
	{"/api/inventory/", "http://127.0.0.1:9003"},
}

func newProxy(target *url.URL) *httputil.ReverseProxy {
	return &httputil.ReverseProxy{
		Rewrite: func(pr *httputil.ProxyRequest) {
			pr.SetURL(target)
			pr.SetXForwarded()
			// Rewrite 收到的 Out 已移除 hop-by-hop 標頭;這裡再把身分改成 gateway 驗證過的值。
			pr.Out.Header.Del("X-User-ID")
			if uid, ok := pr.In.Context().Value(userKey{}).(string); ok {
				pr.Out.Header.Set("X-User-ID", uid)
			}
		},
		ErrorHandler: func(w http.ResponseWriter, r *http.Request, err error) {
			slog.Error("upstream error", "path", r.URL.Path, "err", err,
				"request_id", r.Header.Get("X-Request-ID"))
			http.Error(w, "bad gateway", http.StatusBadGateway)
		},
	}
}

// ---------- 2. 請求 ID ----------

func withRequestID(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)
		}
		r.Header.Set("X-Request-ID", id) // 往下游傳
		w.Header().Set("X-Request-ID", id)
		start := time.Now()
		next.ServeHTTP(w, r)
		slog.Info("request", "id", id, "method", r.Method, "path", r.URL.Path,
			"dur", time.Since(start))
	})
}

// ---------- 3. 認證 ----------

type userKey struct{}

var (
	jwtSecret = []byte(envOr("JWT_SECRET", "dev-only-secret"))
	apiKeys   = map[string]string{ // key → 用戶;實務上放在資料庫或密鑰服務
		envOr("DEMO_API_KEY", "demo-key-123"): "partner-a",
	}
	errUnauthorized = errors.New("unauthorized")
)

func authenticate(r *http.Request) (string, error) {
	if key := r.Header.Get("X-API-Key"); key != "" {
		for k, user := range apiKeys {
			if subtle.ConstantTimeCompare([]byte(k), []byte(key)) == 1 {
				return user, nil
			}
		}
		return "", errUnauthorized
	}
	token, ok := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ")
	if !ok {
		return "", errUnauthorized
	}
	return verifyHS256(token, time.Now())
}

// verifyHS256 只接受 alg=HS256,並檢查簽章與 exp。
func verifyHS256(token string, now time.Time) (string, error) {
	parts := strings.Split(token, ".")
	if len(parts) != 3 {
		return "", errUnauthorized
	}
	var header struct {
		Alg string `json:"alg"`
	}
	if err := decodeSegment(parts[0], &header); err != nil || header.Alg != "HS256" {
		return "", errUnauthorized
	}
	mac := hmac.New(sha256.New, jwtSecret)
	mac.Write([]byte(parts[0] + "." + parts[1]))
	sig, err := base64.RawURLEncoding.DecodeString(parts[2])
	if err != nil || !hmac.Equal(sig, mac.Sum(nil)) {
		return "", errUnauthorized
	}
	var claims struct {
		Sub string `json:"sub"`
		Exp int64  `json:"exp"`
	}
	if err := decodeSegment(parts[1], &claims); err != nil {
		return "", errUnauthorized
	}
	if claims.Sub == "" || now.Unix() >= claims.Exp {
		return "", errUnauthorized
	}
	return claims.Sub, nil
}

func decodeSegment(seg string, v any) error {
	b, err := base64.RawURLEncoding.DecodeString(seg)
	if err != nil {
		return err
	}
	return json.Unmarshal(b, v)
}

// ---------- 4. 限流:token bucket ----------

type bucket struct {
	tokens float64
	last   time.Time
}

type limiter struct {
	mu      sync.Mutex
	rate    float64 // 每秒補幾個 token
	burst   float64 // 桶子容量
	buckets map[string]*bucket
}

func newLimiter(rate, burst float64) *limiter {
	l := &limiter{rate: rate, burst: burst, buckets: map[string]*bucket{}}
	go l.cleanup(time.Minute)
	return l
}

// allow 回傳是否放行,以及不放行時建議等多久。
func (l *limiter) allow(key string, now time.Time) (bool, time.Duration) {
	l.mu.Lock()
	defer l.mu.Unlock()
	b, ok := l.buckets[key]
	if !ok {
		b = &bucket{tokens: l.burst, last: now}
		l.buckets[key] = b
	}
	// 依經過時間補 token,最多補滿 burst
	b.tokens = math.Min(l.burst, b.tokens+now.Sub(b.last).Seconds()*l.rate)
	b.last = now
	if b.tokens >= 1 {
		b.tokens--
		return true, 0
	}
	wait := time.Duration((1 - b.tokens) / l.rate * float64(time.Second))
	return false, wait
}

// cleanup 移除閒置太久的桶,避免 map 無限長大。
func (l *limiter) cleanup(every time.Duration) {
	for range time.Tick(every) {
		l.mu.Lock()
		for k, b := range l.buckets {
			if time.Since(b.last) > every {
				delete(l.buckets, k)
			}
		}
		l.mu.Unlock()
	}
}

// ---------- 5. 組起來 ----------

func gateway(lim *limiter) http.Handler {
	mux := http.NewServeMux()
	for _, rt := range routes {
		u, err := url.Parse(rt.upstream)
		if err != nil {
			panic(err)
		}
		mux.Handle(rt.prefix, newProxy(u))
	}
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) {
		w.Write([]byte("ok"))
	})

	protected := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if r.URL.Path == "/healthz" {
			mux.ServeHTTP(w, r)
			return
		}
		user, err := authenticate(r)
		if err != nil {
			w.Header().Set("WWW-Authenticate", `Bearer realm="api"`)
			http.Error(w, "unauthorized", http.StatusUnauthorized)
			return
		}
		if ok, wait := lim.allow(user, time.Now()); !ok {
			w.Header().Set("Retry-After", strconv.Itoa(int(math.Ceil(wait.Seconds()))))
			http.Error(w, "too many requests", http.StatusTooManyRequests)
			return
		}
		r = r.WithContext(context.WithValue(r.Context(), userKey{}, user))
		mux.ServeHTTP(w, r)
	})
	return withRequestID(protected)
}

func envOr(key, def string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return def
}

func main() {
	lim := newLimiter(5, 10) // 每秒 5 個、最多連發 10 個(示意數字)
	srv := &http.Server{
		Addr:              envOr("ADDR", ":8080"),
		Handler:           gateway(lim),
		ReadHeaderTimeout: 5 * time.Second,
		IdleTimeout:       60 * time.Second,
	}
	slog.Info("gateway listening", "addr", srv.Addr)
	if err := srv.ListenAndServe(); err != nil {
		slog.Error("server stopped", "err", err)
		os.Exit(1)
	}
}

伺服器本身也要設定逾時:ReadHeaderTimeout 防止有人慢慢送標頭佔住連線(Slowloris 攻擊),IdleTimeout 回收閒置的 keep-alive 連線。/healthz 不需要認證,給負載平衡器或 Kubernetes 做健康檢查。

在本機試跑:先在 9001 埠起一個任何會回應的 HTTP 服務當作 order,再啟動 Gateway,用 curl 驗證各種情境:

go run .   # Gateway 監聽 :8080

# 沒有憑證:401
curl -i localhost:8080/api/orders/1

# API key:轉給 order,後端收到 X-User-ID: partner-a 與 X-Request-ID
curl -i localhost:8080/api/orders/1 -H "X-API-Key: demo-key-123"

# 偽造身分標頭沒有用:Gateway 會改寫成驗證過的使用者
curl -i localhost:8080/api/orders/1 -H "X-API-Key: demo-key-123" -H "X-User-ID: admin"

# 連續打 12 次:前 10 次 200,之後 429 並帶 Retry-After
for i in $(seq 1 12); do
  curl -s -o /dev/null -w "%{http_code} " localhost:8080/api/orders/1 -H "X-API-Key: demo-key-123"
done; echo

# 後端沒啟動的路由:502,Gateway 的日誌會記下 request_id
curl -i localhost:8080/api/payments/1 -H "X-API-Key: demo-key-123"

這個 Gateway 的每一塊都可以用〈測試:表格驅動、httptest、整合測試〉的方法測試:用 httptest.NewServer 起一個假後端,把 routes 指過去,再用表格列出「有無憑證、是否過期、是否超過速率」各種組合,檢查狀態碼與後端收到的標頭。limiter.allow 接受 now 參數,所以測試時可以直接傳入假時間,不必真的等待。

第 6 步:多個 Gateway 實例與分散式限流

Gateway 是所有流量的入口,不能只跑一個實例。但多個實例時,上面的記憶體內限流就有問題:每個實例各自記帳,三個實例等於把限額放大成三倍。

常見的處理方式:

做法說明取捨
每個實例分攤限額總限額除以實例數最簡單;但實例數變動、流量分配不均時不精確
黏性路由讓同一個用戶總是落在同一個實例不需共享狀態;實例增減時會重新分配
集中式計數用 Redis 等共享儲存記帳,以原子操作或腳本扣 token精確;多一次網路往返,且 Redis 本身成為依賴
兩層限流本地先粗略擋,集中式再精確控制兼顧效能與精確度,實作較複雜

大多數情況下,限流不需要絕對精確,它的目的是保護系統,不是計費。從「每個實例分攤」開始,真的有精確需求時再引入集中式計數。若改用集中式計數,也要決定 Redis 掛掉時要「放行」還是「拒絕」,通常選擇放行並告警,避免限流元件本身變成整個系統的單點故障。

同樣的思考也適用於其他狀態:JWT 驗證不需要共享狀態(這正是它受歡迎的原因之一),但如果要支援「立即撤銷 token」,就需要一份共享的黑名單,或改用較短的有效期限搭配更新機制。

第 7 步:什麼時候該用現成的 Gateway

自己寫 Gateway 的價值在於理解它在做什麼,以及在需求很簡單時保持輕量。但正式環境往往會需要更多功能:

  • TLS 憑證自動更新、HTTP/2 與 HTTP/3
  • HTTP/JSON 與 gRPC 的轉換(例如 grpc-gateway 或 Envoy 的轉碼功能)
  • 動態設定:不重新部署就能新增路由或調整限額
  • 熔斷、重試、金絲雀發佈與流量鏡像
  • 完整的指標、追蹤與存取日誌
  • 管理介面、開發者入口網站、API key 申請流程

這些功能自己寫不是不行,但每一項都需要長期維護。常見的現成選擇有 Envoy、NGINX、Kong、Traefik,以及各雲端平台的託管 API Gateway。在 Kubernetes 裡,則可以透過 Gateway API 用宣告式設定描述路由,由實作它的控制器(例如 Envoy Gateway、Istio 等)負責實際轉發:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop-api
  namespace: shop
spec:
  parentRefs:
    - name: public-gateway # 由叢集管理者建立的 Gateway
  rules:
    - matches:
        - path: { type: PathPrefix, value: /api/orders }
      backendRefs:
        - name: order # Kubernetes Service 名稱
          port: 8080
    - matches:
        - path: { type: PathPrefix, value: /api/payments }
      backendRefs:
        - name: payment
          port: 8080

判斷的方式可以很實際:

情況建議
少數幾個服務、規則簡單、團隊熟悉 Go自己寫的小 Gateway 足夠,也最容易客製
需要協定轉換、動態設定、進階流量控制現成的 Gateway 產品
已經在 Kubernetes 上Gateway API 或 Ingress 控制器,業務相關的檢查留在服務內
對外開放 API 給大量第三方有開發者入口與金鑰管理的 API 管理平台

也可以混合使用:現成的 Gateway 負責 TLS、路由與粗粒度限流,一個小型的 Go 服務負責特別的認證邏輯,透過外部授權(external authorization)的機制串接。

常見陷阱

  • 信任用戶端帶來的身分標頭:沒有先刪除用戶端自己帶的 X-User-ID,攻擊者就能冒充任何人。後端也必須只接受來自 Gateway 的流量。
  • JWT 照標頭的 alg 驗證:一定要寫死允許的演算法,拒絕 none 與其他意外的值。
  • 用一般的字串比較驗證金鑰:用 subtle.ConstantTimeCompare 或 hmac.Equal,避免時序攻擊。
  • 在 Gateway 放業務邏輯:Gateway 會變成所有團隊的瓶頸,部署風險也集中在一處。
  • Gateway 沒有設逾時:沒有 ReadHeaderTimeout 容易被慢速攻擊佔滿連線;後端呼叫也要有逾時,避免一個慢服務拖垮整個入口。
  • 限流的 map 無限長大:每個新用戶或新 IP 都新增一個桶,沒有清理就會記憶體洩漏。
  • 多實例下沿用單機限流卻以為是總限額:實際放行量是限額乘以實例數。
  • Gateway 只有一個實例:它是所有流量的入口,單點故障就是整個系統故障。
  • 把錯誤細節回給用戶端:後端的錯誤訊息、堆疊或內部位址不應該透過 Gateway 洩漏出去,統一回傳簡短的錯誤並附上請求 ID。

重點整理

  • API Gateway 是站在所有服務前面的反向代理,集中處理路由、認證、限流、請求 ID 等橫切工作,不放業務邏輯。
  • httputil.ReverseProxy 搭配 Rewrite 就能完成路由,並自訂 ErrorHandler 處理後端失敗。
  • 請求 ID 在入口產生或沿用、限制長度,寫入請求與回應標頭,一路往下游傳。
  • 認證支援 API key(常數時間比較)與 JWT(固定演算法、驗簽章、檢查 exp);驗證後覆寫身分標頭,絕不信任用戶端帶來的值。
  • token bucket 用惰性補充實作,同時控制平均速率與突發量,拒絕時回 429 與 Retry-After;記得清理閒置的桶。
  • 中介層順序:請求 ID → 認證 → 限流 → 路由。
  • 多實例時要重新思考限流;需求變複雜時,改用 Envoy、Kong 或 Kubernetes Gateway API 等現成方案。

下一篇

Gateway 的路由表目前寫死了每個服務的位址,但服務會擴充成多個實例、會重新部署、IP 也會改變。下一篇〈服務發現與負載平衡〉會說明怎麼讓呼叫端隨時找到健康的實例,並把請求平均分配出去。