4. 同步通信与RESTful API

在微服务架构中，同步通信是最直接的交互模式。RESTful API 凭借其无状态、资源导向和统一接口的特性，成为服务间同步调用的首选协议。本章将深入剖析如何使用 Go 标准库 net/http 构建符合领域边界的 REST 服务，涵盖路由设计、请求/响应模型及状态码规范。

4.1 路由设计：从 ServeMux 到模式匹配

Go 1.22 之前的 net/http.ServeMux 仅支持路径前缀匹配，无法区分 HTTP 方法。Go 1.22 引入了增强模式匹配，支持方法限定和路径变量。

领域驱动路由设计模式：每个领域聚合根对应一个资源路径，子资源表达领域内的值对象或实体集合。

// 订单领域路由注册示例
mux := http.NewServeMux()

// 订单聚合根集合
mux.HandleFunc("GET /api/v1/orders", listOrders)
mux.HandleFunc("POST /api/v1/orders", createOrder)

// 订单聚合根实例
mux.HandleFunc("GET /api/v1/orders/{orderId}", getOrder)
mux.HandleFunc("PUT /api/v1/orders/{orderId}", updateOrder)
mux.HandleFunc("DELETE /api/v1/orders/{orderId}", deleteOrder)

// 订单子资源：订单项（值对象集合）
mux.HandleFunc("GET /api/v1/orders/{orderId}/items", listOrderItems)
mux.HandleFunc("POST /api/v1/orders/{orderId}/items", addOrderItem)

4.2 请求/响应模型：序列化与反序列化

REST 服务的核心是资源表示。Go 中通常使用 JSON 作为序列化格式，encoding/json 标准库提供了完备的编解码能力。

4.2.1 请求反序列化

// 创建订单请求体
type CreateOrderRequest struct {
    CustomerID string         `json:"customer_id"`
    Items      []OrderItemDTO `json:"items"`
    Currency   string         `json:"currency"`
}

type OrderItemDTO struct {
    ProductID string  `json:"product_id"`
    Quantity  int     `json:"quantity"`
    UnitPrice float64 `json:"unit_price"`
}

func createOrder(w http.ResponseWriter, r *http.Request) {
    var req CreateOrderRequest
    // 限制请求体大小，防止内存攻击
    r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1MB

    decoder := json.NewDecoder(r.Body)
    decoder.DisallowUnknownFields() // 严格模式：拒绝未知字段
    if err := decoder.Decode(&req); err != nil {
        writeError(w, http.StatusBadRequest, "invalid request body: "+err.Error())
        return
    }
    defer r.Body.Close()

    // 调用应用服务
    order, err := orderService.CreateOrder(r.Context(), req)
    if err != nil {
        writeError(w, http.StatusUnprocessableEntity, err.Error())
        return
    }

    writeJSON(w, http.StatusCreated, order)
}

4.2.2 响应序列化与统一封装

// 统一响应结构
type APIResponse struct {
    Data    interface{} `json:"data,omitempty"`
    Error   string      `json:"error,omitempty"`
    TraceID string      `json:"trace_id,omitempty"`
}

func writeJSON(w http.ResponseWriter, status int, data interface{}) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)

    resp := APIResponse{
        Data:    data,
        TraceID: getTraceIDFromContext(r.Context()),
    }

    if err := json.NewEncoder(w).Encode(resp); err != nil {
        // 记录日志，但响应已部分写入
        log.Printf("json encode error: %v", err)
    }
}

func writeError(w http.ResponseWriter, status int, message string) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)

    resp := APIResponse{
        Error:   message,
        TraceID: getTraceIDFromContext(r.Context()),
    }

    json.NewEncoder(w).Encode(resp)
}

4.3 状态码规范：语义精确性

HTTP 状态码是 REST API 语义的重要组成部分。在微服务通信中，精确的状态码能帮助调用方快速定位问题。

4.4 中间件模式：横切关注点

在 net/http 中，中间件是包装 http.Handler 的函数，用于处理日志、认证、限流、追踪等横切关注点。

// 中间件类型定义
type Middleware func(http.Handler) http.Handler

// 链式组合中间件
func Chain(handler http.Handler, middlewares ...Middleware) http.Handler {
    for i := len(middlewares) - 1; i >= 0; i-- {
        handler = middlewares[i](handler)
    }
    return handler
}

