PHP 接口开发:联调、鉴权和错误处理

接口质量取决于五件事:契约清楚、鉴权可靠、校验严格、错误可查、联调顺畅。先把请求/响应/错误码定死,再写代码,能减少大半返工。

コラム・情報:PHP 接口开发:联调、鉴权和错误处理

一、先定契约

每个接口写清:

  • 资源和方法:GET /api/v1/orders。
  • 请求参数:位置、类型、必填、范围。
  • 响应结构:字段、类型、示例。
  • 错误码:HTTP 状态 + 业务码。
  • 鉴权方式。
  • 幂等规则。
  • 版本策略。

示例:

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": 1001,
    "status": "paid"
  },
  "trace_id": "req_abc123"
}

二、鉴权

常见方式:

  • Session/Cookie:适合同域后台。
  • Bearer Token:适合前后端分离。
  • HMAC 签名:适合服务端对服务端。
  • OAuth2:适合第三方授权。

要点:

  • 每个接口明确权限。
  • 不只在前端隐藏按钮。
  • Token 有效期和刷新机制。
  • 密钥不进代码库。
  • 失败返回统一错误,不泄露细节。

三、参数校验

  • 类型、长度、范围、枚举。
  • 必填和默认值。
  • 文件类型和大小。
  • 防注入:预处理语句、输出转义。
  • 防越权:资源归属校验。
  • 防批量赋值:只接收白名单字段。

校验失败返回 4xx,不要 500。

四、幂等与并发

  • 创建订单/支付等接口支持幂等键。
  • 重复请求返回同一结果。
  • 数据库唯一索引兜底。
  • 并发更新用版本号或行锁。
  • 避免“先查后写”的竞态。

五、错误处理

统一结构:

字段 说明
code 业务码,0 成功
message 可读信息
data 成功数据或 null
trace_id 排障追踪

HTTP 状态建议:

  • 200 成功。
  • 400 参数错误。
  • 401 未登录。
  • 403 无权限。
  • 404 不存在。
  • 409 冲突。
  • 422 业务校验失败。
  • 429 限流。
  • 500 服务异常。

不要把异常堆栈返回给前端。

六、日志与监控

  • 记录请求 ID、用户、接口、耗时、状态。
  • 敏感字段脱敏。
  • 慢接口告警。
  • 错误率告警。
  • 保留可追溯时间。

七、限流与安全

  • 按 IP/用户/接口限流。
  • 防重放:时间戳 + nonce。
  • 防 SSRF:限制回调地址。
  • 上传:类型、大小、存储隔离。
  • CORS 白名单。
  • HTTPS。

八、联调

给前端/对方:

  • 接口文档。
  • 环境地址。
  • 测试账号。
  • 示例请求和响应。
  • 错误码表。
  • Mock 数据。
  • 变更通知。

联调问题多半是契约不清,不是代码不会写。

九、版本与兼容

  • URL 版本:/api/v1/。
  • 字段只增不删,废弃字段标注。
  • 破坏性变更提前通知。
  • 保留过渡期。

十、验收

  • 每个接口有文档和示例。
  • 鉴权和越权测试通过。
  • 参数校验覆盖。
  • 幂等和并发测试。
  • 错误码统一。
  • 日志能定位。
  • 限流生效。
  • 压测达标。

报价和周期

按“接口数量 + 鉴权方式 + 对接系统 + 文档/测试 + 验收标准”评估。只按“一个接口多少钱”报价,后期容易因联调和变更超支。

相关阅读: