第三方开放 API 设计文档

1. 概述

1.1 文档目的

本文档专门针对第三方系统调用设计的开放 API 规范，重点阐述 API 的验证机制、签名设计和安全策略。在第三方集成场景中，API 的安全性和可靠性至关重要，需要建立完善的认证授权体系来保护系统资源和数据安全。

本设计文档将详细描述如何构建一个安全、可靠的第三方 API 系统，包括：

  • API 签名验证机制：确保请求的完整性和真实性
  • 第三方认证体系：基于 API Key 和签名的双重验证
  • 安全防护措施：防重放攻击、限流控制、权限管理
  • 完整的调用示例：提供详细的集成指南和代码示例

1.2 适用范围

本设计文档专门适用于以下第三方集成场景：

  • 第三方合作伙伴 API：为外部合作伙伴提供的业务数据接口，如订单查询、用户信息同步等
  • 开放平台 API：面向第三方开发者的开放平台接口，如支付接口、消息推送等
  • 企业间系统集成：不同企业系统间的数据交换接口，如 ERP 集成、CRM 同步等
  • 第三方服务调用：调用外部服务的接口，如短信服务、地图服务等

1.3 设计原则

在设计第三方开放 API 时，我们遵循以下核心原则：

  • 安全第一：建立完善的签名验证机制，确保请求的完整性和真实性，防止数据篡改和重放攻击
  • 身份认证：基于 API Key + 签名的双重验证体系，确保只有授权的第三方才能访问 API
  • 权限控制：实现细粒度的权限管理，不同第三方具有不同的访问权限和资源范围
  • 防攻击设计：内置防重放攻击、限流控制、异常检测等安全防护机制
  • 标准化接口：遵循 RESTful 设计规范，提供统一、清晰的 API 接口
  • 可追溯性：完整的请求日志和审计机制，便于问题排查和安全监控

2. 第三方 API 架构设计

2.1 整体架构

第三方开放 API 系统采用专门的安全架构设计，重点突出验证和签名机制。整个系统分为六个核心层次，每一层都承担着重要的安全防护职责。

架构详细说明：

第三方客户端层（Third-party Client Layer）

第三方客户端层是专门为外部系统设计的接入层，支持多种类型的第三方系统：

  • 合作伙伴系统：具有长期合作关系的企业系统，如银行、物流公司等
  • 开放平台应用：通过开放平台注册的第三方开发者应用
  • 企业集成系统：需要数据交换的企业内部系统，如 ERP、CRM 等
  • 第三方开发者：个人或小团队开发者，通过 API 集成服务

每个第三方都需要经过严格的审核和认证流程，获得唯一的 API Key 和 Secret。

API 网关层（API Gateway Layer）

API 网关层是第三方请求的统一入口，承担着重要的安全防护功能：

  • 请求路由：根据请求路径将请求路由到相应的业务服务
  • 负载均衡：将请求分发到多个服务实例，确保高可用性
  • 限流控制：基于 API Key 和 IP 地址的请求频率限制
  • 协议转换：支持多种协议格式的转换和适配

网关层是安全防护的第一道防线，所有第三方请求都必须通过网关验证。

安全验证层（Security Validation Layer）

安全验证层是第三方 API 的核心安全机制，包含多重验证：

  • API Key 验证：验证请求头中的 API Key 是否有效且未过期
  • 签名验证：验证请求签名是否正确，确保请求未被篡改
  • 时间戳验证：检查请求时间戳是否在有效范围内（通常 5 分钟）
  • 防重放检查：通过 nonce 机制防止请求被重复提交

这一层是确保 API 安全性的关键，任何验证失败都会立即拒绝请求。

权限控制层（Permission Control Layer）

权限控制层负责细粒度的访问控制：

  • 身份认证：确认第三方身份的真实性和有效性
  • 权限验证：检查第三方是否有访问特定资源的权限
  • 资源访问控制：控制第三方可以访问哪些数据资源
  • 操作权限检查：限制第三方可以执行哪些操作（读、写、删除等）

不同级别的第三方具有不同的权限范围，确保数据安全。

业务服务层（Business Service Layer）

业务服务层提供具体的业务功能：

  • 用户服务：用户信息查询、用户状态管理等功能
  • 订单服务：订单查询、订单状态更新等功能
  • 支付服务：支付状态查询、退款处理等功能
  • 通知服务：消息推送、状态通知等功能

