《后端架构设计·演进与治理》4.1 边缘网关：路由、认证与租户限流

// file: internal/platform/gateway/gateway.go
// tier: L1
// verify: go test ./internal/platform/gateway/ -count=1
package gateway

import (
	"errors"
	"fmt"
	"strings"
	"sync"
	"time"
)

type Route struct {
	ID, Method, Path, Scope string
	TenantScoped            bool
	Cost                    int
}

type Router struct{ routes []Route }

func NewRouter(routes []Route) (*Router, error) {
	seen := map[string]bool{}
	for _, r := range routes {
		if r.ID == "" || r.Method == "" || r.Path == "" {
			return nil, errors.New("gateway: route id, method and path are required")
		}
		if seen[r.ID] {
			return nil, fmt.Errorf("gateway: duplicate route id %q", r.ID)
		}
		seen[r.ID] = true
		if !strings.HasPrefix(r.Path, "/") {
			return nil, fmt.Errorf("gateway: route %q path must start with /", r.ID)
		}
	}
	return &Router{routes: routes}, nil
}

func splitPath(p string) []string {
	if p = strings.Trim(p, "/"); p == "" {
		return nil
	}
	return strings.Split(p, "/")
}

func (r *Router) Match(method, path string) (Route, map[string]string, bool) {
	segs := splitPath(path)
	for _, route := range r.routes {
		want := splitPath(route.Path)
		if route.Method != method || len(want) != len(segs) {
			continue
		}
		params, ok := map[string]string{}, true
		for i, w := range want {
			if name, capture := strings.CutPrefix(w, "{"); capture && strings.HasSuffix(name, "}") {
				name = strings.TrimSuffix(name, "}")
				if name == "" || segs[i] == "" {
					ok = false
					break
				}
				params[name] = segs[i]
			} else if w != segs[i] {
				ok = false
				break
			}
		}
		if ok {
			return route, params, true
		}
	}
	return Route{}, nil, false
}

// Principal is the authenticated caller. TenantID comes from the credential,
// never from a request header.
type Principal struct {
	TenantID string
	Scopes   map[string]bool
}

type TokenResolver func(token string) (Principal, bool)

type TenantRateLimiter struct {
	mu      sync.Mutex
	rate    float64
	burst   float64
	buckets map[string]*bucket
	now     func() time.Time
}
type bucket struct {
	tokens float64
	last   time.Time
}

func NewTenantRateLimiter(ratePerSecond float64, burst int) (*TenantRateLimiter, error) {
	return newTenantRateLimiter(ratePerSecond, burst, time.Now)
}

func newTenantRateLimiter(rate float64, burst int, now func() time.Time) (*TenantRateLimiter, error) {
	if rate <= 0 || burst < 1 {
		return nil, errors.New("gateway: rate must be positive and burst at least 1")
	}
	return &TenantRateLimiter{rate: rate, burst: float64(burst), buckets: map[string]*bucket{}, now: now}, nil
}

func (l *TenantRateLimiter) Allow(tenant string, cost int) (bool, int) {
	if cost <= 0 {
		cost = 1
	}
	l.mu.Lock()
	defer l.mu.Unlock()
	now := l.now()
	b := l.buckets[tenant]
	if b == nil {
		b = &bucket{tokens: l.burst, last: now}
		l.buckets[tenant] = b
	}
	if e := now.Sub(b.last).Seconds(); e > 0 {
		b.tokens = min(l.burst, b.tokens+e*l.rate)
		b.last = now
	}
	if b.tokens < float64(cost) {
		return false, int(b.tokens)
	}
	b.tokens -= float64(cost)
	return true, int(b.tokens)
}

// Request has no tenant field on purpose: the tenant is derived from Token.
type Request struct{ Method, Path, Token string }

type Decision struct {
	Status    int
	RouteID   string
	Tenant    string
	Remaining int
	Reason    string
}

type Gateway struct {
	router  *Router
	resolve TokenResolver
	limiter *TenantRateLimiter
}

func NewGateway(router *Router, resolve TokenResolver, limiter *TenantRateLimiter) *Gateway {
	return &Gateway{router, resolve, limiter}
}

func (g *Gateway) Serve(req Request) Decision {
	route, _, ok := g.router.Match(req.Method, req.Path)
	if !ok {
		return Decision{Status: 404, Reason: "no route"}
	}
	p, ok := g.resolve(req.Token)
	if !ok {
		return Decision{Status: 401, RouteID: route.ID, Reason: "invalid token"}
	}
	if route.Scope != "" && !p.Scopes[route.Scope] {
		return Decision{Status: 403, RouteID: route.ID, Tenant: p.TenantID, Reason: "missing scope"}
	}
	if route.TenantScoped && p.TenantID == "" {
		return Decision{Status: 403, RouteID: route.ID, Reason: "tenant claim required"}
	}
	ok, remaining := g.limiter.Allow(p.TenantID, route.Cost)
	if !ok {
		return Decision{Status: 429, RouteID: route.ID, Tenant: p.TenantID, Remaining: remaining, Reason: "tenant quota exhausted"}
	}
	return Decision{Status: 200, RouteID: route.ID, Tenant: p.TenantID, Remaining: remaining}
}

// file: internal/platform/gateway/gateway_test.go
// tier: L1
// verify: go test ./internal/platform/gateway/ -count=1
package gateway

import (
	"testing"
	"time"
)

func gwRouter(t *testing.T) *Router {
	r, err := NewRouter([]Route{
		{ID: "create-order", Method: "POST", Path: "/v1/orders", Scope: "orders:write", TenantScoped: true},
		{ID: "get-order", Method: "GET", Path: "/v1/orders/{orderID}", Scope: "orders:read", TenantScoped: true},
		{ID: "admin-metrics", Method: "GET", Path: "/v1/admin/metrics", Scope: "admin:read"},
	})
	if err != nil {
		t.Fatalf("NewRouter: %v", err)
	}
	return r
}

