《后端架构设计·分布式与数据一致性》9.1 幂等键设计：作用域、生命周期与存储

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

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

// Key identifies one operation. Tenant and Operation scope a client-supplied
// key so the same value cannot collide across tenants or APIs.
type Key struct {
	Tenant    string
	Operation string
	Value     string
}

func (k Key) String() string { return k.Tenant + "/" + k.Operation + "/" + k.Value }

func (k Key) validate() error {
	if k.Tenant == "" || k.Operation == "" || k.Value == "" {
		return fmt.Errorf("idempotency: tenant=%q operation=%q key=%q: %w",
			k.Tenant, k.Operation, k.Value, ErrKeyEmpty)
	}
	return nil
}

// State is the lifecycle of one idempotency record.
type State string

const (
	StateInProgress State = "in_progress"
	StateDone       State = "done"
	StateFailed     State = "failed"
	StateRetryable  State = "retryable"
)

var (
	ErrConflict     = errors.New("idempotency: key reused with different payload")
	ErrInProgress   = errors.New("idempotency: request already in progress")
	ErrLeaseExpired = errors.New("idempotency: lease expired before completion")
	ErrStaleAttempt = errors.New("idempotency: attempt no longer owns the key")
	ErrKeyEmpty     = errors.New("idempotency: empty key component")
)

// Record holds a replayable outcome. Attempt is a fencing token: only the
// attempt that currently owns the key may complete it.
type Record struct {
	State       State
	Fingerprint string
	Response    string
	ExpiresAt   time.Time
	Attempt     uint64
}

// Store keeps records in memory. The same state machine can run behind a
// unique index on (tenant, operation, key).
type Store struct {
	mu        sync.Mutex
	clock     func() time.Time
	lease     time.Duration
	retention time.Duration
	seq       uint64
	records   map[string]Record
}

// NewStore returns a store. lease bounds how long an in-progress record blocks
// duplicates; retention bounds how long a final answer can be replayed.
func NewStore(lease, retention time.Duration, clock func() time.Time) (*Store, error) {
	if lease <= 0 || retention <= 0 || clock == nil {
		return nil, fmt.Errorf("idempotency: lease=%v retention=%v clock_nil=%v", lease, retention, clock == nil)
	}
	return &Store{
		clock:     clock,
		lease:     lease,
		retention: retention,
		records:   make(map[string]Record),
	}, nil
}

// live returns a record unless it has expired. Caller holds s.mu.
func (s *Store) live(key string) (Record, bool) {
	r, ok := s.records[key]
	if !ok {
		return Record{}, false
	}
	if !s.clock().Before(r.ExpiresAt) {
		delete(s.records, key)
		return Record{}, false
	}
	return r, true
}

// Begin reserves the key. created is true only for the caller that must
// execute. A finished request returns its stored record; a concurrent
// duplicate gets ErrInProgress.
func (s *Store) Begin(k Key, fingerprint string) (Record, bool, error) {
	if err := k.validate(); err != nil {
		return Record{}, false, err
	}
	if fingerprint == "" {
		return Record{}, false, fmt.Errorf("idempotency: begin %s: empty fingerprint", k)
	}
	s.mu.Lock()
	defer s.mu.Unlock()

	if r, ok := s.live(k.String()); ok {
		if r.Fingerprint != fingerprint {
			return Record{}, false, fmt.Errorf("idempotency: begin %s: %w", k, ErrConflict)
		}
		switch r.State {
		case StateDone, StateFailed:
			return r, false, nil
		case StateInProgress:
			return Record{}, false, fmt.Errorf("idempotency: begin %s: %w", k, ErrInProgress)
		}
		// StateRetryable: the previous attempt promised no effect.
	}

	s.seq++
	rec := Record{State: StateInProgress, Fingerprint: fingerprint,
		ExpiresAt: s.clock().Add(s.lease), Attempt: s.seq}
	s.records[k.String()] = rec
	return rec, true, nil
}

// Complete stores the response under the retention window. A stale attempt is
// rejected even when its fingerprint matches, because a lease takeover cannot
// safely share the same key.
func (s *Store) Complete(k Key, fingerprint string, attempt uint64, response string) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	r, ok := s.live(k.String())
	if !ok {
		return fmt.Errorf("idempotency: complete %s: %w", k, ErrLeaseExpired)
	}
	if r.Fingerprint != fingerprint {
		return fmt.Errorf("idempotency: complete %s: %w", k, ErrConflict)
	}
	if r.Attempt != attempt {
		return fmt.Errorf("idempotency: complete %s: %w", k, ErrStaleAttempt)
	}
	r.State, r.Response = StateDone, response
	r.ExpiresAt = s.clock().Add(s.retention)
	s.records[k.String()] = r
	return nil
}

// Fail records a failed attempt. retryable=true releases the key; false makes
// the failure final for the retention window.
func (s *Store) Fail(k Key, fingerprint string, attempt uint64, retryable bool) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	r, ok := s.live(k.String())
	if !ok {
		return fmt.Errorf("idempotency: fail %s: %w", k, ErrLeaseExpired)
	}
	if r.Fingerprint != fingerprint {
		return fmt.Errorf("idempotency: fail %s: %w", k, ErrConflict)
	}
	if r.Attempt != attempt {
		return fmt.Errorf("idempotency: fail %s: %w", k, ErrStaleAttempt)
	}
	if retryable {
		r.State = StateRetryable
	} else {
		r.State = StateFailed
	}
	r.ExpiresAt = s.clock().Add(s.retention)
	s.records[k.String()] = r
	return nil
}

$ go test ./internal/platform/idempotency/ -count=1 -v
=== RUN   TestConcurrentSameKeyOnlyOneOwner
    store_test.go:82: workers=64 created=1 in_progress=63 other=0
--- PASS: TestConcurrentSameKeyOnlyOneOwner (0.00s)
=== RUN   TestLeaseExpiryAllowsTakeover
    store_test.go:139: after_lease_expiry attempt_old=1 attempt_new=2 created=true late_complete=idempotency: complete tenant-a/order.create/req-1001: idempotency: attempt no longer owns the key
--- PASS: TestLeaseExpiryAllowsTakeover (0.00s)
=== RUN   TestRetentionExpiryForgetsKey
    store_test.go:198: after_retention created=true
--- PASS: TestRetentionExpiryForgetsKey (0.00s)
PASS
ok  	archlab/internal/platform/idempotency	0.336s