《游戏服务端编程实践》4.4.1 API 设计

// file: ch04/login/api.go
// tier: L1
// verify: go test ./ch04/login/

package login

import (
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"errors"
	"net/http"
	"strings"
	"sync"
	"time"
)

// tokenAudience 在签发与校验两侧共用，避免字符串漂移。
const tokenAudience = "game-gateway"

// 业务错误码稳定、可编程；HTTP 状态码只表达传输层语义。
const (
	CodeOK         = 0
	CodeInvalidArg = 40001
	CodeConflict   = 40901
	CodeTooLarge   = 41301
	CodeMethod     = 40501
	CodeInternal   = 50001
)

type Envelope struct {
	Code      int    `json:"code"`
	Message   string `json:"message"`
	RequestID string `json:"request_id"`
	Data      any    `json:"data,omitempty"`
}

type LoginRequest struct {
	Provider       string `json:"provider"`
	Ticket         string `json:"ticket"`
	DeviceID       string `json:"device_id"`
	IdempotencyKey string `json:"idempotency_key"`
}

type SessionView struct {
	SessionID   string `json:"session_id"`
	AccountID   uint64 `json:"account_id"`
	Version     uint64 `json:"version"`
	AccessToken string `json:"access_token"`
	TokenType   string `json:"token_type"`
	ExpiresIn   int    `json:"expires_in"`
}

// TokenIssuer 由 4.4.2 的 JWT 签发器实现；测试注入 fake，避免依赖时钟与网络。
type TokenIssuer interface {
	Issue(accountID uint64, sessionID string, version uint64, audience string) (string, int, error)
}

type loginRecord struct {
	fingerprint string
	session     SessionView
}

type API struct {
	issuer      TokenIssuer
	mu          sync.Mutex
	logins      map[string]loginRecord
	nextAccount uint64
}

func NewAPI(issuer TokenIssuer) *API {
	return &API{issuer: issuer, logins: map[string]loginRecord{}, nextAccount: 10001}
}

func (a *API) Routes() http.Handler {
	mux := http.NewServeMux()
	mux.HandleFunc("/v1/auth/login", a.handleLogin)
	return mux
}

func (a *API) handleLogin(w http.ResponseWriter, r *http.Request) {
	rid := requestID(r)
	if r.Method != http.MethodPost {
		writeJSON(w, http.StatusMethodNotAllowed, rid, CodeMethod, "method not allowed", nil)
		return
	}
	var req LoginRequest
	r.Body = http.MaxBytesReader(w, r.Body, 64<<10)
	dec := json.NewDecoder(r.Body)
	dec.DisallowUnknownFields()
	if err := dec.Decode(&req); err != nil {
		var tooLarge *http.MaxBytesError
		if errors.As(err, &tooLarge) {
			writeJSON(w, http.StatusRequestEntityTooLarge, rid, CodeTooLarge, "invalid request body", nil)
		} else {
			writeJSON(w, http.StatusBadRequest, rid, CodeInvalidArg, "invalid request body", nil)
		}
		return
	}
	req.Provider, req.Ticket, req.DeviceID = strings.TrimSpace(req.Provider), strings.TrimSpace(req.Ticket), strings.TrimSpace(req.DeviceID)
	if req.Provider == "" || req.Ticket == "" || req.DeviceID == "" || len(req.IdempotencyKey) > 128 {
		writeJSON(w, http.StatusBadRequest, rid, CodeInvalidArg, "provider, ticket and device_id are required", nil)
		return
	}
	fingerprint := req.Provider + "|" + req.Ticket + "|" + req.DeviceID
	a.mu.Lock()
	rec, seen := a.logins[req.IdempotencyKey]
	a.mu.Unlock()
	if req.IdempotencyKey != "" && seen {
		if rec.fingerprint != fingerprint {
			writeJSON(w, http.StatusConflict, rid, CodeConflict, "idempotency key reused with different payload", nil)
			return
		}
		writeJSON(w, http.StatusOK, rid, CodeOK, "ok", rec.session)
		return
	}
	a.mu.Lock()
	accountID := a.nextAccount
	a.nextAccount++
	a.mu.Unlock()
	session := SessionView{SessionID: newID("sess_"), AccountID: accountID, Version: 1, TokenType: "Bearer", ExpiresIn: 900}
	token, expiresIn, err := a.issuer.Issue(accountID, session.SessionID, session.Version, tokenAudience)
	if err != nil {
		writeJSON(w, http.StatusInternalServerError, rid, CodeInternal, "internal error", nil)
		return
	}
	session.AccessToken, session.ExpiresIn = token, expiresIn
	a.mu.Lock()
	if rec, ok := a.logins[req.IdempotencyKey]; ok && req.IdempotencyKey != "" {
		a.mu.Unlock()
		if rec.fingerprint != fingerprint {
			writeJSON(w, http.StatusConflict, rid, CodeConflict, "idempotency key reused with different payload", nil)
			return
		}
		writeJSON(w, http.StatusOK, rid, CodeOK, "ok", rec.session)
		return
	}
	if req.IdempotencyKey != "" {
		a.logins[req.IdempotencyKey] = loginRecord{fingerprint: fingerprint, session: session}
	}
	a.mu.Unlock()
	writeJSON(w, http.StatusOK, rid, CodeOK, "ok", session)
}

