4. 接口调用机制总览：从用户请求到策略决策的端到端调用链路全景图

在策略即代码（Policy-as-Code, PaC）资源配额模型中，一次完整的策略决策并非孤立执行，而是由一系列紧密耦合的接口调用与中间件协作完成。本章从架构视角出发，绘制从用户发起请求到最终策略决策生效的端到端调用链路全景图，帮助读者建立全局调用视图，理解各组件在链路中的职责与交互时序。

4.1 调用链路核心阶段划分

整个调用链路可划分为四个核心阶段，每个阶段对应一组明确的接口与处理逻辑：

4.2 端到端调用链路全景图

下图展示了从用户请求到策略决策的完整调用链路，包含所有关键组件、接口方向及数据流路径：

4.3 核心接口调用时序

以下时序描述了典型场景下各组件之间的接口调用顺序与数据传递关系：

1. 请求拦截：API Gateway 或 Sidecar Proxy 拦截用户请求，提取身份、资源类型、操作类型等上下文信息，封装为标准化请求对象。
2. 策略查询：调用 Policy Engine 的 Evaluate 接口，传入请求上下文。Policy Engine 首先查询 Policy Cache，若未命中则从 Policy Store 加载最新策略。
3. 策略匹配：Policy Engine 执行规则匹配，返回匹配的策略规则集（包含配额约束条件）。
4. 配额校验：Quota Manager 接收策略规则集，调用 CheckQuota 接口。优先查询 Quota Cache，若缓存未命中则从 Quota Store 读取当前配额使用量。
5. 决策生成：Quota Manager 计算剩余配额是否满足请求，生成 Allow/Deny 决策，并附带配额余量信息。
6. 决策执行：Enforcement Point 根据决策结果执行相应操作（允许请求继续或拒绝请求），同时异步写入审计日志。
7. 响应返回：将决策结果与配额余量沿原路径返回给用户。

4.4 接口调用协议与数据格式

各阶段之间的接口调用采用统一的协议与数据格式，确保链路可观测性与兼容性：

4.5 异常场景与降级策略

在实际生产环境中，接口调用可能面临超时、缓存穿透、后端不可用等异常。以下是常见异常场景及其对应的降级策略：

• Policy Engine 超时：降级为默认策略（通常为 Deny），避免请求在无策略保护下执行。
• Quota Store 不可用：Quota Manager 回退到本地缓存副本，允许一定时间内的配额决策（最终一致性）。
• 缓存穿透：引入布隆过滤器（Bloom Filter）或空值缓存，防止大量请求直接穿透到后端存储。
• 审计日志写入失败：采用本地日志缓冲区 + 重试机制，确保关键决策不丢失。

4.6 链路可观测性设计

为保障端到端调用链路的可观测性，每个接口调用都需要注入统一的 Trace ID 与 Span ID：

// 请求上下文结构体示例
type RequestContext struct {
    TraceID    string            // 全链路追踪 ID
    SpanID     string            // 当前 Span ID
    UserID     string            // 用户标识
    ResourceID string            // 资源标识
    Action     string            // 操作类型
    Metadata   map[string]string // 扩展元数据
}

通过 Trace ID 串联所有接口调用，可以在 Jaeger 或 Zipkin 等分布式追踪系统中还原完整的调用链路，快速定位性能瓶颈与异常节点。

4.7 本章小结