《后端架构设计·演进与治理》10.1 租户模型：隔离级别与数据分区

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

import (
	"crypto/sha256"
	"encoding/binary"
	"errors"
	"fmt"
	"sort"
	"strings"
)

type IsolationLevel string

const (
	Pooled IsolationLevel = "pooled"
	Bridge IsolationLevel = "bridge"
	Silo   IsolationLevel = "silo"
)

var (
	ErrInvalidTenant = errors.New("tenant: invalid tenant id")
	ErrCrossTenant   = errors.New("tenant: key belongs to another tenant")
)

type TenantProfile struct {
	ID                   string
	Regulated            bool
	DedicatedDBRequested bool
	NeedsCustomSchema    bool
	MonthlyOrders        int
	NoisyNeighborRisk    int // 0..100
}

type IsolationDecision struct {
	Level   IsolationLevel
	Reasons []string
}

func validTenantID(id string) bool {
	if len(id) < 3 || len(id) > 32 {
		return false
	}
	for i, r := range id {
		switch {
		case r >= 'a' && r <= 'z', r >= '0' && r <= '9':
		case (r == '-' || r == '_') && i > 0:
		default:
			return false
		}
	}
	return true
}

// Recommend applies hard constraints before soft signals: regulation and a
// dedicated-database contract cannot be relaxed by lower volume.
func Recommend(p TenantProfile) (IsolationDecision, error) {
	if !validTenantID(p.ID) {
		return IsolationDecision{}, fmt.Errorf("%w: %q", ErrInvalidTenant, p.ID)
	}
	if p.MonthlyOrders < 0 || p.NoisyNeighborRisk < 0 || p.NoisyNeighborRisk > 100 {
		return IsolationDecision{}, fmt.Errorf("tenant: profile %q has out-of-range metrics", p.ID)
	}
	d := IsolationDecision{Level: Pooled}
	if p.Regulated {
		d.Level = Silo
		d.Reasons = append(d.Reasons, "regulated data requires a dedicated boundary")
	}
	if p.DedicatedDBRequested && d.Level != Silo {
		d.Level = Silo
		d.Reasons = append(d.Reasons, "contract requires a dedicated database")
	}
	if d.Level == Silo {
		return d, nil
	}
	if p.NeedsCustomSchema {
		d.Level = Bridge
		d.Reasons = append(d.Reasons, "custom schema needs its own namespace")
	}
	if p.MonthlyOrders > 5_000_000 && d.Level == Pooled {
		d.Level = Bridge
		d.Reasons = append(d.Reasons, "order volume above 5M/month")
	}
	if p.NoisyNeighborRisk >= 70 && d.Level == Pooled {
		d.Level = Bridge
		d.Reasons = append(d.Reasons, "noisy-neighbor risk at or above 70")
	}
	if len(d.Reasons) == 0 {
		d.Reasons = append(d.Reasons, "default pooled isolation")
	}
	return d, nil
}

type PartitionKey struct {
	Tenant   string
	Bucket   uint16
	Resource string
}

// BucketFor hashes only the tenant, so all resources of one tenant share a
// bucket and a range scan does not fan out.
func BucketFor(tenantID string, buckets uint16) (uint16, error) {
	if !validTenantID(tenantID) {
		return 0, fmt.Errorf("%w: %q", ErrInvalidTenant, tenantID)
	}
	if buckets == 0 {
		return 0, errors.New("tenant: bucket count must be positive")
	}
	sum := sha256.Sum256([]byte(tenantID))
	return binary.BigEndian.Uint16(sum[:2]) % buckets, nil
}

// NewPartitionKey encodes tenant, bucket and resource into one key. The tenant
// prefix is what makes a cross-tenant read detectable at parse time.
func NewPartitionKey(tenantID, resourceID string, buckets uint16) (string, error) {
	bucket, err := BucketFor(tenantID, buckets)
	if err != nil {
		return "", err
	}
	if resourceID == "" || strings.ContainsRune(resourceID, ':') {
		return "", fmt.Errorf("tenant: invalid resource id %q", resourceID)
	}
	return fmt.Sprintf("%s:%04x:%s", tenantID, bucket, resourceID), nil
}

