3. API设计原则：RESTful与gRPC选型、无状态设计、幂等性、版本控制策略

在贷后预警场景中，API设计直接决定了系统的延迟表现、运维复杂度与扩展能力。本章围绕四个核心设计原则展开：通信协议选型（RESTful vs gRPC）、无状态设计、幂等性保障以及版本控制策略。这些原则共同构成了低延迟贷后预警API的架构基石。

3.1 RESTful与gRPC选型

贷后预警API需要同时支持查询类（如客户画像、逾期记录）与命令类（如触发预警、更新策略）操作。RESTful与gRPC各有适用场景，选型需基于延迟、吞吐、客户端生态与团队能力综合判断。

3.2 无状态设计

贷后预警API必须遵循无状态原则（Stateless Design），即每个请求包含服务端处理所需的全部信息，不依赖服务端会话上下文。无状态设计是水平扩展与故障转移的前提。

• 请求自包含：认证令牌、租户ID、请求追踪ID必须由客户端在每次请求中携带。
• 会话数据外置：用户登录态、临时缓存数据存储在Redis或分布式缓存中，而非服务端内存。
• 无状态带来的收益：
  • 任意实例可处理任意请求，实现真正的水平扩展。
  • 实例故障后，流量自动切换到健康实例，无会话丢失风险。
  • 简化运维：滚动更新、蓝绿部署无需考虑会话粘滞。

3.3 幂等性

贷后预警场景中，网络重试、消息重复投递是常态。幂等性（Idempotency）保证同一操作无论执行一次还是多次，结果一致。核心接口必须设计幂等键（Idempotency Key）。

3.4 版本控制策略

贷后预警API面向多个业务方（风控、运营、催收），接口演进必须平滑。版本控制策略决定了升级成本与兼容性。

• URI路径版本（推荐）：/api/v1/early-warning，直观、易于路由，适合对外API。
• 请求头版本：Accept: application/vnd.early-warning.v2+json，适合内部服务间，避免URL污染。
• 参数版本：?version=2，简单但容易遗漏，不推荐用于生产。

3.5 综合设计示例

以下是一个符合上述原则的贷后预警API接口定义示例（gRPC + RESTful双协议）：

// gRPC proto 定义（内部服务间）
service EarlyWarningService {
  rpc TriggerWarning(TriggerWarningRequest) returns (TriggerWarningResponse);
  rpc QueryWarningStatus(QueryWarningStatusRequest) returns (QueryWarningStatusResponse);
}

message TriggerWarningRequest {
  string idempotency_key = 1;   // 幂等键
  string tenant_id = 2;         // 租户ID（无状态）
  string customer_id = 3;
  WarningType type = 4;
  int32 version = 5;            // 乐观锁版本
}

// RESTful 接口（对外暴露）
// POST /api/v1/early-warning/trigger
// Headers: Idempotency-Key: uuid
//          X-Tenant-Id: tenant_001
// Body: { "customer_id": "cust_123", "type": "OVERDUE_30" }