3. API架构设计原则：RESTful vs gRPC选择、无状态设计、幂等性保障

在贷后预警场景中，API架构直接决定了系统的吞吐能力、响应延迟与运维复杂度。本章围绕三个核心设计原则展开：协议选型（RESTful vs gRPC）、无状态设计与幂等性保障。这三者相互关联，共同构成低延迟预警服务的通信基石。

3.1 协议选型：RESTful vs gRPC

贷后预警API需要频繁推送风险事件、查询客户状态、批量同步数据。RESTful与gRPC各有适用场景，选型不当会直接导致延迟升高或资源浪费。

3.2 无状态设计

贷后预警API必须遵循无状态（Stateless）原则：每个请求包含服务端处理所需的全部信息，不依赖本地会话或上下文。这是实现水平扩展、故障转移和低延迟的前提。

• 会话数据外置：用户登录态、风险偏好、筛选条件统一存储在 Redis 或 Token 中，API 节点不持有任何会话。
• 请求自包含：每个预警查询请求必须携带 tenant_id、risk_level、page_token 等参数，服务端不做隐式推导。
• 无粘性路由：负载均衡器可采用轮询或一致性哈希，无需 session sticky，任意节点均可处理任意请求。
• 缓存穿透防护：无状态设计下，热点数据通过分布式缓存（Redis Cluster）共享，避免节点本地缓存不一致。

3.3 幂等性保障

贷后预警场景中，网络抖动、客户端重试、消息重复投递是常态。API 必须支持幂等性（Idempotency）：同一操作执行多次与执行一次的结果一致。

3.3.1 幂等性实现策略

3.3.2 贷后预警幂等设计要点

• 去重键设计：推荐使用 tenant_id + event_id + action 三元组作为幂等键，避免全局 UUID 带来的索引膨胀。
• 过期时间：幂等记录设置 TTL（建议 24 小时），超过时间窗口的重复请求视为新请求处理。
• 原子性写入：使用 Redis SET NX EX 或 MySQL INSERT ... ON DUPLICATE KEY 保证并发安全。
• 响应缓存：对于已处理的幂等请求，直接返回上一次的成功响应（含业务结果），避免重复计算。

3.4 三大原则协同效应

在贷后预警系统中，三个原则并非孤立存在，而是相互增强：

• 无状态 + 幂等性：无状态设计使得幂等校验可以部署在任意节点，无需共享本地缓存；幂等性保障了无状态节点在重试场景下的数据一致性。
• gRPC + 无状态：gRPC 长连接天然适合无状态服务，连接复用减少握手开销；无状态设计让 gRPC 负载均衡更简单（无需 sticky session）。
• 幂等性 + gRPC：gRPC 的 deadline 和重试机制与幂等性结合，客户端可安全重试，服务端保证最终一致性。