Go权限审计网关Mock隔离 - 第2节

2.1 接口（interface）：网关插件的契约基石

在微服务网关中，认证、限流、审计、Mock 等插件需要一套统一的接入规范。Go 的接口类型恰好提供了“行为契约”机制：只要实现了规定的方法集，任何类型都可以作为插件注入网关。

2.1.1 网关插件接口定义

一个典型的权限审计网关会定义如下核心接口：

// Handler 是网关处理器的核心接口
type Handler interface {
    ServeHTTP(ctx context.Context, req *Request) (*Response, error)
}

// Authenticator 认证插件接口
type Authenticator interface {
    Authenticate(ctx context.Context, token string) (UserInfo, error)
}

// Auditor 审计日志接口
type Auditor interface {
    Record(ctx context.Context, entry AuditEntry) error
}

// MockProvider Mock 数据提供接口
type MockProvider interface {
    Match(ctx context.Context, req *Request) bool
    Response(ctx context.Context, req *Request) (*Response, error)
}
设计要点：接口方法签名中的 context.Context 用于传递链路追踪 ID、超时控制；返回 error 使得调用方可以统一处理异常，这是 Go 网关编程的标准范式。

2.1.2 接口组合与插件链

网关通常使用接口组合来构建插件链：

// Plugin 组合了多个职责
type Plugin interface {
    Handler
    Authenticator
    Auditor
    MockProvider
}

// 插件注册表
type Registry struct {
    plugins map[string]Plugin
}

func (r *Registry) Register(name string, p Plugin) {
    r.plugins[name] = p
}
网关插件接口组合架构 网关插件接口组合架构 Handler Authenticator Auditor MockProvider Plugin（组合接口） Handler Authenticator Auditor MockProvider Registry map[string]Plugin Register(name, p) Get(name) Plugin 接口组合实现“插件化”：每个插件只需实现 Plugin 接口，即可被注册到网关链中 网关按顺序调用各插件方法，实现认证→审计→Mock 的完整流程

2.2 结构体（struct）：数据模型与配置管理

结构体是网关中承载请求、响应、配置、审计日志的主要数据类型。通过字段标签（Tag）可以实现序列化、验证、ORM 映射等能力。

2.2.1 核心数据模型

// Request 网关统一请求结构
type Request struct {
    Method  string            `json:"method" validate:"required"`
    Path    string            `json:"path" validate:"required"`
    Headers map[string]string `json:"headers"`
    Body    []byte            `json:"body"`
    Token   string            `json:"token"`
}

// Response 网关统一响应结构
type Response struct {
    StatusCode int               `json:"status_code"`
    Headers    map[string]string `json:"headers"`
    Body       []byte            `json:"body"`
}

// AuditEntry 审计日志条目
type AuditEntry struct {
    RequestID  string    `json:"request_id"`
    UserID     string    `json:"user_id"`
    Action     string    `json:"action"`
    Resource   string    `json:"resource"`
    Result     string    `json:"result"`
    Timestamp  time.Time `json:"timestamp"`
    DurationMs int64     `json:"duration_ms"`
}

2.2.2 结构体方法：行为封装

在网关开发中，常为结构体绑定方法来实现业务逻辑：

// MockRule Mock 规则配置
type MockRule struct {
    PathPattern string            `yaml:"path_pattern"`
    Method      string            `yaml:"method"`
    StatusCode  int               `yaml:"status_code"`
    ResponseBody string           `yaml:"response_body"`
    Headers     map[string]string `yaml:"headers"`
}

// Match 判断请求是否匹配当前 Mock 规则
func (m *MockRule) Match(req *Request) bool {
    if m.Method != "" && m.Method != req.Method {
        return false
    }
    // 使用 path.Match 进行模式匹配
    matched, _ := path.Match(m.PathPattern, req.Path)
    return matched
}

// BuildResponse 根据规则构造响应
func (m *MockRule) BuildResponse() *Response {
    return &Response{
        StatusCode: m.StatusCode,
        Headers:    m.Headers,
        Body:       []byte(m.ResponseBody),
    }
}
实战建议：结构体方法让数据与操作内聚。在 Mock 隔离场景中，MockRule.Match() 和 MockRule.BuildResponse() 使得规则判断与响应构造逻辑清晰分离，便于单元测试。