每个服务都经过权限验证，只返回第三方有权限访问的数据。

数据存储层（Data Storage Layer）

数据存储层提供数据持久化和审计功能：

  • MySQL 主库：存储业务数据，支持事务和一致性
  • Redis 缓存：提供高速缓存，提高响应性能
  • 审计日志：记录所有 API 调用日志，用于安全审计
  • 监控数据：收集系统运行指标，用于性能监控

2.2 安全技术栈

第三方 API 系统的技术选型重点突出安全性和可靠性，确保第三方调用的安全可控。

层级技术选型安全功能说明
API 网关Spring Cloud Gateway提供统一的安全入口，支持签名验证、限流控制、请求路由等功能
签名验证HMAC-SHA256 算法使用 HMAC-SHA256 算法生成和验证请求签名，确保请求完整性和真实性
身份认证API Key + Secret 机制基于 API Key 和 Secret 的双重验证体系，确保只有授权第三方才能访问
权限控制RBAC 权限模型基于角色的访问控制，支持细粒度的权限管理，不同第三方具有不同权限范围
防重放攻击Timestamp + Nonce 机制通过时间戳和随机数机制防止重放攻击，确保请求的唯一性和时效性
限流控制Redis + 令牌桶算法基于 Redis 的分布式限流，支持 API Key 级别和 IP 级别的限流控制
数据加密AES-256 加密对敏感数据进行 AES-256 加密存储和传输，确保数据安全
审计日志ELK Stack使用 Elasticsearch、Logstash、Kibana 收集和分析 API 调用日志，支持安全审计
监控告警Prometheus + Grafana实时监控 API 调用情况，异常情况及时告警，支持安全事件检测
数据存储MySQL + RedisMySQL 存储业务数据，Redis 提供缓存和会话存储，支持数据一致性

安全技术选型理由：

  1. 多重验证机制：API Key + 签名 + 时间戳的三重验证，确保请求的合法性和安全性
  2. 防攻击设计：内置防重放攻击、限流控制、异常检测等安全防护机制
  3. 权限最小化：基于 RBAC 模型的细粒度权限控制，遵循最小权限原则
  4. 可追溯性：完整的审计日志和监控体系，支持安全事件追踪和分析
  5. 高可用性：分布式架构设计，确保服务的高可用性和数据安全性

3. 第三方 API 验证流程设计

3.1 第三方 API 调用完整流程

第三方 API 调用流程是安全验证的核心，详细描述了从第三方发起请求到返回响应的完整安全验证过程。

详细流程说明：

第一阶段：请求接收和基础验证（步骤 1-2）

第三方系统发起 API 请求时，必须包含以下安全参数：

  • API Key：在请求头 X-API-Key 中传递，用于身份识别
  • 签名：在请求头 X-Signature 中传递，用于验证请求完整性
  • 时间戳：在请求头 X-Timestamp 中传递，用于防重放攻击
  • 随机数：在请求头 X-Nonce 中传递，确保请求唯一性

API 网关接收到请求后，首先进行基础验证：

  • 请求格式验证：检查 HTTP 方法、URL 格式、Content-Type 等是否符合规范
  • 必填参数检查：验证所有必需的安全参数是否都存在
  • 参数格式验证：检查时间戳格式、签名格式等是否正确
  • 基础限流检查：检查 IP 地址和 API Key 的请求频率是否超限

第二阶段：API Key 身份认证（步骤 3-6）

基础验证通过后，网关会验证 API Key 的有效性：

  • API Key 提取：从请求头中提取 API Key
  • API Key 验证：检查 API Key 是否存在于系统中且未过期
  • 权限查询：查询该 API Key 对应的权限范围和资源访问权限
  • 缓存查询：为了提高性能，优先从缓存中查询 API Key 信息

如果 API Key 无效或已过期，会立即返回 401 未授权错误。

第三阶段：签名验证和安全检查（步骤 7-11）

API Key 验证通过后，进行签名验证和安全检查：

  • 签名重新计算：使用相同的算法和参数重新计算签名
  • 签名对比：将计算出的签名与请求中的签名进行对比
  • 时间戳验证：检查请求时间戳是否在 5 分钟的有效期内
  • Nonce 防重放检查：验证随机数是否已被使用过，防止重放攻击