// ParsePartitionKey rejects malformed keys and keys owned by another tenant.
func ParsePartitionKey(key, tenantID string) (PartitionKey, error) {
	parts := strings.SplitN(key, ":", 3)
	if len(parts) != 3 || parts[2] == "" {
		return PartitionKey{}, fmt.Errorf("tenant: malformed partition key %q", key)
	}
	if parts[0] != tenantID {
		return PartitionKey{}, fmt.Errorf("%w: request=%q key=%q", ErrCrossTenant, tenantID, parts[0])
	}
	var bucket uint16
	if _, err := fmt.Sscanf(parts[1], "%04x", &bucket); err != nil {
		return PartitionKey{}, fmt.Errorf("tenant: malformed bucket %q", parts[1])
	}
	return PartitionKey{Tenant: parts[0], Bucket: bucket, Resource: parts[2]}, nil
}

type ScopedQuery struct {
	Tenant string
	Key    PartitionKey
}

// BindTenant turns a client key into a tenant-scoped query; repositories that
// only accept ScopedQuery cannot forget the tenant filter.
func BindTenant(tenantID, key string) (ScopedQuery, error) {
	pk, err := ParsePartitionKey(key, tenantID)
	if err != nil {
		return ScopedQuery{}, err
	}
	return ScopedQuery{Tenant: tenantID, Key: pk}, nil
}

type Shard struct {
	Name     string
	Capacity int
}

type TenantLoad struct {
	ID   string
	Load int
}

type ShardPlan struct {
	Assignment map[string]string
	Used       map[string]int
	Overloaded []string
}

// PlanShards uses best-fit decreasing. Tenants are never split; one that fits
// nowhere is reported instead of being silently packed.
func PlanShards(tenants []TenantLoad, shards []Shard) (ShardPlan, error) {
	if len(shards) == 0 {
		return ShardPlan{}, errors.New("tenant: no shards")
	}
	sortedShards := append([]Shard(nil), shards...)
	for _, s := range sortedShards {
		if s.Name == "" || s.Capacity <= 0 {
			return ShardPlan{}, fmt.Errorf("tenant: bad shard %q", s.Name)
		}
	}
	sort.Slice(sortedShards, func(i, j int) bool { return sortedShards[i].Name < sortedShards[j].Name })
	sortedTenants := append([]TenantLoad(nil), tenants...)
	for _, t := range sortedTenants {
		if t.Load < 0 {
			return ShardPlan{}, fmt.Errorf("tenant: %q has negative load", t.ID)
		}
	}
	sort.Slice(sortedTenants, func(i, j int) bool {
		if sortedTenants[i].Load != sortedTenants[j].Load {
			return sortedTenants[i].Load > sortedTenants[j].Load
		}
		return sortedTenants[i].ID < sortedTenants[j].ID
	})
	plan := ShardPlan{Assignment: make(map[string]string), Used: make(map[string]int)}
	for _, t := range sortedTenants {
		best, bestRatio := -1, 0.0
		for i, s := range sortedShards {
			if plan.Used[s.Name]+t.Load > s.Capacity {
				continue
			}
			ratio := float64(plan.Used[s.Name]+t.Load) / float64(s.Capacity)
			if best < 0 || ratio < bestRatio {
				best, bestRatio = i, ratio
			}
		}
		if best < 0 {
			plan.Overloaded = append(plan.Overloaded, t.ID)
			continue
		}
		s := sortedShards[best]
		plan.Assignment[t.ID] = s.Name
		plan.Used[s.Name] += t.Load
	}
	return plan, nil
}

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

import (
	"errors"
	"testing"
)

