《后端架构设计·演进与治理》4.2 BFF：按端聚合与契约裁剪

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

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

type ClientKind string

const (
	ClientWeb     ClientKind = "web"
	ClientMobile  ClientKind = "mobile"
	ClientPartner ClientKind = "partner"
)

// BFFSection is one upstream call. A nil Fields slice means all fields; a
// non-nil slice is an allow-list.
type BFFSection struct {
	Name     string
	Required bool
	Fields   []string
}
type BFFPlan struct {
	Client   ClientKind
	Sections []BFFSection
}
type Fetcher interface {
	Fetch(ctx context.Context, orderID, section string) (map[string]any, error)
}

// BFFResponse carries the body plus the degradation metadata clients need to
// render a placeholder instead of failing the whole screen.
type BFFResponse struct {
	Client    ClientKind
	OrderID   string
	Data      map[string]any
	Degraded  bool
	Missing   []string
	Durations map[string]time.Duration
}
type BFFAggregator struct {
	Fetcher Fetcher
	Plans   map[ClientKind]BFFPlan
}

type bffResult struct {
	index int
	name  string
	data  map[string]any
	err   error
	dur   time.Duration
}

func (a *BFFAggregator) Aggregate(ctx context.Context, client ClientKind, orderID string) (BFFResponse, error) {
	plan, ok := a.Plans[client]
	if !ok {
		return BFFResponse{}, fmt.Errorf("bff: no plan for client %q", client)
	}
	if a.Fetcher == nil {
		return BFFResponse{}, errors.New("bff: nil fetcher")
	}
	ctx, cancel := context.WithCancel(ctx)
	defer cancel()
	ch := make(chan bffResult, len(plan.Sections))
	var wg sync.WaitGroup
	for i, section := range plan.Sections {
		wg.Add(1)
		go func(i int, section BFFSection) {
			defer wg.Done()
			start := time.Now()
			data, err := a.Fetcher.Fetch(ctx, orderID, section.Name)
			ch <- bffResult{index: i, name: section.Name, data: data, err: err, dur: time.Since(start)}
		}(i, section)
	}
	go func() { wg.Wait(); close(ch) }()
	results := make([]bffResult, len(plan.Sections))
	for r := range ch {
		results[r.index] = r
	}
	resp := BFFResponse{
		Client: client, OrderID: orderID,
		Data:      make(map[string]any, len(plan.Sections)),
		Durations: make(map[string]time.Duration, len(plan.Sections)),
	}
	for i, section := range plan.Sections {
		r := results[i]
		resp.Durations[section.Name] = r.dur
		if r.err != nil {
			if section.Required {
				cancel()
				return BFFResponse{}, fmt.Errorf("bff: required section %s: %w", section.Name, r.err)
			}
			resp.Degraded = true
			resp.Missing = append(resp.Missing, section.Name)
			resp.Data[section.Name] = nil
			continue
		}
		resp.Data[section.Name] = trimFields(r.data, section.Fields)
	}
	return resp, nil
}

// trimFields copies only allowed keys; it never mutates a shared cache entry.
func trimFields(data map[string]any, allow []string) map[string]any {
	if data == nil {
		return nil
	}
	out := make(map[string]any, len(data))
	if allow == nil {
		for k, v := range data {
			out[k] = v
		}
		return out
	}
	for _, field := range allow {
		if v, ok := data[field]; ok {
			out[field] = v
		}
	}
	return out
}

// DefaultBFFPlans is the starting contract for the three clients.
func DefaultBFFPlans() map[ClientKind]BFFPlan {
	return map[ClientKind]BFFPlan{
		ClientWeb: {Client: ClientWeb, Sections: []BFFSection{
			{Name: "order", Required: true, Fields: []string{"orderID", "status", "total", "currency", "customerID", "customerPhone", "internalNote"}},
			{Name: "inventory", Required: false, Fields: []string{"sku", "available", "warehouse"}},
			{Name: "payment", Required: false, Fields: []string{"status", "paidAt"}},
		}},
		ClientMobile: {Client: ClientMobile, Sections: []BFFSection{
			{Name: "order", Required: true, Fields: []string{"orderID", "status", "total", "currency"}},
			{Name: "inventory", Required: false, Fields: []string{"sku", "available"}},
			{Name: "payment", Required: false, Fields: []string{"status"}},
		}},
		ClientPartner: {Client: ClientPartner, Sections: []BFFSection{
			{Name: "order", Required: true, Fields: []string{"orderID", "status"}},
			{Name: "payment", Required: true, Fields: []string{"status", "paidAt"}},
		}},
	}
}

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

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

type bffFakeFetcher struct {
	mu       sync.Mutex
	data     map[string]map[string]any
	errs     map[string]error
	delay    time.Duration
	inFlight int
	peak     int
	calls    int
}

func (f *bffFakeFetcher) Fetch(ctx context.Context, orderID, section string) (map[string]any, error) {
	f.mu.Lock()
	f.inFlight++
	f.calls++
	if f.inFlight > f.peak {
		f.peak = f.inFlight
	}
	f.mu.Unlock()
	if f.delay > 0 {
		time.Sleep(f.delay)
	}
	f.mu.Lock()
	f.inFlight--
	f.mu.Unlock()
	if err := f.errs[section]; err != nil {
		return nil, err
	}
	d, ok := f.data[section]
	if !ok {
		return nil, fmt.Errorf("no fixture for %s", section)
	}
	return d, nil
}