签名验证是确保请求安全性的关键步骤，任何验证失败都会拒绝请求。

第四阶段：业务处理和响应（步骤 12-19）

所有安全验证通过后，网关将请求转发给业务服务：

  • 权限检查：根据 API Key 的权限范围，检查是否有访问特定资源的权限
  • 业务处理：执行业务逻辑，查询或更新数据
  • 缓存策略：合理使用缓存提高响应性能
  • 响应封装：将业务数据封装成标准格式返回

安全验证要点：

  1. 多重验证：API Key + 签名 + 时间戳的三重验证机制
  2. 防重放攻击：通过时间戳和 Nonce 机制防止请求被重复提交
  3. 权限最小化：严格按照权限范围控制数据访问
  4. 审计日志：记录所有验证过程和业务操作，便于安全审计

3.2 第三方 API 签名验证流程

第三方 API 的签名验证是安全体系的核心，确保请求的完整性和真实性。本流程详细描述了从请求接收到签名验证的完整过程。

签名验证流程详细说明：

第一步：API Key 存在性检查

第三方系统发送 API 请求时，必须在请求头中包含 API Key：

  • API Key 位置：在请求头 X-API-Key 中传递
  • 格式要求：API Key 必须是 32 位十六进制字符串
  • 无 API Key 情况：如果请求中没有携带 API Key，系统会立即返回 401 未授权错误

第二步：API Key 格式验证

系统会验证 API Key 的格式是否符合规范：

  • 长度检查：验证 API Key 长度是否为 32 位
  • 字符检查：验证是否只包含十六进制字符（0-9, a-f, A-F）
  • 格式验证：检查是否符合预定义的格式规范

如果格式不正确，系统会返回 400 错误格式的响应。

第三步：API Key 有效性验证

系统会验证 API Key 是否有效且未过期：

  • 数据库查询：从数据库中查询 API Key 是否存在
  • 状态检查：验证 API Key 是否处于激活状态
  • 过期检查：检查 API Key 是否已过期
  • 权限查询：获取该 API Key 对应的权限范围

如果 API Key 无效或已过期，系统会返回 401 API Key 无效错误。

第四步：请求参数提取和签名构造

系统会提取请求参数并构造签名字符串：

  • 参数提取：提取 HTTP 方法、URI、请求体、时间戳、随机数等参数
  • 参数排序：按照字母顺序对参数进行排序
  • 字符串构造：按照预定义格式构造待签名字符串
  • 编码处理：对特殊字符进行 URL 编码处理

第五步：HMAC-SHA256 签名计算

系统会使用 HMAC-SHA256 算法计算签名：

  • 密钥获取：从数据库中获取与 API Key 对应的 Secret
  • 签名计算：使用 HMAC-SHA256 算法和 Secret 计算签名
  • 签名格式：将签名转换为十六进制字符串格式
  • 大小写处理：统一转换为小写格式

第六步：签名对比验证

系统会将计算出的签名与请求中的签名进行对比：

  • 签名提取：从请求头 X-Signature 中提取签名
  • 格式统一：将两个签名都转换为相同格式
  • 逐字符比较：进行逐字符的精确比较
  • 大小写敏感：签名比较是大小写敏感的

如果签名不匹配，系统会返回 401 签名错误。

第七步：时间戳验证

系统会验证请求时间戳是否在有效期内：

  • 时间戳提取：从请求头 X-Timestamp 中提取时间戳
  • 格式验证：验证时间戳格式是否为 Unix 时间戳（秒）
  • 时间范围检查：检查时间戳是否在 5 分钟的有效期内
  • 时钟同步：考虑服务器时钟差异，设置合理的容错范围

如果时间戳超时，系统会返回 401 时间戳超时错误。

第八步：Nonce 防重放检查

系统会检查随机数是否已被使用过：

  • Nonce 提取：从请求头 X-Nonce 中提取随机数
  • 格式验证：验证 Nonce 格式是否正确
  • 重复检查：检查该 Nonce 是否在最近 5 分钟内已被使用
  • 存储管理：将使用过的 Nonce 存储到缓存中

如果 Nonce 已被使用，系统会返回 401 重放攻击错误。

第九步：权限范围验证