func TestRecommendIsolation(t *testing.T) {
	cases := []struct {
		in   TenantProfile
		want IsolationLevel
	}{
		{TenantProfile{ID: "acme"}, Pooled},
		{TenantProfile{ID: "bank-a", Regulated: true}, Silo},
		{TenantProfile{ID: "big-co", DedicatedDBRequested: true}, Silo},
		{TenantProfile{ID: "schema-co", NeedsCustomSchema: true}, Bridge},
		{TenantProfile{ID: "volume-co", MonthlyOrders: 5_000_001}, Bridge},
		{TenantProfile{ID: "noisy-co", NoisyNeighborRisk: 70}, Bridge},
	}
	for _, tc := range cases {
		got, err := Recommend(tc.in)
		if err != nil || got.Level != tc.want || len(got.Reasons) == 0 {
			t.Fatalf("%s: level=%s err=%v reasons=%v", tc.in.ID, got.Level, err, got.Reasons)
		}
	}
	if _, err := Recommend(TenantProfile{ID: "A"}); !errors.Is(err, ErrInvalidTenant) {
		t.Fatalf("invalid id err=%v", err)
	}
}

func TestPartitionKeyRoundTrip(t *testing.T) {
	key, err := NewPartitionKey("acme", "order-1001", 32)
	if err != nil {
		t.Fatalf("NewPartitionKey: %v", err)
	}
	pk, err := ParsePartitionKey(key, "acme")
	if err != nil || pk.Tenant != "acme" || pk.Resource != "order-1001" {
		t.Fatalf("parsed %+v err=%v", pk, err)
	}
	if _, err := ParsePartitionKey(key, "other"); !errors.Is(err, ErrCrossTenant) {
		t.Fatalf("cross tenant err=%v", err)
	}
	if _, err := BindTenant("other", key); !errors.Is(err, ErrCrossTenant) {
		t.Fatalf("BindTenant err=%v", err)
	}
	if _, err := NewPartitionKey("acme", "bad:id", 32); err == nil {
		t.Fatal("expected resource error")
	}
	if _, err := ParsePartitionKey("acme:zzzz:x", "acme"); err == nil {
		t.Fatal("expected malformed bucket error")
	}
}

func TestPlanShards(t *testing.T) {
	shards := []Shard{{Name: "shard-a", Capacity: 100}, {Name: "shard-b", Capacity: 100}, {Name: "shard-c", Capacity: 100}}
	tenants := []TenantLoad{{ID: "t-01", Load: 60}, {ID: "t-02", Load: 50}, {ID: "t-03", Load: 40},
		{ID: "t-04", Load: 30}, {ID: "t-05", Load: 20}, {ID: "t-06", Load: 10}}
	plan, err := PlanShards(tenants, shards)
	if err != nil || len(plan.Assignment) != len(tenants) || len(plan.Overloaded) != 0 {
		t.Fatalf("assigned=%d overloaded=%v err=%v", len(plan.Assignment), plan.Overloaded, err)
	}
	reversed := append([]TenantLoad(nil), tenants...)
	for i, j := 0, len(reversed)-1; i < j; i, j = i+1, j-1 {
		reversed[i], reversed[j] = reversed[j], reversed[i]
	}
	again, _ := PlanShards(reversed, shards)
	for id, shard := range plan.Assignment {
		if again.Assignment[id] != shard {
			t.Fatalf("%s moved from %s to %s", id, shard, again.Assignment[id])
		}
	}
	t.Logf("used a=%d b=%d c=%d", plan.Used["shard-a"], plan.Used["shard-b"], plan.Used["shard-c"])

	small, err := PlanShards([]TenantLoad{{ID: "huge-co", Load: 60}}, []Shard{{Name: "small", Capacity: 50}})
	if err != nil || len(small.Overloaded) != 1 || small.Overloaded[0] != "huge-co" {
		t.Fatalf("overloaded=%v err=%v", small.Overloaded, err)
	}
}

$ go version
go version go1.26.0 darwin/arm64
$ go test ./internal/platform/tenant/ -count=1 -v -run 'TestRecommend|TestPartition|TestPlan'
=== RUN   TestRecommendIsolation
--- PASS: TestRecommendIsolation (0.00s)
=== RUN   TestPartitionKeyRoundTrip
--- PASS: TestPartitionKeyRoundTrip (0.00s)
=== RUN   TestPlanShards
    isolation_test.go:75: used a=70 b=70 c=70
--- PASS: TestPlanShards (0.00s)
PASS
ok  	archlab/internal/platform/tenant	0.239s