func bffFixture() *bffFakeFetcher {
	return &bffFakeFetcher{
		data: map[string]map[string]any{
			"order": {"orderID": "o-42", "status": "PAID", "total": 19900, "currency": "CNY",
				"customerID": "c-7", "customerPhone": "13800000000", "internalNote": "vip", "internalCost": 12000},
			"inventory": {"sku": "sku-9", "available": 3, "warehouse": "WH-1", "internalCost": 8000},
			"payment":   {"status": "CAPTURED", "paidAt": "2026-10-28T09:00:00+08:00", "providerSecret": "never"},
		},
		errs: map[string]error{},
	}
}

func bffRun(t *testing.T, f *bffFakeFetcher, client ClientKind) BFFResponse {
	resp, err := (&BFFAggregator{Fetcher: f, Plans: DefaultBFFPlans()}).Aggregate(context.Background(), client, "o-42")
	if err != nil {
		t.Fatalf("Aggregate: %v", err)
	}
	return resp
}

func bffSection(t *testing.T, resp BFFResponse, name string) map[string]any {
	m, ok := resp.Data[name].(map[string]any)
	if !ok {
		t.Fatalf("section %q is %T, want map", name, resp.Data[name])
	}
	return m
}

func TestBFFProjectionPerClient(t *testing.T) {
	web := bffRun(t, bffFixture(), ClientWeb)
	if web.Degraded || len(web.Missing) != 0 {
		t.Fatalf("unexpected degradation: %v", web.Missing)
	}
	order := bffSection(t, web, "order")
	if order["customerPhone"] != "13800000000" {
		t.Fatalf("web order must keep customerPhone, got %v", order["customerPhone"])
	}
	if _, ok := order["internalCost"]; ok {
		t.Fatal("web order leaked an unmapped field")
	}
	if _, ok := bffSection(t, web, "inventory")["internalCost"]; ok {
		t.Fatal("inventory allow-list leaked internalCost")
	}
	if len(web.Durations) != 3 {
		t.Fatalf("durations=%d want 3", len(web.Durations))
	}
	mobile := bffSection(t, bffRun(t, bffFixture(), ClientMobile), "order")
	for _, field := range []string{"customerPhone", "internalNote", "customerID"} {
		if _, ok := mobile[field]; ok {
			t.Fatalf("mobile order must not contain %q", field)
		}
	}
	if len(mobile) != 4 {
		t.Fatalf("mobile order fields=%d want 4", len(mobile))
	}
}

func TestBFFPartialFailureDegrades(t *testing.T) {
	f := bffFixture()
	f.errs["inventory"] = errors.New("inventory timeout")
	resp := bffRun(t, f, ClientWeb)
	if !resp.Degraded || len(resp.Missing) != 1 || resp.Missing[0] != "inventory" {
		t.Fatalf("degraded=%v missing=%v want true [inventory]", resp.Degraded, resp.Missing)
	}
	if resp.Data["inventory"] != nil {
		t.Fatalf("missing section should be nil, got %v", resp.Data["inventory"])
	}
	if bffSection(t, resp, "order")["status"] != "PAID" {
		t.Fatal("order should survive an optional failure")
	}
}

func TestBFFRequiredFailureReturnsError(t *testing.T) {
	f := bffFixture()
	f.errs["order"] = errors.New("order store unavailable")
	resp, err := (&BFFAggregator{Fetcher: f, Plans: DefaultBFFPlans()}).Aggregate(context.Background(), ClientPartner, "o-42")
	if err == nil || resp.Data != nil {
		t.Fatalf("required failure must return no body, got err=%v data=%v", err, resp.Data)
	}
}

func TestBFFFetchRunsInParallel(t *testing.T) {
	f := bffFixture()
	f.delay = 30 * time.Millisecond
	resp := bffRun(t, f, ClientWeb)
	f.mu.Lock()
	peak, calls := f.peak, f.calls
	f.mu.Unlock()
	t.Logf("peak=%d calls=%d sections=%d", peak, calls, len(resp.Data))
	if peak < 2 || calls != 3 || len(resp.Data) != 3 {
		t.Fatalf("peak=%d calls=%d sections=%d want >=2/3/3", peak, calls, len(resp.Data))
	}
}

$ go test ./internal/platform/gateway/ -run 'TestBFF' -count=1 -v
=== RUN   TestBFFProjectionPerClient
--- PASS: TestBFFProjectionPerClient (0.00s)
=== RUN   TestBFFPartialFailureDegrades
--- PASS: TestBFFPartialFailureDegrades (0.00s)
=== RUN   TestBFFRequiredFailureReturnsError
--- PASS: TestBFFRequiredFailureReturnsError (0.00s)
=== RUN   TestBFFFetchRunsInParallel
    bff_test.go:137: peak=3 calls=3 sections=3
--- PASS: TestBFFFetchRunsInParallel (0.03s)
PASS
ok  	archlab/internal/platform/gateway	0.259s