最后一步是检查第三方是否有访问特定资源的权限：

  • 资源识别：根据请求路径识别要访问的资源
  • 权限查询：查询该 API Key 是否有访问该资源的权限
  • 操作权限：检查是否有执行特定操作的权限（GET、POST、PUT、DELETE）
  • 数据范围：验证可以访问的数据范围（如特定用户的数据）

如果权限不足，系统会返回 403 权限不足错误。

安全最佳实践：

  1. API Key 管理：定期轮换 API Key 和 Secret，避免长期使用同一密钥
  2. 签名算法：使用强加密算法（HMAC-SHA256），避免使用弱加密算法
  3. 时间同步：确保客户端和服务器时间同步，避免时间戳验证失败
  4. Nonce 管理：使用足够随机的 Nonce，避免被猜测或重复使用
  5. 权限最小化：遵循最小权限原则，只授予第三方必要的权限
  6. 审计日志：记录所有签名验证过程，便于安全审计和问题排查

4. 第三方 API 签名设计规范

第三方 API 的签名设计是安全体系的核心，需要建立统一、标准化的签名规范，确保所有第三方都能正确实现签名验证。

4.1 签名算法规范

4.1.1 签名算法选择

第三方 API 统一使用 HMAC-SHA256 算法进行签名计算：

  • 算法名称：HMAC-SHA256
  • 密钥长度：256 位（32 字节）
  • 输出格式：十六进制字符串（小写）
  • 安全性：提供 128 位的安全强度

选择理由：

  • HMAC-SHA256 是业界标准，安全性高
  • 计算效率高，适合高并发场景
  • 支持多种编程语言，易于实现
  • 抗碰撞能力强，安全性可靠

4.1.2 签名参数规范

签名计算需要包含以下参数：

参数名称参数位置是否必需格式要求说明
HTTP 方法请求行是大写GET、POST、PUT、DELETE 等
URI 路径请求行是完整路径包含查询参数，如 /v1/users?page=1
请求体请求体否JSON 字符串POST/PUT 请求的请求体内容
时间戳请求头是Unix 时间戳X-Timestamp，精确到秒
随机数请求头是32 位字符串X-Nonce，确保请求唯一性
API 密钥请求头是32 位十六进制X-API-Key，用于身份识别

4.1.3 签名字符串构造规范

签名字符串按照以下格式构造：

{HTTP方法}\n{URI路径}\n{请求体}\n{时间戳}\n{随机数}\n{API密钥}

构造规则：

  1. 参数之间使用换行符（\n）分隔
  2. 请求体为空时使用空字符串
  3. 所有参数必须进行 URL 编码
  4. 参数顺序严格按照上述格式排列
  5. 字符串末尾不添加额外的换行符

示例：

POST
/v1/users
{"name":"张三","email":"zhangsan@example.com"}
1640995200
abc123def456
a1b2c3d4e5f6789012345678901234567890abcd

4.2 请求头设计规范

第三方 API 请求必须包含特定的安全请求头，用于身份认证和签名验证。

4.2.1 必需请求头

所有第三方 API 请求必须包含以下请求头：

请求头名称格式要求示例值说明
X-API-Key32 位十六进制字符串a1b2c3d4e5f6789012345678901234567890abcd第三方身份标识
X-Signature64 位十六进制字符串1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890HMAC-SHA256 签名
X-TimestampUnix 时间戳（秒）1640995200请求时间戳，防重放攻击
X-Nonce32 位随机字符串abc123def456ghi789jkl012mno345pqr随机数，确保请求唯一性
Content-TypeMIME 类型application/json请求体内容类型

4.2.2 可选请求头

根据业务需要，可以包含以下可选请求头：

请求头名称格式要求示例值说明
X-Request-IDUUID 格式550e8400-e29b-41d4-a716-446655440000请求唯一标识，用于追踪
X-Client-Version版本号1.0.0客户端版本号，用于兼容性管理
X-User-Agent字符串MyApp/1.0.0客户端标识信息

4.2.3 请求头验证规则

系统会对请求头进行以下验证：

  • 格式验证：检查请求头格式是否符合规范
  • 长度验证：验证请求头值的长度是否在允许范围内
  • 字符验证：检查是否包含非法字符
  • 必填验证：确保所有必需的请求头都存在

4.3 URL 设计规范

第三方 API 的 URL 设计遵循 RESTful 规范，同时考虑安全性和易用性。

