3. API设计原则：RESTful规范、资源命名、HTTP方法选择、状态码设计

在信用评分API的设计中，遵循RESTful规范是确保接口可维护性、可扩展性与团队协作效率的基石。本节将围绕资源命名、HTTP方法选择与状态码设计三大核心维度展开，并结合信用评分业务场景给出具体实践指南。

3.1 RESTful核心规范

REST（Representational State Transfer）是一种基于资源的架构风格，强调通过统一的接口对资源进行无状态操作。在信用评分API中，核心资源包括：用户（User）、信用报告（CreditReport）、评分记录（ScoreRecord）、查询授权（Authorization）。

3.2 资源命名规范

资源命名应使用名词复数形式，采用小写字母与连字符（kebab-case），避免使用动词或扩展名。以下是信用评分场景中的资源命名对照表：

3.3 HTTP方法选择

每个HTTP方法对应一种标准操作，在信用评分API中应严格遵循语义映射：

• GET — 查询资源，不改变服务端状态。例如：GET /users/{id}/credit-reports 获取用户信用报告。
• POST — 创建资源或触发操作。例如：POST /score-records 发起一次评分计算。
• PUT — 全量替换资源。例如：PUT /users/{id} 更新用户全部信息。
• PATCH — 部分更新资源。例如：PATCH /authorizations/{id} 更新授权状态。
• DELETE — 删除资源。例如：DELETE /users/{id}/credit-reports/{reportId} 删除指定报告。

3.4 状态码设计

状态码是API响应语义的重要组成部分，必须覆盖成功、客户端错误、服务端错误三大类。信用评分API推荐的状态码体系如下：

3.5 响应体结构规范

统一的响应体结构有助于客户端解析与错误处理。信用评分API推荐以下标准格式：

// 成功响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "userId": "usr_20240301_001",
    "creditScore": 725,
    "reportId": "rpt_20240301_001"
  },
  "requestId": "req_abc123"
}

// 错误响应示例
{
  "code": 40001,
  "message": "参数校验失败",
  "details": [
    {
      "field": "idNumber",
      "error": "身份证号格式不正确"
    }
  ],
  "requestId": "req_def456"
}

响应体字段说明：

• code：业务状态码，0表示成功，非0表示具体错误类型。
• message：人类可读的状态描述。
• data：成功时的业务数据载体。
• details：错误详情数组，支持多字段校验错误。
• requestId：全局唯一请求标识，用于链路追踪与问题排查。