3. API 设计原则：RESTful 规范、资源命名、版本控制策略、状态码设计

在金融图谱 API 的设计中，遵循统一的 API 设计原则是保障系统可维护性、可扩展性与安全性的基石。本节将围绕 RESTful 架构风格，深入讲解资源命名规范、版本控制策略以及状态码设计的最佳实践。

3.1 RESTful 架构核心原则

REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，强调资源导向与无状态通信。金融图谱 API 严格遵循以下核心约束：

• 资源导向：每个 URL 代表一个唯一的资源（如实体、关系、图谱），而非操作。
• 无状态性：每个请求包含所有必要信息，服务端不保存客户端上下文。
• 统一接口：使用标准的 HTTP 方法（GET、POST、PUT、PATCH、DELETE）对资源进行 CRUD 操作。
• 自描述消息：通过 MIME 类型（如 application/json）和 HATEOAS 链接指导客户端下一步操作。

3.2 资源命名规范

资源命名直接影响 API 的可读性与一致性。金融图谱 API 采用以下命名规则：

3.3 版本控制策略

API 版本控制是保障向后兼容性的关键。金融图谱 API 采用 URL 路径版本控制 策略，将版本号显式置于路径前缀中：

# 当前稳定版本
GET /api/v1/entities/{id}

# 新版本迭代
GET /api/v2/entities/{id}

版本控制策略对比：

3.4 状态码设计

正确使用 HTTP 状态码能让客户端快速理解请求结果。金融图谱 API 状态码设计遵循以下分类：

3.5 金融图谱 API 状态码详细设计

针对金融图谱业务场景，状态码需要覆盖数据校验、权限控制与业务异常：

3.6 设计原则总结

金融图谱 API 的设计原则可归纳为以下关键要点：

1. 资源命名：使用名词复数、小写连字符、层级嵌套，避免动词和混合命名风格。
2. 版本控制：采用 URL 路径版本控制（/api/v1/），明确版本生命周期，保障向后兼容。
3. 状态码：严格区分 2xx（成功）、4xx（客户端错误）、5xx（服务端错误），金融场景扩展 422 用于图谱校验失败。
4. 错误响应：统一错误格式，包含 code、message、details，便于客户端自动化处理。
5. 无状态设计：每个请求携带完整认证信息，不依赖服务端会话，便于水平扩展。