4.3.1 URL 基本格式

第三方 API 的 URL 遵循以下格式：

https://api.example.com/v1/{resource}/{id}?{query_params}

URL 组成部分说明：

  • 协议：强制使用 HTTPS 协议，确保数据传输安全
  • 域名：使用专门的 API 域名，如 api.example.com
  • 版本号：在 URL 中包含版本号，如 v1，便于版本管理和兼容性
  • 资源名：使用名词表示资源，如 users、orders 等
  • 资源 ID：使用资源的唯一标识符，如 123
  • 查询参数：用于过滤、分页、排序等操作

4.3.2 命名规范

第三方 API 的命名遵循以下规范：

  • 使用小写字母和连字符：URL 中的单词使用小写字母，单词之间用连字符（-）分隔
  • 资源名使用复数形式：表示资源集合时使用复数形式，如 users、orders
  • 避免使用动词：URL 中不包含动词，操作通过 HTTP 方法表示
  • 使用有意义的名称：选择能够清楚表达资源含义的名称

4.3.3 API 端点示例

以下是一些典型的第三方 API 端点示例：

# 用户管理 API
GET    /v1/users                    # 获取用户列表
GET    /v1/users/{user_id}          # 获取指定用户信息
POST   /v1/users                    # 创建新用户
PUT    /v1/users/{user_id}          # 更新用户信息
DELETE /v1/users/{user_id}          # 删除用户

# 订单管理 API
GET    /v1/orders                   # 获取订单列表
GET    /v1/orders/{order_id}        # 获取订单详情
POST   /v1/orders                   # 创建订单
PUT    /v1/orders/{order_id}        # 更新订单状态
DELETE /v1/orders/{order_id}        # 取消订单

# 数据同步 API
GET    /v1/sync/users               # 同步用户数据
POST   /v1/sync/orders              # 同步订单数据
GET    /v1/sync/status              # 查询同步状态

5. 安全措施设计

5.1 防重放攻击机制

5.1.1 时间戳验证

系统通过时间戳验证防止重放攻击：

  • 时间窗口：请求时间戳必须在 5 分钟的有效期内
  • 时钟同步：考虑客户端和服务器时钟差异，设置 30 秒的容错范围
  • 时间格式：使用 Unix 时间戳（秒）格式，便于计算和比较
  • 验证逻辑：服务器时间 - 请求时间戳 ≤ 300 秒

5.1.2 Nonce 机制

通过随机数（Nonce）机制确保请求的唯一性：

  • Nonce 生成：客户端生成 32 位随机字符串作为 Nonce
  • 唯一性检查：服务器检查该 Nonce 是否在最近 5 分钟内已被使用
  • 存储管理：将使用过的 Nonce 存储在 Redis 中，设置 5 分钟过期时间
  • 重复检测：如果 Nonce 已被使用，立即拒绝请求

5.1.3 签名验证

通过签名验证确保请求的完整性和真实性：

  • 签名算法：使用 HMAC-SHA256 算法计算签名
  • 参数完整性：签名包含所有关键参数，防止参数被篡改
  • 密钥安全：使用安全的密钥管理机制，定期轮换密钥
  • 验证严格性：签名验证失败立即拒绝请求

5.2 限流控制策略

5.2.1 多级限流机制

系统实现多级限流控制：

  • API Key 级别限流：每个 API Key 有独立的请求频率限制
  • IP 地址级别限流：对同一 IP 地址的请求频率进行限制
  • 接口级别限流：对特定接口的请求频率进行限制
  • 全局限流：对整个系统的请求频率进行限制

5.2.2 限流策略配置

不同级别的限流策略配置：

限流级别限制频率时间窗口说明
API Key1000 次/分钟1 分钟单个 API Key 的请求频率限制
IP 地址5000 次/分钟1 分钟单个 IP 地址的请求频率限制
接口级别10000 次/分钟1 分钟单个接口的请求频率限制
全局100000 次/分钟1 分钟整个系统的请求频率限制

5.2.3 限流实现机制

使用 Redis 和令牌桶算法实现限流：

  • 令牌桶算法：使用令牌桶算法实现平滑限流
  • 分布式限流：基于 Redis 实现分布式限流控制
  • 动态调整：根据系统负载动态调整限流阈值
  • 优雅降级：限流时返回友好的错误信息

