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

在构建图谱评分 API 时，遵循统一的接口设计原则是保障系统可维护性、可扩展性与团队协作效率的基石。RESTful 风格是目前业界最广泛采用的 API 设计范式，其核心在于将后端功能抽象为“资源”，并通过标准的 HTTP 协议进行操作。本章将围绕资源命名、HTTP 方法选择与状态码设计三个关键维度展开，确保你的图谱评分接口既符合规范，又具备良好的可读性与自描述能力。

2.1 RESTful 设计核心规范

REST（Representational State Transfer）是一种架构风格，而非强制标准。对于图谱评分 API，我们重点关注以下六项约束，它们共同保证了接口的轻量、无状态与统一接口特性：

  • 客户端-服务器分离：前端只关心 UI 与交互，后端只负责数据存储与业务逻辑，两者通过 API 契约解耦。
  • 无状态：每次请求必须包含所有必要信息，服务器不保存客户端上下文。评分请求中需携带完整的图谱 ID、评分维度与认证令牌。
  • 可缓存：响应应明确标记是否可缓存（如评分规则列表可缓存，单次评分结果不可缓存），以提升性能。
  • 统一接口：通过标准 HTTP 方法（GET/POST/PUT/DELETE）操作资源，并使用统一的状态码反馈结果。
  • 分层系统：客户端无需知道直接通信的是网关、负载均衡器还是应用服务器，各层职责独立。
  • 按需代码（可选）：服务器可临时向客户端传输可执行代码（如评分脚本），但本课程中不强制使用。
设计提示：图谱评分 API 属于数据密集型接口，建议严格遵循“无状态”原则。不要在服务端 Session 中存储评分进度，每次请求都应独立完成一个完整的评分操作或查询。
RESTful 架构分层与请求流转 客户端 Web / 移动端 / CLI API 网关 认证 / 限流 / 路由 评分服务 业务逻辑 / 计算 数据存储 图谱 / 评分记录 核心原则： 统一接口 + 无状态 + 分层解耦，每层只关注自身职责。

2.2 资源命名规范

资源是 RESTful API 的核心抽象。图谱评分 API 中的资源命名应遵循以下规范，以保证 URL 的直观性与一致性：

规范项 推荐做法 反例
使用名词复数 /graphs、/scores、/rules /getGraph、/graphScore
小写字母 + 连字符 /score-rules、/graph-versions /scoreRules、/graph_versions
层级关系用斜杠 /graphs/{graphId}/scores /graphs/{graphId}/getScores
查询参数过滤 /scores?status=completed /scores/completed
避免动词 /graphs/{graphId}/publish（特殊动作可用） /graphs/{graphId}/doPublish
图谱评分 API 资源路径示例： 
# 图谱资源
GET    /graphs                          # 获取图谱列表
POST   /graphs                          # 创建新图谱
GET    /graphs/{graphId}                # 获取单个图谱详情
PUT    /graphs/{graphId}                # 更新图谱信息
DELETE /graphs/{graphId}                # 删除图谱

# 评分资源（子资源）
GET    /graphs/{graphId}/scores         # 获取某图谱的所有评分
POST   /graphs/{graphId}/scores         # 对图谱发起一次评分
GET    /graphs/{graphId}/scores/{scoreId}  # 获取单次评分详情

# 评分规则资源
GET    /score-rules                     # 获取评分规则列表
POST   /score-rules                     # 创建新评分规则

2.3 HTTP 方法选择

每个 HTTP 方法对应一种标准操作，图谱评分 API 中应严格区分使用：

HTTP 方法 CRUD 对应 图谱评分 API 典型用途 幂等性
GET 读取 查询图谱列表、获取评分详情、查看评分规则 是
POST 创建 创建新图谱、发起评分、触发评分重算 否
PUT 全量替换 更新图谱全部属性、替换评分规则 是
PATCH 部分更新 更新图谱名称、修改评分状态 否
DELETE 删除 删除图谱、删除评分记录 是
注意事项：POST 用于创建资源时，服务端应返回 201 Created 状态码及新资源的 Location 头。对于幂等性要求高的操作（如重复提交评分），建议在请求体中引入幂等键（Idempotency-Key），防止重复计分。

2.4 状态码设计

合理的 HTTP 状态码能让客户端无需解析响应体即可判断请求结果。图谱评分 API 应覆盖以下核心状态码：

状态码 含义 图谱评分 API 使用场景
200 OK 请求成功 GET 查询成功、PUT/PATCH 更新成功
201 Created 资源创建成功 POST 创建图谱或评分成功
204 No Content 操作成功，无返回体 DELETE 删除成功
400 Bad Request 请求参数错误 评分维度缺失、图谱 ID 格式错误
401 Unauthorized 未认证 缺少或无效的 API Token
403 Forbidden 无权限 用户无权操作指定图谱
404 Not Found 资源不存在 图谱 ID 或评分 ID 不存在
409 Conflict 资源冲突 创建重复图谱名称、评分版本冲突
422 Unprocessable Entity 语义错误 评分规则表达式语法错误
429 Too Many Requests 限流 超过 API 调用频率限制
500 Internal Server Error 服务端内部错误 评分引擎异常、数据库连接失败
503 Service Unavailable 服务暂时不可用 系统维护中、评分队列积压
最佳实践：对于 4xx 错误，响应体中应包含 error 字段说明具体原因；对于 5xx 错误，建议返回 requestId 便于日志追踪。避免将业务逻辑错误（如评分分数超范围）映射为 500，应使用 400 或 422。
API 状态码决策流程 收到 API 请求 认证通过？ 权限足够？ 执行业务逻辑 401 Unauthorized 403 Forbidden 决策要点：先认证 → 再鉴权 → 最后执行业务，失败时返回对应 4xx 状态码。

2.5 综合设计示例

以下是一个完整的图谱评分 API 接口设计示例，综合了资源命名、HTTP 方法与状态码规范：

图谱评分 API 接口清单（部分）： 
# 图谱管理
POST   /graphs                          → 201 Created
GET    /graphs                          → 200 OK
GET    /graphs/{graphId}                → 200 OK / 404 Not Found
PUT    /graphs/{graphId}                → 200 OK / 404 Not Found
DELETE /graphs/{graphId}                → 204 No Content / 404 Not Found

# 评分操作
POST   /graphs/{graphId}/scores         → 201 Created / 422 Unprocessable Entity
GET    /graphs/{graphId}/scores         → 200 OK
GET    /graphs/{graphId}/scores/{scoreId} → 200 OK / 404 Not Found

# 评分规则
GET    /score-rules                     → 200 OK
POST   /score-rules                     → 201 Created / 409 Conflict
PUT    /score-rules/{ruleId}            → 200 OK / 404 Not Found
DELETE /score-rules/{ruleId}            → 204 No Content / 404 Not Found
版本管理建议：建议在 URL 前缀中加入版本号，例如 /v1/graphs。当评分算法或资源结构发生不兼容变更时，通过版本号平滑过渡，避免影响已有客户端。
← 上一章 📖 返回目录 下一章 →