API 设计原则与规范：RESTful API 设计、资源命名、HTTP 状态码选择、版本控制策略

在贷后预警系统中，API 是业务能力对外暴露的唯一窗口。一个设计良好的 API 不仅能降低前后端联调成本，还能显著提升系统的可维护性与可扩展性。本节将围绕 RESTful 风格、资源命名、状态码语义与版本控制四个核心维度展开，结合贷后预警场景给出可落地的规范。

2.1 RESTful API 设计原则

REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，强调资源导向、无状态与统一接口。在贷后预警系统中，所有业务能力都应抽象为“资源”的增删改查操作。

原则	说明	贷后预警示例
资源导向	每个 URL 代表一个资源，而非动作	/api/v1/warnings 表示预警记录集合
无状态	每次请求包含全部必要信息，服务端不保存客户端上下文	使用 JWT Token 携带用户身份与权限
统一接口	使用标准 HTTP 方法操作资源	GET 查询、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除
可缓存	响应中显式声明缓存策略	预警规则列表可缓存 5 分钟
分层系统	客户端无需关心中间层（网关、负载均衡）	API 网关统一处理鉴权与限流

2.2 资源命名规范

资源命名是 API 可读性的第一道关卡。贷后预警系统涉及客户、合同、预警规则、预警记录、处置任务等多个核心实体，命名必须一致、清晰、可预测。

2.2.1 核心规则

• 使用名词复数形式： /customers、/contracts、/warnings、/rules
• 层级关系用斜杠表示： /customers/{customerId}/contracts
• 使用小写字母与连字符： /early-warning-rules 而非 /earlyWarningRules
• 避免动词与动作： 不要出现 /getWarnings、/createRule
• 查询参数用于过滤与排序： /warnings?status=active&page=1&size=20

2.2.2 贷后预警资源路径示例

HTTP 方法	资源路径	语义
GET	/api/v1/customers	查询客户列表
GET	/api/v1/customers/{id}	查询单个客户详情
GET	/api/v1/customers/{id}/contracts	查询客户名下的合同列表
POST	/api/v1/warnings	创建一条预警记录
PATCH	/api/v1/warnings/{id}/status	更新预警状态（如：待处理→已处置）
DELETE	/api/v1/rules/{id}	删除一条预警规则

2.3 HTTP 状态码选择策略

状态码是 API 语义的重要组成部分。贷后预警系统涉及大量业务校验与异常场景，选择正确的状态码能让调用方快速理解响应含义，减少沟通成本。

2.3.1 常用状态码分类

分类	状态码	含义	贷后预警场景
2xx 成功	200 OK	请求成功，返回数据	查询预警列表成功
	201 Created	资源创建成功	新增预警规则成功
	204 No Content	删除成功，无返回体	删除过期预警记录
4xx 客户端错误	400 Bad Request	请求参数错误	预警时间格式错误
	401 Unauthorized	未认证或 Token 过期	JWT 失效
	403 Forbidden	无权限操作	非管理员删除规则
	404 Not Found	资源不存在	查询不存在的客户 ID
	409 Conflict	资源冲突	重复创建同名预警规则
	422 Unprocessable Entity	业务校验失败	预警阈值超出允许范围
5xx 服务端错误	500 Internal Server Error	服务内部异常	数据库连接失败
	503 Service Unavailable	服务暂时不可用	预警引擎过载熔断

2.4 版本控制策略

贷后预警系统需要持续迭代，API 版本控制是保证向后兼容的关键手段。常见的版本控制方式有三种：URL 路径、请求头、查询参数。推荐使用 URL 路径版本控制，因为它最直观、最容易被网关和客户端识别。

2.4.1 版本控制方式对比

方式	示例	优点	缺点
URL 路径	/api/v1/warnings	直观、易于缓存与路由	URL 变更，需更新客户端
请求头	Accept: application/vnd.earlywarning.v2+json	URL 不变，语义清晰	调试困难，网关支持要求高
查询参数	/api/warnings?version=1	实现简单	容易遗漏，缓存混乱

2.4.2 贷后预警版本控制策略

• 主版本号（v1, v2）： 当 API 发生不兼容变更时递增，如删除字段、修改请求结构。
• 次版本号（v1.1）： 通过文档标注，不体现在 URL 中，仅增加可选字段或扩展响应。
• 废弃策略： 旧版本至少维护 6 个月，在响应头中添加 Deprecation: true 与 Sunset: Sat, 31 Dec 2025 23:59:59 GMT 通知客户端迁移。

2.5 响应体结构规范

统一的响应体结构能降低客户端解析成本。贷后预警系统建议采用以下标准格式：

2.5.1 成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "WARN-20241201-001",
    "customerId": "CUST-12345",
    "warningType": "逾期预警",
    "status": "待处理",
    "createdAt": "2024-12-01T10:30:00Z"
  },
  "requestId": "req-abc123"
}

2.5.2 错误响应

{
  "code": 10422,
  "message": "预警阈值超出允许范围",
  "details": [
    {
      "field": "threshold",
      "reason": "逾期天数阈值不能超过 180 天",
      "value": 200
    }
  ],
  "requestId": "req-def456"
}

2.6 安全与幂等性设计

贷后预警系统涉及资金与风险，API 安全与幂等性是不可忽视的设计要点。

维度	要求	实现方式
认证	所有 API 必须携带有效 Token	JWT + 刷新令牌机制
授权	细粒度权限控制	RBAC 模型，API 网关校验角色
幂等性	POST/PATCH 支持幂等重试	请求头 Idempotency-Key，服务端去重
限流	防止恶意调用与突发流量	令牌桶算法，按用户/接口限流
数据加密	敏感字段传输加密	HTTPS + 字段级 AES 加密

2.7 规范落地检查清单

在贷后预警 API 开发过程中，建议团队使用以下清单进行代码审查：

• 资源命名： 是否全部使用名词复数？是否避免动词？层级关系是否合理？
• HTTP 方法： GET 是否只用于查询？POST 是否用于创建？PATCH 是否用于部分更新？
• 状态码： 业务校验失败是否使用 422？权限不足是否使用 403？服务异常是否使用 500？
• 版本控制： URL 是否包含版本号？废弃版本是否设置 Deprecation 头？
• 响应结构： 是否统一包含 code、message、data、requestId？错误响应是否包含 details？
• 幂等性： 关键变更接口是否支持 Idempotency-Key？服务端是否实现去重逻辑？