4. API基础与RESTful设计：RESTful API设计原则、HTTP方法、状态码、资源路径设计规范

在精算模型API的构建中，RESTful架构风格是连接精算模型与业务系统的桥梁。本章将系统讲解RESTful API的核心设计原则、HTTP方法语义、状态码选择策略以及资源路径的命名规范，确保你能够设计出符合行业标准、易于维护且高可用的精算模型接口。

4.1 RESTful API六大设计原则

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

4.2 HTTP方法语义与精算映射

RESTful API通过HTTP方法表达对资源的操作意图。以下是精算模型API中常用的HTTP方法及其语义：

4.3 HTTP状态码选择策略

正确的状态码能够帮助客户端快速判断请求结果，减少错误排查成本。以下是精算模型API中推荐使用的状态码：

4.4 资源路径设计规范

资源路径（Endpoint）是API的对外标识，良好的路径设计能够提升API的可读性和可维护性。以下是精算模型API的路径设计规范：

4.4.1 核心命名规则

• 使用名词复数形式： /loss-ratios 而非 /loss-ratio 或 /getLossRatio
• 使用小写字母与连字符： /intercept-rules 而非 /interceptRules 或 /intercept_rules
• 避免动词： 操作通过HTTP方法表达，路径中不应出现 /calculate、/get、/update
• 层级关系通过斜杠表达： /policies/{policyId}/claims 表示某保单下的理赔记录
• 查询参数用于过滤、排序、分页： /loss-ratios?product=auto&page=1&size=20

4.4.2 精算模型API路径示例

4.5 RESTful API架构总览

下图展示了精算模型API的RESTful架构设计，涵盖客户端、API网关、资源层与精算模型引擎的交互关系：

4.6 精算API请求与响应示例

以下是一个符合RESTful规范的赔付率计算请求与响应示例：

请求示例：POST /api/v1/loss-ratios/calculate

{
    "policyId": "POL-2024-001234",
    "productCode": "AUTO",
    "premium": 5000.00,
    "claimsIncurred": 3200.00,
    "exposureUnits": 1,
    "calculationDate": "2024-12-01"
}

成功响应：201 Created

{
    "status": "success",
    "data": {
        "lossRatioId": "LR-2024-001234",
        "lossRatio": 0.64,
        "lossRatioPercentage": "64.00%",
        "threshold": 0.70,
        "interceptRequired": false,
        "calculatedAt": "2024-12-01T10:30:00Z"
    },
    "metadata": {
        "modelVersion": "v2.3.1",
        "apiVersion": "v1"
    }
}

错误响应：422 Unprocessable Entity

{
    "status": "error",
    "error": {
        "code": "INVALID_THRESHOLD",
        "message": "赔付率阈值必须在0到1之间",
        "details": {
            "field": "threshold",
            "providedValue": 1.5,
            "allowedRange": [0, 1]
        }
    },
    "requestId": "req-abc-123-def"
}

4.7 版本管理策略

精算模型API的版本管理推荐使用URI路径前缀方式，确保向后兼容：

• URI路径版本： /api/v1/loss-ratios、/api/v2/loss-ratios
• 版本生命周期： 每个大版本至少维护6个月，废弃前提前3个月通过响应头 Deprecation: true 通知客户端
• 版本变更触发条件： 精算模型核心算法变更、请求/响应结构不兼容修改、赔付率计算逻辑重大调整