5.3 权限控制设计

5.3.1 基于角色的权限控制

实现基于角色的访问控制（RBAC）：

  • 角色定义：定义不同的角色，如管理员、开发者、只读用户等
  • 权限分配：为每个角色分配相应的权限
  • 用户绑定：将 API Key 绑定到特定角色
  • 权限检查：在每次请求时检查用户是否有相应权限

5.3.2 资源级权限控制

实现细粒度的资源级权限控制：

  • 资源分类：将 API 资源按功能分类，如用户管理、订单管理、支付管理等
  • 操作权限：为每个资源定义可执行的操作，如读取、创建、更新、删除
  • 数据范围：控制用户可以访问的数据范围，如只能访问自己的数据
  • 动态权限：支持动态调整用户权限，无需重启服务

5.3.3 权限验证流程

权限验证的完整流程：

  1. 身份识别：通过 API Key 识别用户身份
  2. 角色查询：查询用户所属的角色
  3. 权限获取：获取角色对应的权限列表
  4. 资源匹配：检查请求的资源是否在权限范围内
  5. 操作验证：验证请求的操作是否被允许
  6. 数据过滤：根据权限范围过滤返回的数据

6. API 调用示例和集成指南

6.1 签名计算示例

6.1.1 签名计算步骤

第三方系统在调用 API 时需要按照以下步骤计算签名：

  1. 准备参数：收集所有必需的参数
  2. 构造字符串：按照规范格式构造签名字符串
  3. 计算签名：使用 HMAC-SHA256 算法计算签名
  4. 添加请求头：将签名和其他参数添加到请求头中

6.1.2 签名计算示例

假设第三方系统要调用用户查询接口：

请求参数：

  • HTTP 方法：GET
  • URI 路径：/v1/users/123
  • 请求体：空（GET 请求）
  • 时间戳：1640995200
  • 随机数：abc123def456ghi789jkl012mno345pqr
  • API Key：a1b2c3d4e5f6789012345678901234567890abcd

签名字符串构造：

GET
/v1/users/123

1640995200
abc123def456ghi789jkl012mno345pqr
a1b2c3d4e5f6789012345678901234567890abcd

HMAC-SHA256 计算： 使用 Secret 密钥对上述字符串进行 HMAC-SHA256 计算，得到签名： 1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890

6.1.3 请求头设置

将计算结果添加到 HTTP 请求头中：

X-API-Key: a1b2c3d4e5f6789012345678901234567890abcd
X-Signature: 1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890
X-Timestamp: 1640995200
X-Nonce: abc123def456ghi789jkl012mno345pqr
Content-Type: application/json

6.2 API 调用示例

6.2.1 用户查询接口

请求示例：

GET /v1/users/123 HTTP/1.1
Host: api.example.com
X-API-Key: a1b2c3d4e5f6789012345678901234567890abcd
X-Signature: 1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890
X-Timestamp: 1640995200
X-Nonce: abc123def456ghi789jkl012mno345pqr
Content-Type: application/json

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "user_id": "123",
    "name": "张三",
    "email": "zhangsan@example.com",
    "phone": "13800138000",
    "status": "active",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  },
  "timestamp": "2024-01-01T00:00:00Z",
  "request_id": "req_123456789"
}

6.2.2 订单创建接口

请求示例：

POST /v1/orders HTTP/1.1
Host: api.example.com
X-API-Key: a1b2c3d4e5f6789012345678901234567890abcd
X-Signature: 2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890ab
X-Timestamp: 1640995200
X-Nonce: def456ghi789jkl012mno345pqr678901
Content-Type: application/json

{
  "user_id": "123",
  "product_id": "456",
  "quantity": 2,
  "price": 99.99,
  "remark": "请尽快发货"
}

响应示例：

