《游戏服务端架构·核心系统与契约》1.2 第三方登录与账号绑定

// file: internal/identitylink/contract.go
// tier: L1
// verify: go test ./internal/identitylink/
package identitylink

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

type Provider string

const (
	Guest  Provider = "guest"
	WeChat Provider = "wechat"
	Apple  Provider = "apple"
	Steam  Provider = "steam"
)

var (
	ErrIncomplete     = errors.New("identitylink: provider, tenant and subject are required")
	ErrNotFound       = errors.New("identitylink: link not found")
	ErrUnknownAccount = errors.New("identitylink: unknown account")
	ErrNotOwner       = errors.New("identitylink: link belongs to another account")
	ErrLastCredential = errors.New("identitylink: refusing to remove the last credential")
	ErrGuestOnly      = errors.New("identitylink: guest link cannot be the last credential")
	ErrLinkLimit      = errors.New("identitylink: account link limit reached")
	ErrAlreadyLinked  = errors.New("identitylink: subject already linked to another account")
	ErrSameCredential = errors.New("identitylink: old and new credential are identical")
	ErrSameAccount    = errors.New("identitylink: cannot adopt into itself")
	ErrShadowRetired  = errors.New("identitylink: shadow account already retired")
)

// ExternalID is one credential observed from a provider. Tenant scopes the
// identifier: the same union id may map to different accounts in different
// products when data isolation is required by contract.
type ExternalID struct {
	Provider Provider
	Tenant   string
	OpenID   string
	UnionID  string
}

// key is the uniqueness rule. UnionID wins over OpenID because it is stable
// across the provider's app family; OpenID is only unique per app.
func (e ExternalID) key() (string, error) {
	if e.Provider == "" || e.Tenant == "" {
		return "", ErrIncomplete
	}
	subject := e.UnionID
	if subject == "" {
		subject = e.OpenID
	}
	if subject == "" {
		return "", ErrIncomplete
	}
	return string(e.Provider) + "|" + e.Tenant + "|" + subject, nil
}

type Link struct {
	Key       string
	AccountID string
	Provider  Provider
	Tenant    string
	OpenID    string
	UnionID   string
	CreatedAt time.Time
}

type Revoked struct {
	Key       string
	AccountID string
	Provider  Provider
	Tenant    string
	At        time.Time
	Reason    string
}

type BindStatus string

const (
	Bound        BindStatus = "BOUND"
	AlreadyBound BindStatus = "ALREADY_BOUND"
	Conflict     BindStatus = "CONFLICT"
)

// BindOutcome reports a conflict instead of hiding it in an error: merging two
// real accounts is a product decision, not something this package may do.
type BindOutcome struct {
	Status            BindStatus
	AccountID         string
	ConflictAccountID string
}

type Policy struct {
	AutoCreate         bool
	AllowGuestOnly     bool
	MaxLinksPerAccount int
}

// Registry is the mapping table. In production the primary key is the same
// string produced by key(); the uniqueness guarantee must live in the database,
// because two concurrent callbacks can both pass an in-memory check.
type Registry struct {
	links     map[string]*Link
	byAccount map[string]map[string]struct{}
	accounts  map[string]struct{}
	retired   map[string]string
	revoked   []Revoked
	policy    Policy
	clock     func() time.Time
	seq       int
}

func New(clock func() time.Time, policy Policy) *Registry {
	return &Registry{
		links:     make(map[string]*Link),
		byAccount: make(map[string]map[string]struct{}),
		accounts:  make(map[string]struct{}),
		retired:   make(map[string]string),
		policy:    policy,
		clock:     clock,
	}
}

func (r *Registry) NewAccount() string {
	r.seq++
	id := fmt.Sprintf("acc-%03d", r.seq)
	r.accounts[id] = struct{}{}
	r.byAccount[id] = map[string]struct{}{}
	return id
}

func (r *Registry) AccountExists(id string) bool {
	_, ok := r.accounts[id]
	return ok
}

// Resolve is the login-time lookup. It never mutates an existing mapping, so a
// retried provider callback returns the same account every time.
func (r *Registry) Resolve(id ExternalID) (string, bool, error) {
	key, err := id.key()
	if err != nil {
		return "", false, err
	}
	if l, ok := r.links[key]; ok {
		return l.AccountID, false, nil
	}
	if !r.policy.AutoCreate {
		return "", false, ErrNotFound
	}
	accountID := r.NewAccount()
	if _, err := r.Bind(accountID, id); err != nil {
		return "", false, err
	}
	return accountID, true, nil
}

func (r *Registry) Bind(accountID string, id ExternalID) (BindOutcome, error) {
	key, err := id.key()
	if err != nil {
		return BindOutcome{}, err
	}
	if _, ok := r.accounts[accountID]; !ok {
		return BindOutcome{}, ErrUnknownAccount
	}
	if l, ok := r.links[key]; ok {
		if l.AccountID == accountID {
			return BindOutcome{Status: AlreadyBound, AccountID: accountID}, nil
		}
		return BindOutcome{Status: Conflict, AccountID: accountID, ConflictAccountID: l.AccountID}, nil
	}
	if r.policy.MaxLinksPerAccount > 0 && len(r.byAccount[accountID]) >= r.policy.MaxLinksPerAccount {
		return BindOutcome{}, ErrLinkLimit
	}
	now := r.clock()
	r.links[key] = &Link{
		Key:       key,
		AccountID: accountID,
		Provider:  id.Provider,
		Tenant:    id.Tenant,
		OpenID:    id.OpenID,
		UnionID:   id.UnionID,
		CreatedAt: now,
	}
	r.byAccount[accountID][key] = struct{}{}
	return BindOutcome{Status: Bound, AccountID: accountID}, nil
}

$ go test -count=1 ./internal/identitylink/
ok  	gsarchlab/internal/identitylink	0.341s