コラム・情報: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/。 - 字段只增不删,废弃字段标注。
- 破坏性变更提前通知。
- 保留过渡期。
十、验收
- 每个接口有文档和示例。
- 鉴权和越权测试通过。
- 参数校验覆盖。
- 幂等和并发测试。
- 错误码统一。
- 日志能定位。
- 限流生效。
- 压测达标。
报价和周期
按“接口数量 + 鉴权方式 + 对接系统 + 文档/测试 + 验收标准”评估。只按“一个接口多少钱”报价,后期容易因联调和变更超支。
相关阅读: