《后端架构设计·架构基础与边界》1.1 后端架构到底在解决什么问题

// file: internal/adapters/httpapi/naive_handler.go
// tier: L1
// verify: go vet ./internal/adapters/httpapi/
package httpapi

import (
	"encoding/json"
	"fmt"
	"net/http"
	"sync"
	"time"
)

// naiveOrder 把状态存成裸字符串，金额按 SKU 个数推算。
type naiveOrder struct {
	ID         string    `json:"id"`
	CustomerID string    `json:"customer_id"`
	Status     string    `json:"status"`
	SKUs       []string  `json:"skus"`
	TotalCents int64     `json:"total_cents"`
	CreatedAt  time.Time `json:"created_at"`
}

type NaiveStore struct {
	mu     sync.Mutex
	orders map[string]*naiveOrder
	seq    int
}

func NewNaiveStore() *NaiveStore {
	return &NaiveStore{orders: make(map[string]*naiveOrder)}
}

func (s *NaiveStore) Create(w http.ResponseWriter, r *http.Request) {
	var req struct {
		CustomerID string   `json:"customer_id"`
		SKUs       []string `json:"skus"`
	}
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		http.Error(w, err.Error(), http.StatusBadRequest)
		return
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	s.seq++
	o := &naiveOrder{
		ID:         fmt.Sprintf("ord-%d", s.seq),
		CustomerID: req.CustomerID,
		Status:     "CREATED",
		SKUs:       req.SKUs,
		TotalCents: int64(len(req.SKUs)) * 100,
		CreatedAt:  time.Now(),
	}
	s.orders[o.ID] = o
	w.WriteHeader(http.StatusCreated)
	_ = json.NewEncoder(w).Encode(o)
}

func (s *NaiveStore) Pay(w http.ResponseWriter, r *http.Request) {
	s.mu.Lock()
	defer s.mu.Unlock()
	o, ok := s.orders[r.PathValue("id")]
	if !ok {
		http.NotFound(w, r)
		return
	}
	o.Status = "PAID" // 不校验当前状态，重复支付也会成功
	_ = json.NewEncoder(w).Encode(o)
}

// file: internal/order/order.go
// tier: L1
// verify: go test ./internal/order/
package order

import (
	"fmt"
	"time"
)

// Status 用字符串而不是 int：日志、数据库、API 三处看到同一个值。
type Status string

const (
	StatusCreated           Status = "CREATED"
	StatusInventoryReserved Status = "INVENTORY_RESERVED"
	StatusPaid              Status = "PAID"
	StatusFulfilled         Status = "FULFILLED"
	StatusCancelled         Status = "CANCELLED"
	StatusRefunded          Status = "REFUNDED"
)

type Code string

const (
	CodeInvalidState        Code = "INVALID_STATE"
	CodeOutOfStock          Code = "OUT_OF_STOCK"
	CodePaymentFailed       Code = "PAYMENT_FAILED"
	CodeVersionConflict     Code = "VERSION_CONFLICT"
	CodeIdempotencyConflict Code = "IDEMPOTENCY_CONFLICT"
)

// Error 带上被拒绝的迁移边，日志不需要再拼业务上下文。
type Error struct {
	Code Code
	Op   string
	From Status
	To   Status
}

func (e *Error) Error() string {
	if e.From == "" {
		return fmt.Sprintf("%s: %s", e.Code, e.Op)
	}
	return fmt.Sprintf("%s: %s (%s -> %s)", e.Code, e.Op, e.From, e.To)
}

type OrderItem struct {
	SKU            string
	Quantity       int
	UnitPriceCents int64
}