// 日志中间件
func LoggingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        // 包装 ResponseWriter 以捕获状态码
        lrw := &loggingResponseWriter{ResponseWriter: w, statusCode: http.StatusOK}
        next.ServeHTTP(lrw, r)
        log.Printf("[%s] %s %s %d %v",
            r.Method, r.URL.Path, r.RemoteAddr, lrw.statusCode, time.Since(start))
    })
}

// 认证中间件
func AuthMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        token := r.Header.Get("Authorization")
        if token == "" || !validateToken(token) {
            writeError(w, http.StatusUnauthorized, "missing or invalid token")
            return
        }
        // 将用户信息注入上下文
        ctx := context.WithValue(r.Context(), "user", extractUser(token))
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// 使用示例
mux := http.NewServeMux()
mux.HandleFunc("GET /api/v1/orders", listOrders)

handler := Chain(mux, LoggingMiddleware, AuthMiddleware, CORSMiddleware)
server := &http.Server{Addr: ":8080", Handler: handler}

4.5 错误处理与领域异常映射

领域层抛出的异常应映射为合适的 HTTP 状态码和错误响应。定义统一的领域错误类型有助于保持一致性。

// 领域错误类型
type DomainError struct {
    Code    string `json:"code"`
    Message string `json:"message"`
    Status  int    `json:"-"`
}

var (
    ErrOrderNotFound      = &DomainError{"ORDER_NOT_FOUND", "订单不存在", http.StatusNotFound}
    ErrOrderAlreadyPaid   = &DomainError{"ORDER_ALREADY_PAID", "订单已支付", http.StatusConflict}
    ErrInsufficientStock  = &DomainError{"INSUFFICIENT_STOCK", "库存不足", http.StatusUnprocessableEntity}
    ErrUnauthorizedAccess = &DomainError{"UNAUTHORIZED", "无权限操作", http.StatusForbidden}
)

// 错误处理中间件
func ErrorHandlerMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if rec := recover(); rec != nil {
                log.Printf("panic recovered: %v", rec)
                writeError(w, http.StatusInternalServerError, "internal server error")
            }
        }()
        next.ServeHTTP(w, r)
    })
}

// 应用服务中的错误返回
func (s *OrderService) GetOrder(ctx context.Context, id string) (*Order, error) {
    order, err := s.repo.FindByID(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, ErrOrderNotFound
        }
        return nil, fmt.Errorf("database error: %w", err)
    }
    return order, nil
}

4.6 测试 REST 端点

使用 net/http/httptest 标准库可以方便地对 REST 端点进行单元测试和集成测试。

func TestCreateOrderHandler(t *testing.T) {
    // 准备测试用例
    tests := []struct {
        name       string
        body       string
        wantStatus int
    }{
        {"valid order", `{"customer_id":"c1","items":[{"product_id":"p1","quantity":2,"unit_price":10.5}]}`, http.StatusCreated},
        {"missing customer_id", `{"items":[]}`, http.StatusBadRequest},
        {"invalid json", `{invalid}`, http.StatusBadRequest},
        {"empty items", `{"customer_id":"c1","items":[]}`, http.StatusUnprocessableEntity},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            req := httptest.NewRequest(http.MethodPost, "/api/v1/orders", strings.NewReader(tt.body))
            req.Header.Set("Content-Type", "application/json")
            w := httptest.NewRecorder()

            // 假设已注册路由
            createOrder(w, req)

            if w.Code != tt.wantStatus {
                t.Errorf("status = %d, want %d; body = %s", w.Code, tt.wantStatus, w.Body.String())
            }
        })
    }
}

4.7 生产级配置清单

// 生产级 HTTP 服务器配置
server := &http.Server{
    Addr:              ":8080",
    Handler:           handler,
    ReadTimeout:       10 * time.Second,
    ReadHeaderTimeout: 5 * time.Second,
    WriteTimeout:      30 * time.Second,
    IdleTimeout:       60 * time.Second,
    MaxHeaderBytes:    1 << 20, // 1MB
}

// 优雅关闭
go func() {
    if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        log.Fatalf("server error: %v", err)
    }
}()

// 等待中断信号
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := server.Shutdown(ctx); err != nil {
    log.Fatalf("server forced shutdown: %v", err)
}