func gwGateway(t *testing.T, burst int) *Gateway {
	tokens := map[string]Principal{
		"read-a":    {TenantID: "tenant-a", Scopes: map[string]bool{"orders:read": true}},
		"write-a":   {TenantID: "tenant-a", Scopes: map[string]bool{"orders:write": true}},
		"write-b":   {TenantID: "tenant-b", Scopes: map[string]bool{"orders:write": true}},
		"no-tenant": {Scopes: map[string]bool{"orders:write": true, "admin:read": true}},
	}
	resolve := func(token string) (Principal, bool) { p, ok := tokens[token]; return p, ok }
	lim, err := NewTenantRateLimiter(1, burst)
	if err != nil {
		t.Fatalf("NewTenantRateLimiter: %v", err)
	}
	return NewGateway(gwRouter(t), resolve, lim)
}

func TestRouterMatch(t *testing.T) {
	r := gwRouter(t)
	cases := []struct {
		method, path, want, param string
		ok                        bool
	}{
		{"POST", "/v1/orders", "create-order", "", true},
		{"POST", "/v1/orders/", "create-order", "", true},
		{"GET", "/v1/orders/o-42", "get-order", "o-42", true},
		{"DELETE", "/v1/orders", "", "", false},
		{"GET", "/v1/orders/o-42/items", "", "", false},
		{"GET", "/V1/orders/o-42", "", "", false},
	}
	for _, tc := range cases {
		route, params, ok := r.Match(tc.method, tc.path)
		if ok != tc.ok || (ok && (route.ID != tc.want || (tc.param != "" && params["orderID"] != tc.param))) {
			t.Fatalf("%s %s: ok=%v route=%s params=%v", tc.method, tc.path, ok, route.ID, params)
		}
	}
}

func TestGatewayStageOrder(t *testing.T) {
	g := gwGateway(t, 100)
	cases := []struct {
		name   string
		req    Request
		status int
		tenant string
	}{
		{"unknown route", Request{Method: "GET", Path: "/v1/nope", Token: "read-a"}, 404, ""},
		{"missing token", Request{Method: "POST", Path: "/v1/orders"}, 401, ""},
		{"missing scope", Request{Method: "POST", Path: "/v1/orders", Token: "read-a"}, 403, "tenant-a"},
		{"tenant required", Request{Method: "POST", Path: "/v1/orders", Token: "no-tenant"}, 403, ""},
		{"allowed", Request{Method: "GET", Path: "/v1/orders/o-1", Token: "read-a"}, 200, "tenant-a"},
		{"not tenant scoped", Request{Method: "GET", Path: "/v1/admin/metrics", Token: "no-tenant"}, 200, ""},
	}
	for _, tc := range cases {
		d := g.Serve(tc.req)
		if d.Status != tc.status || d.Tenant != tc.tenant {
			t.Fatalf("%s: status=%d tenant=%q want %d/%q (%s)", tc.name, d.Status, d.Tenant, tc.status, tc.tenant, d.Reason)
		}
	}
}

func TestTenantLimiterIsolation(t *testing.T) {
	now := time.Date(2026, 10, 28, 9, 30, 0, 0, time.UTC)
	lim, err := newTenantRateLimiter(1, 2, func() time.Time { return now })
	if err != nil {
		t.Fatalf("newTenantRateLimiter: %v", err)
	}
	for i := 0; i < 2; i++ {
		if ok, _ := lim.Allow("tenant-a", 1); !ok {
			t.Fatalf("tenant-a request %d should pass", i+1)
		}
	}
	if ok, remaining := lim.Allow("tenant-a", 1); ok || remaining != 0 {
		t.Fatalf("third tenant-a: ok=%v remaining=%d want false/0", ok, remaining)
	}
	if ok, remaining := lim.Allow("tenant-b", 1); !ok || remaining != 1 {
		t.Fatalf("tenant-b must be isolated: ok=%v remaining=%d", ok, remaining)
	}
	now = now.Add(time.Second)
	if ok, remaining := lim.Allow("tenant-a", 1); !ok || remaining != 0 {
		t.Fatalf("after refill: ok=%v remaining=%d", ok, remaining)
	}
}

func TestGatewayQuotaIsPerTenant(t *testing.T) {
	g := gwGateway(t, 1)
	if d := g.Serve(Request{Method: "POST", Path: "/v1/orders", Token: "write-a"}); d.Status != 200 {
		t.Fatalf("first request status=%d want 200", d.Status)
	}
	if d := g.Serve(Request{Method: "POST", Path: "/v1/orders", Token: "write-a"}); d.Status != 429 || d.Tenant != "tenant-a" {
		t.Fatalf("second request status=%d tenant=%q want 429 tenant-a", d.Status, d.Tenant)
	}
	if d := g.Serve(Request{Method: "POST", Path: "/v1/orders", Token: "write-b"}); d.Status != 200 {
		t.Fatalf("tenant-b status=%d want 200", d.Status)
	}
}

$ go test ./internal/platform/gateway/ -run 'TestRouterMatch|TestGateway|TestTenantLimiter' -count=1 -v
=== RUN   TestRouterMatch
--- PASS: TestRouterMatch (0.00s)
=== RUN   TestGatewayStageOrder
--- PASS: TestGatewayStageOrder (0.00s)
=== RUN   TestTenantLimiterIsolation
--- PASS: TestTenantLimiterIsolation (0.00s)
=== RUN   TestGatewayQuotaIsPerTenant
--- PASS: TestGatewayQuotaIsPerTenant (0.00s)
PASS
ok  	archlab/internal/platform/gateway	0.289s