type Order struct {
	ID         string
	CustomerID string
	Status     Status
	Items      []OrderItem
	TotalCents int64
	Currency   string
	Version    int64
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

// New 只负责“创建即 CREATED”，不碰库存和支付。
func New(id, customerID, currency string, items []OrderItem, now time.Time) (*Order, error) {
	if id == "" || customerID == "" || currency == "" || len(items) == 0 {
		return nil, &Error{Code: CodeInvalidState, Op: "order.New: missing required field"}
	}
	var total int64
	for _, item := range items {
		if item.SKU == "" || item.Quantity <= 0 || item.UnitPriceCents < 0 {
			return nil, &Error{Code: CodeInvalidState, Op: "order.New: invalid item " + item.SKU}
		}
		total += int64(item.Quantity) * item.UnitPriceCents
	}
	return &Order{
		ID: id, CustomerID: customerID, Status: StatusCreated,
		Items: append([]OrderItem(nil), items...), TotalCents: total,
		Currency: currency, Version: 1, CreatedAt: now, UpdatedAt: now,
	}, nil
}

// allowed 是状态机的唯一事实来源。
var allowed = map[Status][]Status{
	StatusCreated:           {StatusInventoryReserved, StatusCancelled},
	StatusInventoryReserved: {StatusPaid, StatusCancelled},
	StatusPaid:              {StatusFulfilled, StatusRefunded},
	StatusFulfilled:         {},
	StatusCancelled:         {},
	StatusRefunded:          {},
}

func CanTransition(from, to Status) bool {
	for _, candidate := range allowed[from] {
		if candidate == to {
			return true
		}
	}
	return false
}

// TransitionTo 是唯一的写状态入口：判合法、改状态、升版本一次完成。
func (o *Order) TransitionTo(next Status, now time.Time) error {
	if !CanTransition(o.Status, next) {
		return &Error{Code: CodeInvalidState, Op: "order.TransitionTo", From: o.Status, To: next}
	}
	o.Status = next
	o.Version++
	o.UpdatedAt = now
	return nil
}

// file: internal/order/order_test.go
// tier: L1
// verify: go test ./internal/order/ -run TestTransitionTo -v
package order

import (
	"errors"
	"testing"
	"time"
)

// 期望的边独立于实现再写一遍；实现被误改时测试不会跟着漂移。
func TestTransitionTo(t *testing.T) {
	legal := map[[2]Status]bool{
		{StatusCreated, StatusInventoryReserved}:   true,
		{StatusCreated, StatusCancelled}:           true,
		{StatusInventoryReserved, StatusPaid}:      true,
		{StatusInventoryReserved, StatusCancelled}: true,
		{StatusPaid, StatusFulfilled}:              true,
		{StatusPaid, StatusRefunded}:               true,
	}
	statuses := []Status{
		StatusCreated, StatusInventoryReserved, StatusPaid,
		StatusFulfilled, StatusCancelled, StatusRefunded,
	}
	now := time.Unix(1_700_000_000, 0)

	for _, from := range statuses {
		for _, to := range statuses {
			order := &Order{ID: "ord-1", Status: from, Version: 3}
			err := order.TransitionTo(to, now)
			want := legal[[2]Status{from, to}]

			if got := err == nil; got != want {
				t.Fatalf("%s -> %s: error = %v, want legal = %v", from, to, err, want)
			}
			if want {
				if order.Status != to || order.Version != 4 || !order.UpdatedAt.Equal(now) {
					t.Fatalf("%s -> %s: state not committed: %+v", from, to, order)
				}
				continue
			}
			var domainErr *Error
			if !errors.As(err, &domainErr) || domainErr.Code != CodeInvalidState {
				t.Fatalf("%s -> %s: error = %v, want INVALID_STATE", from, to, err)
			}
			if order.Status != from || order.Version != 3 {
				t.Fatalf("%s -> %s: illegal transition mutated order", from, to)
			}
		}
	}
}

func TestNewComputesTotal(t *testing.T) {
	o, err := New("ord-1", "cus-1", "CNY", []OrderItem{
		{SKU: "sku-a", Quantity: 2, UnitPriceCents: 1999},
		{SKU: "sku-b", Quantity: 1, UnitPriceCents: 500},
	}, time.Unix(1_700_000_000, 0))
	if err != nil {
		t.Fatal(err)
	}
	if o.TotalCents != 4498 || o.Status != StatusCreated || o.Version != 1 {
		t.Fatalf("order = %+v", o)
	}
	if _, err := New("ord-2", "cus-1", "CNY", []OrderItem{{SKU: "sku-a", Quantity: 0}}, time.Now()); err == nil {
		t.Fatal("zero quantity accepted")
	}
}