4. API 设计原则：RESTful vs gRPC 选择、无状态设计、幂等性、版本控制策略

低延迟因子评分接口对传输效率、状态约束与接口稳定性有极高要求。本章从协议选型、架构约束、操作语义与版本演进四个维度，给出量化场景下的 API 设计原则与落地规范。

4.1 协议选型：RESTful vs gRPC

因子评分接口通常承载高频、小体量的请求（单次请求 200–500 字节），且对端到端延迟敏感。RESTful（HTTP/1.1 + JSON）与 gRPC（HTTP/2 + Protobuf）在序列化效率、连接复用与生态成熟度上存在显著差异。

4.2 无状态设计

因子评分接口必须遵循无状态（Stateless）约束：每个请求包含服务端处理所需的全部信息，服务端不存储客户端会话状态。无状态设计带来三个关键收益：

• 水平扩展无瓶颈：任意实例可处理任意请求，无需 session 亲和性。
• 故障恢复即时：实例重启后无需重建会话，客户端重试即可。
• 请求可独立缓存：相同入参的评分结果可在 CDN 或本地缓存层命中。

在因子评分场景中，无状态设计的具体落地规范：

• 请求中携带完整的因子快照（因子 ID、时间戳、参数值），不依赖服务端历史数据。
• 认证信息通过 Authorization 头传递，不依赖 Cookie 或 Session。
• 幂等键（Idempotency-Key）由客户端生成并随请求发送，服务端不维护客户端状态机。

4.3 幂等性设计

低延迟链路中网络抖动、客户端超时重试是常态。因子评分接口必须保证幂等性：同一请求无论执行一次还是多次，对系统产生的影响相同。

幂等性分级实现策略：

幂等键处理流程（gRPC 拦截器示例）：

// 幂等键拦截器伪代码
func IdempotencyInterceptor(ctx context.Context, req interface{},
    info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
    key := metadata.Value(ctx, "idempotency-key")
    if key == "" {
        return nil, status.Error(codes.InvalidArgument, "missing idempotency-key")
    }
    // 检查 Redis 中是否已存在该 key 的处理结果
    if result, found := cache.Get(key); found {
        return result, nil
    }
    // 执行实际处理
    resp, err := handler(ctx, req)
    if err == nil {
        cache.Set(key, resp, ttl) // 缓存结果，ttl 根据业务设置
    }
    return resp, err
}

4.4 版本控制策略：URL 路径版本号

因子评分模型和算法会持续迭代，API 版本控制是向后兼容的基础。本指南采用 URL 路径版本号策略，将主版本号直接嵌入路径：

# RESTful 风格
GET /v1/factors/alpha101/score
POST /v2/factors/alpha101/score

# gRPC 风格（proto package 版本）
package factorscore.v1;
package factorscore.v2;

版本号规则：

• 主版本号（v1, v2…）：不兼容变更时递增，包括：删除字段、修改字段类型、变更评分算法逻辑。
• 次版本号：不体现在 URL 中，通过响应头 X-API-Minor-Version 传递。
• 补丁版本：内部发布标记，不对外暴露。

版本生命周期管理：

4.5 设计原则总览

以下 SVG 图总结了因子评分接口 API 设计的四个核心原则及其相互关系：

4.6 设计决策检查清单

在开始因子评分接口设计前，逐项确认以下决策点：

• 协议选型：内部链路用 gRPC，外部接口用 RESTful？是否需要在网关层做协议转换？
• 无状态：请求是否携带完整因子上下文？认证信息是否通过 Header 传递？
• 幂等性：写操作是否实现了幂等键机制？幂等键的存储后端（Redis/本地缓存）是否高可用？
• 版本控制：当前设计是 v1 还是 v2？废弃版本是否有 Sunset 头通知客户端？
• 兼容性：新增字段是否使用 optional？是否避免删除已有字段？