2. API架构基础：RESTful与GraphQL在精算场景的选型

精算模型从离线批次计算走向实时API服务，首先面临的是API架构选型。RESTful API与GraphQL是当前最主流的两种风格，它们在数据获取方式、缓存策略、性能特征上存在本质差异。本章从精算场景出发，对比两种架构的适用边界，并给出选型决策框架。

2.1 RESTful API设计原则

REST（Representational State Transfer）是一种基于资源的架构风格，核心原则包括：

• 资源导向：每个精算实体（保单、准备金、风险因子）对应唯一URI
• 无状态：每次请求包含所有必要信息，服务器不保存客户端上下文
• 统一接口：使用标准HTTP方法（GET/POST/PUT/DELETE）操作资源
• 可缓存：响应明确标记是否可缓存，降低重复计算开销

2.2 GraphQL简介

GraphQL由Facebook提出，允许客户端精确指定所需字段，避免过度获取（over-fetching）或获取不足（under-fetching）。在精算场景中，GraphQL特别适合以下情况：

• 前端需要从多个精算模型聚合数据（如同时查询死亡率、退保率、费用率）
• 移动端或低带宽环境需要最小化传输数据量
• 模型输出结构频繁变化，需要灵活的数据契约

// GraphQL查询示例：同时获取多个精算指标
query {
  policy(id: "POL-2024-001") {
    premium
    reserve {
      bestEstimate
      riskMargin
    }
    mortalityFactor(scenario: "base") {
      qx
      confidenceInterval
    }
  }
}

2.3 精算场景下的API选型对比

下表从精算模型发布的核心关注点出发，对比RESTful与GraphQL的差异：

2.4 精算API架构决策流程

下图展示了精算模型发布时的API选型决策流程：

2.5 精算场景API选型检查清单

在实际项目中，建议按以下清单逐项评估：

1. 模型输出稳定性：输出字段是否频繁变化？变化频繁则GraphQL更灵活
2. 调用频率与缓存收益：高频查询（如日频准备金）优先REST，利用HTTP缓存降低后端压力
3. 前端消费方：多团队、多终端消费同一模型？GraphQL schema可统一数据契约
4. 性能SLA：是否要求毫秒级响应？REST的缓存和CDN支持更成熟
5. 团队技术栈：团队是否熟悉GraphQL的DataLoader、schema设计？学习成本需纳入考量

2.6 精算API版本管理策略

精算模型会随监管要求、参数更新而迭代，API版本管理至关重要：