2. API 设计原则：RESTful API 规范、资源命名、HTTP 方法选择、状态码设计、版本控制策略
在信用额度定价流式决策场景中，API 是业务能力与外部系统之间的契约。本章聚焦 RESTful API 的核心设计原则，确保接口具备可读性、可维护性与可扩展性。以下从资源命名、HTTP 方法、状态码与版本控制四个维度展开。
2.1 RESTful API 规范核心
REST（Representational State Transfer）强调资源导向、无状态通信与统一接口。在定价决策 API 中，每个“额度申请”、“定价策略”、“决策结果”都应视为独立资源，通过 URI 暴露，并通过标准 HTTP 方法操作。
关键约束： 无状态（Stateless）——每次请求必须包含所有必要信息，服务端不保存客户端上下文。流式决策场景下，请求 ID 与时间戳必须由客户端携带。
2.2 资源命名规范
资源命名应使用名词复数形式，采用小写字母与连字符（kebab-case），避免动词与下划线。路径层级反映资源从属关系。
| 场景 | 推荐 URI | 不推荐 URI |
|---|---|---|
| 查询所有定价策略 | GET /pricing-strategies |
GET /getPricingStrategies |
| 查询某额度申请的决策 | GET /credit-applications/{appId}/decisions |
GET /creditApplication/decision?app=123 |
| 提交流式定价请求 | POST /pricing-requests |
POST /submitPricing |
| 查询单个定价策略 | GET /pricing-strategies/{strategyId} |
GET /pricing-strategies?id=456 |
命名原则： 资源名使用名词复数；层级关系用斜杠表示；避免在 URI 中使用动词或查询参数模拟资源路径。
2.3 HTTP 方法选择
标准 HTTP 方法对应 CRUD 操作。在流式决策 API 中，POST 用于创建资源或触发异步流程，GET 用于查询，PATCH 用于部分更新定价参数。
| HTTP 方法 | 操作语义 | 定价决策场景示例 | 幂等性 |
|---|---|---|---|
GET |
查询资源 | 获取定价策略列表 | 是 |
POST |
创建资源 / 触发动作 | 提交额度定价请求 | 否 |
PUT |
全量替换资源 | 替换定价策略配置 | 是 |
PATCH |
部分更新资源 | 更新定价参数中的利率 | 否 |
DELETE |
删除资源 | 删除过期的定价策略 | 是 |
注意： 流式决策接口通常使用
POST 提交请求，因为每次请求包含动态参数且不幂等。避免使用 GET 触发状态变更。
2.4 状态码设计
状态码应精确反映请求处理结果。在定价决策 API 中，常见状态码如下：
- 200 OK：同步查询成功，返回资源数据。
- 201 Created：资源创建成功，如提交定价请求后返回决策 ID。
- 202 Accepted：请求已接受但尚未完成，适用于异步流式处理场景。
- 400 Bad Request：请求参数错误，如缺失必填字段或格式非法。
- 401 Unauthorized：认证失败或缺少有效令牌。
- 403 Forbidden：认证通过但无权限操作该资源。
- 404 Not Found：资源不存在。
- 409 Conflict：资源冲突，如重复提交相同请求 ID。
- 422 Unprocessable Entity：请求体语义错误，如定价参数超出业务范围。
- 429 Too Many Requests：触发限流。
- 500 Internal Server Error：服务端未预期异常。
- 503 Service Unavailable：服务暂时不可用，如依赖的定价引擎宕机。
最佳实践： 流式决策中，
202 Accepted 配合 Location 头部返回决策结果查询 URI，客户端轮询或通过 WebSocket 获取最终定价。
2.5 版本控制策略
API 版本控制避免向后不兼容变更影响已有客户端。推荐使用 URI 路径前缀方式，清晰且易于路由。
| 策略 | 示例 | 优点 | 缺点 |
|---|---|---|---|
| URI 路径前缀 | /v1/pricing-requests |
显式、易于缓存与路由 | 版本扩散，URI 变长 |
| 请求头 | Accept: application/vnd.pricing.v2+json |
URI 简洁，版本与媒体类型绑定 | 调试困难，客户端实现复杂 |
| 查询参数 | /pricing-requests?version=2 |
实现简单 | 易被忽略，缓存不友好 |
推荐： 定价决策 API 使用 URI 路径前缀版本控制，如
/v2/credit-applications/{appId}/decisions。至少保留一个主版本（如 v1）供旧客户端过渡，并设定废弃时间表。
2.6 设计原则总览
以下 SVG 图展示 RESTful API 设计原则在信用额度定价流式决策中的整体映射关系。
2.7 流式决策 API 设计检查清单
在信用额度定价流式决策 API 设计阶段，建议逐项核对以下清单：
- 资源模型：是否将“定价请求”、“决策结果”、“定价策略”定义为独立资源？
- URI 命名：是否使用名词复数、kebab-case、层级路径？
- HTTP 方法：是否避免用 GET 修改状态？POST 是否用于非幂等创建？
- 状态码：是否区分 400（参数错误）与 422（语义错误）？异步场景是否返回 202？
- 版本控制：是否在 URI 路径中包含主版本号？是否保留至少一个旧版本？
- 错误响应：是否统一返回错误码、消息与请求 ID？
- 幂等性：关键操作（如重复提交定价请求）是否通过请求 ID 去重？
设计建议： 在 API 设计初期，使用 OpenAPI 3.0 规范描述接口，并生成 mock 服务供前端与测试团队提前联调，减少后期返工。