API 开发规范

API 面向外部系统、前端应用或自动化工具，应保持鉴权明确、响应稳定、错误可判断。

一、鉴权方式

开放 API 应使用明确的 Token、签名或授权应用机制。不要依赖后台登录态作为开放接口鉴权。

请求应能判断：

• 调用方是谁。
• 是否启用。
• 是否拥有对应 scope。
• 是否超过频率限制。
• 是否来自允许的回调来源。

二、Scope 设计

Scope 按资源和动作拆分：

content.read
content.write
member.read
order.read
upload.write

不要给第三方应用一次性开放全部后台能力。

三、响应格式

成功响应建议保持：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

错误响应建议保持：

{
  "code": 40301,
  "message": "权限不足",
  "errors": {}
}

四、分页

列表接口使用稳定分页参数：

page
per_page
cursor
since_id

大数据同步优先使用游标、时间范围或 ID 边界，不建议长期依赖深分页。

五、错误码

常见错误：

HTTP	场景
400	参数格式错误
401	未认证或 Token 无效
403	无权限或 scope 不足
404	资源不存在
409	状态冲突或重复提交
422	业务验证失败
429	请求过于频繁
500	服务端异常

六、签名和回调

外部回调必须校验签名、时间戳和随机串，避免重放攻击。支付、订单、授权类回调必须支持幂等。

幂等依据可以是：

• 第三方订单号。
• 回调事件 ID。
• 业务流水号。
• 本地状态机。

七、日志

开放 API 和重要回调应记录：

• 调用方。
• 路由和动作。
• 请求摘要。
• 响应状态。
• 错误信息。
• 耗时。

不要记录明文密码、完整 Token、AppSecret 或敏感证件号。

八、兼容策略

API 字段只能谨慎删除或改义。新增字段通常安全，删除字段和改变类型必须进入版本计划。