2.3 错误处理（error）：网关的健壮性保障

Go 的 error 接口是网关中传递异常信息的标准方式。在权限审计网关中，错误处理需要区分“客户端错误”、“服务端错误”、“Mock 降级”等场景。

2.3.1 自定义错误类型

// GatewayError 网关自定义错误
type GatewayError struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Err     error  `json:"-"`
}

func (e *GatewayError) Error() string {
    return fmt.Sprintf("code=%d, message=%s, err=%v", e.Code, e.Message, e.Err)
}

func (e *GatewayError) Unwrap() error {
    return e.Err
}

// 预定义错误常量
var (
    ErrAuthFailed     = &GatewayError{Code: 401, Message: "authentication failed"}
    ErrForbidden      = &GatewayError{Code: 403, Message: "access denied"}
    ErrRateLimited    = &GatewayError{Code: 429, Message: "rate limit exceeded"}
    ErrMockNotFound   = &GatewayError{Code: 404, Message: "mock rule not found"}
    ErrInternal       = &GatewayError{Code: 500, Message: "internal server error"}
)

2.3.2 错误处理链模式

网关的插件链中，每个插件处理完返回 error，由链管理器决定是否继续执行或降级：

// Chain 插件执行链
type Chain struct {
    plugins []Plugin
}

func (c *Chain) Execute(ctx context.Context, req *Request) (*Response, error) {
    for _, p := range c.plugins {
        // 先执行认证
        userInfo, err := p.Authenticate(ctx, req.Token)
        if err != nil {
            // 认证失败：记录审计并返回 401
            p.Record(ctx, AuditEntry{Result: "AUTH_FAILED", Error: err.Error()})
            return nil, fmt.Errorf("auth: %w", err)
        }
        // 检查 Mock 规则
        if p.Match(ctx, req) {
            return p.Response(ctx, req)
        }
        // 执行实际处理
        resp, err := p.ServeHTTP(ctx, req)
        if err != nil {
            // 处理失败：记录审计
            p.Record(ctx, AuditEntry{Result: "HANDLER_ERROR", Error: err.Error()})
            return nil, fmt.Errorf("handler: %w", err)
        }
        // 记录成功审计
        p.Record(ctx, AuditEntry{Result: "SUCCESS"})
        return resp, nil
    }
    return nil, ErrInternal
}
网关错误处理链与降级流程 网关错误处理链与降级流程 请求进入 Authenticate() 认证成功？ 返回 401 记录审计日志 Mock 匹配？ 返回 Mock ServeHTTP() 处理

2.4 核心用法对比表

特性 接口（interface） 结构体（struct） 错误处理（error）
网关角色 插件契约、行为抽象 数据模型、配置载体 异常传递、降级决策
典型场景 Authenticator、Auditor 接口 Request、Response、MockRule GatewayError、错误链
组合方式 接口组合（Plugin） 结构体嵌套、方法绑定 errors.Is / errors.As / %w
Mock 隔离中的用途 MockProvider 接口定义 MockRule 规则存储与匹配 ErrMockNotFound 降级处理
测试友好度 高（可 mock 实现） 高（直接构造实例） 高（可断言错误类型）
常见陷阱：
  • 接口定义过于庞大（应遵循“小接口”原则，每个接口 1~3 个方法）
  • 结构体字段未使用标签导致 JSON/YAML 序列化字段名不一致
  • 错误处理中忽略 errors.Is 和 errors.As，直接使用 == 比较 error 导致无法匹配包装错误
  • Mock 规则匹配失败时未返回明确的 ErrMockNotFound，导致调用方无法区分“无规则”和“规则匹配失败”

2.5 本章小结

接口、结构体、错误处理是 Go 网关开发的三大基石：

  • 接口定义了插件的契约，使得认证、审计、Mock 等模块可以独立开发、灵活组合。
  • 结构体承载了请求/响应数据、配置规则和审计日志，通过方法绑定实现内聚的业务逻辑。
  • 错误处理通过自定义错误类型和错误链，实现了网关的健壮降级和可观测性。
← 上一章 📖 返回目录 下一章 →