{
  "code": 201,
  "message": "订单创建成功",
  "data": {
    "order_id": "789",
    "user_id": "123",
    "product_id": "456",
    "quantity": 2,
    "price": 99.99,
    "total_amount": 199.98,
    "status": "pending",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "timestamp": "2024-01-01T00:00:00Z",
  "request_id": "req_123456790"
}

6.3 错误处理示例

6.3.1 签名验证失败

请求：

GET /v1/users/123 HTTP/1.1
Host: api.example.com
X-API-Key: a1b2c3d4e5f6789012345678901234567890abcd
X-Signature: invalid_signature
X-Timestamp: 1640995200
X-Nonce: abc123def456ghi789jkl012mno345pqr

响应：

{
  "code": 401,
  "message": "签名验证失败",
  "error": "Invalid signature",
  "timestamp": "2024-01-01T00:00:00Z",
  "request_id": "req_123456791"
}

6.3.2 时间戳超时

请求：

GET /v1/users/123 HTTP/1.1
Host: api.example.com
X-API-Key: a1b2c3d4e5f6789012345678901234567890abcd
X-Signature: 1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890
X-Timestamp: 1640992000
X-Nonce: abc123def456ghi789jkl012mno345pqr

响应：

{
  "code": 401,
  "message": "请求时间戳超时",
  "error": "Request timestamp expired",
  "timestamp": "2024-01-01T00:00:00Z",
  "request_id": "req_123456792"
}

6.3.3 权限不足

请求：

GET /v1/admin/users HTTP/1.1
Host: api.example.com
X-API-Key: a1b2c3d4e5f6789012345678901234567890abcd
X-Signature: 1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890
X-Timestamp: 1640995200
X-Nonce: abc123def456ghi789jkl012mno345pqr

响应：

{
  "code": 403,
  "message": "权限不足",
  "error": "Insufficient permissions to access this resource",
  "timestamp": "2024-01-01T00:00:00Z",
  "request_id": "req_123456793"
}

6.4 集成指南

6.4.1 开发环境准备

第三方系统在集成 API 前需要准备：

  1. 申请 API Key：向平台申请 API Key 和 Secret
  2. 阅读文档：仔细阅读 API 文档和签名规范
  3. 测试环境：使用测试环境进行集成测试
  4. 开发工具：准备必要的开发工具和测试工具

6.4.2 集成步骤

  1. 环境配置：配置 API 端点和认证信息
  2. 签名实现：实现签名计算和验证逻辑
  3. 错误处理：实现完善的错误处理机制
  4. 测试验证：进行全面的功能测试和安全性测试
  5. 生产部署：通过测试后部署到生产环境

6.4.3 最佳实践

  1. 安全存储：安全存储 API Key 和 Secret，避免硬编码
  2. 时间同步：确保系统时间与服务器时间同步
  3. 重试机制：实现合理的重试机制，处理网络异常
  4. 日志记录：记录详细的请求和响应日志，便于问题排查
  5. 监控告警：实现监控和告警机制，及时发现和处理问题

7. HTTP 状态码规范

第三方 API 使用标准的 HTTP 状态码来传达请求处理结果，确保客户端能够正确处理各种响应情况。

状态码含义使用场景详细说明
200OK请求成功请求已成功处理，通常用于 GET、PUT、PATCH 请求的成功响应
201Created资源创建成功新资源已成功创建，通常用于 POST 请求创建新资源后的响应
204No Content删除成功，无返回内容请求已成功处理，但不需要返回内容，通常用于 DELETE 请求
400Bad Request请求参数错误客户端请求的语法错误或参数不正确，服务器无法理解请求
401Unauthorized未授权访问请求需要身份验证，或者提供的认证信息无效或已过期
403Forbidden权限不足服务器理解请求，但拒绝执行，通常是因为权限不足或资源被禁止访问
404Not Found资源不存在请求的资源不存在，通常是因为 URL 错误或资源已被删除
409Conflict资源冲突请求与服务器当前状态冲突，通常是因为资源状态不匹配或并发冲突
429Too Many Requests请求频率超限客户端发送的请求过多，超过了服务器允许的频率限制
500Internal Server Error服务器内部错误服务器遇到意外情况，无法完成请求，通常是服务器端代码错误或系统故障

状态码使用原则：

  1. 准确性：状态码必须准确反映请求的实际处理结果
  2. 一致性：相同类型的错误应该使用相同的状态码
  3. 标准化：遵循 HTTP 标准，使用标准的状态码
  4. 可扩展性：为将来可能的新状态码预留空间

8. 总结

本文档详细描述了第三方开放 API 的设计规范，重点突出了以下核心内容：

8.1 核心安全机制

  1. 多重验证体系：API Key + 签名 + 时间戳的三重验证机制
  2. 签名算法规范：统一使用 HMAC-SHA256 算法确保请求完整性
  3. 防重放攻击：通过时间戳和 Nonce 机制防止请求被重复提交
  4. 权限控制：基于 RBAC 模型的细粒度权限管理

8.2 设计优势

  1. 安全性高：多重安全验证机制，确保 API 调用的安全性
  2. 标准化：统一的签名规范和接口设计，便于第三方集成
  3. 可扩展性：支持多级限流和权限控制，适应不同业务需求
  4. 可维护性：清晰的架构设计和完整的文档，便于系统维护

8.3 实施建议

  1. 严格遵循规范：第三方在集成时必须严格按照签名规范实现
  2. 安全存储密钥：API Key 和 Secret 必须安全存储，避免泄露
  3. 完善错误处理：实现完善的错误处理机制，提高系统稳定性
  4. 定期安全审计：定期进行安全审计和漏洞扫描，确保系统安全

通过遵循本文档的设计规范，可以构建安全、可靠、易用的第三方开放 API 系统，为业务发展提供强有力的技术支撑。

4.3 请求响应格式

4.3.1 统一响应格式

{
  "code": 200,
  "message": "success",
  "data": {
    // 具体业务数据
  },
  "timestamp": "2024-01-01T00:00:00Z",
  "requestId": "req_123456789"
}

4.3.2 分页响应格式

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}