func requestID(r *http.Request) string {
	if id := r.Header.Get("X-Request-ID"); len(id) >= 8 && len(id) <= 64 && strings.IndexFunc(id, func(c rune) bool {
		return !(c == '-' || c == '_' || c >= '0' && c <= '9' || c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z')
	}) < 0 {
		return id
	}
	return newID("req_")
}

func newID(prefix string) string {
	var b [8]byte
	if _, err := rand.Read(b[:]); err != nil {
		return prefix + time.Now().Format("150405.000000000")
	}
	return prefix + hex.EncodeToString(b[:])
}

func writeJSON(w http.ResponseWriter, status int, rid string, code int, msg string, data any) {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.Header().Set("X-Request-ID", rid)
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(Envelope{Code: code, Message: msg, RequestID: rid, Data: data})
}

// file: ch04/login/api_test.go
// tier: L1
// verify: go test ./ch04/login/

package login

import (
	"encoding/json"
	"net/http"
	"net/http/httptest"
	"strings"
	"testing"
)

type fakeIssuer struct{ calls int }

func (f *fakeIssuer) Issue(accountID uint64, sessionID string, version uint64, audience string) (string, int, error) {
	f.calls++
	return "tok_" + sessionID, 900, nil
}

func call(h http.Handler, method, body string) *httptest.ResponseRecorder {
	req := httptest.NewRequest(method, "/v1/auth/login", strings.NewReader(body))
	rec := httptest.NewRecorder()
	h.ServeHTTP(rec, req)
	return rec
}

func decode(t *testing.T, rec *httptest.ResponseRecorder) (Envelope, SessionView) {
	t.Helper()
	var env Envelope
	if err := json.Unmarshal(rec.Body.Bytes(), &env); err != nil {
		t.Fatalf("decode: %v", err)
	}
	raw, _ := json.Marshal(env.Data)
	var view SessionView
	_ = json.Unmarshal(raw, &view)
	return env, view
}

func TestLoginAndReplay(t *testing.T) {
	issuer := &fakeIssuer{}
	h := NewAPI(issuer).Routes()
	body := `{"provider":"wechat","ticket":"code-123","device_id":"dev-a","idempotency_key":"idem-1"}`
	first := call(h, http.MethodPost, body)
	env1, v1 := decode(t, first)
	if first.Code != http.StatusOK || env1.Code != CodeOK || env1.RequestID == "" || v1.SessionID == "" {
		t.Fatalf("first login: status=%d env=%+v view=%+v", first.Code, env1, v1)
	}
	env2, v2 := decode(t, call(h, http.MethodPost, body))
	if env2.Code != CodeOK || issuer.calls != 1 || v2.SessionID != v1.SessionID {
		t.Fatalf("replay: env=%+v calls=%d view=%+v", env2, issuer.calls, v2)
	}
}

func TestRejectInvalidRequests(t *testing.T) {
	h := NewAPI(&fakeIssuer{}).Routes()
	cases := []struct {
		name, body   string
		status, code int
	}{
		{"missing ticket", `{"provider":"wechat","device_id":"dev-a"}`, http.StatusBadRequest, CodeInvalidArg},
		{"bad json", `{"provider":`, http.StatusBadRequest, CodeInvalidArg},
		{"oversized", `{"provider":"wechat","ticket":"` + strings.Repeat("x", 70<<10) + `","device_id":"dev-a"}`, http.StatusRequestEntityTooLarge, CodeTooLarge},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			rec := call(h, http.MethodPost, tc.body)
			if env, _ := decode(t, rec); rec.Code != tc.status || env.Code != tc.code {
				t.Fatalf("status=%d code=%d, want %d/%d", rec.Code, env.Code, tc.status, tc.code)
			}
		})
	}
	rec := call(h, http.MethodGet, "")
	if env, _ := decode(t, rec); rec.Code != http.StatusMethodNotAllowed || env.Code != CodeMethod {
		t.Fatalf("method: status=%d code=%d", rec.Code, env.Code)
	}
}

cd .local/checks/gs-practice-lab
gofmt -l ch04/login
go vet ./ch04/login/
go test ./ch04/login/ -count=1

ok  	gspractice/ch04/login	0.405s