5. 安全设计

5.1 认证机制

认证机制说明：

  • OAuth2.0：标准的授权协议
  • JWT Token：无状态的访问令牌
  • 刷新令牌：用于获取新的访问令牌
  • 作用域控制：限制 API 访问范围

5.2 安全措施

5.2.1 请求签名

// 签名算法示例
public String generateSignature(String method, String uri, String timestamp, String nonce, String secret) {
    String stringToSign = method + "\n" + uri + "\n" + timestamp + "\n" + nonce;
    return HmacSHA256(stringToSign, secret);
}

5.2.2 防重放攻击

  • 时间戳验证（5 分钟有效期）
  • 随机数（nonce）防重放
  • 请求签名验证

5.2.3 限流策略

# 限流配置示例
rateLimit:
  default: 1000/minute # 默认限流
  user: 100/minute # 用户级限流
  ip: 500/minute # IP级限流

6. 错误处理

6.1 错误处理流程

6.2 错误码规范

错误码错误类型说明HTTP 状态码
10001参数错误请求参数格式错误400
10002参数缺失必需参数缺失400
20001认证失败Token 无效或过期401
20002权限不足无访问权限403
30001业务错误业务逻辑错误400
30002资源不存在请求的资源不存在404
50001系统错误服务器内部错误500
50002服务不可用依赖服务不可用503

7. 监控和日志

7.1 监控指标

7.2 日志规范

7.2.1 日志级别

  • ERROR：系统错误，需要立即处理
  • WARN：警告信息，需要关注
  • INFO：重要业务信息
  • DEBUG：调试信息

7.2.2 日志格式

{
  "timestamp": "2024-01-01T00:00:00.000Z",
  "level": "INFO",
  "service": "user-service",
  "traceId": "trace_123456789",
  "message": "用户登录成功",
  "userId": "12345",
  "ip": "192.168.1.1"
}

8. 版本管理

8.1 版本策略

8.2 版本控制规则

  • 主版本号：不兼容的 API 修改
  • 次版本号：向后兼容的功能性新增
  • 修订号：向后兼容的问题修正

9. 性能优化

9.1 缓存策略

9.2 性能指标

指标目标值监控方式
响应时间< 200msAPM 监控
吞吐量> 1000 QPS压力测试
可用性> 99.9%健康检查
错误率< 0.1%日志分析

10. 部署和运维

10.1 部署架构

10.2 运维规范

10.2.1 发布流程

  1. 代码审查
  2. 自动化测试
  3. 灰度发布
  4. 全量发布
  5. 监控验证

10.2.2 回滚策略

  • 自动回滚：错误率超过阈值
  • 手动回滚：业务异常时
  • 数据回滚：数据一致性保证

11. 总结

本文档详细描述了开放 API 的设计规范、架构方案、安全机制和运维策略。通过遵循这些规范，可以构建安全、高效、可扩展的 API 服务，为业务发展提供强有力的技术支撑。

最近更新：:
Contributors: Duke