PHP API接口设计需统一响应结构、合理使用HTTP状态码与业务码、通过中间件实现鉴权限流日志、路径式版本控制、错误分级脱敏及404统一处理。
PHP 的 API 接口不是写个 echo json_encode(...) 就算完事——它得能扛住并发、方便调试、支持版本演进、被前端或第三方安全调用。设计的核心不是“怎么返回 JSON”，而是“怎么让接口可维护、可验证、可监控”。
接口必须统一响应结构，且含明确状态码
前端（或调用方）不该靠解析 data 字段是否存在来判断成功与否。HTTP 状态码 + 标准化 JSON body 是底线。
推荐结构：
{
"code": 0,
"message": "success",
"data": {...},
"timestamp": 1718234567
}
code 不是 HTTP 状态码的翻版，而是业务码：0 表示业务成功；1001 表示参数缺失；2003 表示资源不存在。HTTP 状态码仍需配合使用：400 对应参数校验失败，401 对应鉴权失败，404 对应路由/资源未找到，500 仅用于未捕获异常。
立即学习“PHP免费学习笔记（深入）”；
- 避免把所有错误都塞进
code: -1—— 后续加监控、埋点、前端 toast 分类都会变困难 - 不要在
data里嵌套code或status字段，这会造成双重语义混淆 - 开发期建议开启
display_errors = Off，用日志记录原始异常，绝不把Parse error或堆栈直接吐给客户端
用中间件统一处理鉴权、限流、日志，别塞在控制器里
每个接口都写一遍 if (!checkToken()) { die(json_encode(['code'=>401])) } 是反模式。PHP 虽无原生中间件机制，但可通过 PSR-15 兼容的轻量框架（如 Slim、Laravel Octane 配合 Swoole）或自建路由分发层实现。
典型中间件链顺序应为：
- 请求日志中间件（记录 IP、URI、耗时、
$_SERVER['REQUEST_TIME_FLOAT']） - 跨域中间件（设置
Access-Control-Allow-Origin等头，注意不暴露敏感 header） - 鉴权中间件（解析 Bearer Token，查 Redis 缓存 session，挂载
$request->withAttribute('user_id', $uid)） - 限流中间件（基于 IP + UID 组合 Key，用 Redis
INCR+EXPIRE实现滑动窗口） - 参数校验中间件（用 Respect/Validation 或自定义规则，失败直接返回
400和标准化错误）
关键点：中间件之间靠 $request->withAttribute() 传递上下文，而非全局变量或静态属性；限流策略要区分「登录用户」和「游客」，避免封禁爬虫时误伤真实用户。
路由版本控制必须体现在 URL 路径中，别用 Accept 头或 query 参数
用 Accept: application/vnd.myapi.v2+json 或 ?v=2 做版本控制，会导致 CDN 缓存混乱、Nginx 日志难聚合、OpenAPI 文档无法按版本生成。
正确做法是将版本号作为路径前缀：
GET /v1/usersPOST /v2/users/importDELETE /v1/users/{id}
好处是路由完全隔离，可独立部署、灰度、下线；Nginx 可按 /v1/ 和 /v2/ 分流到不同 PHP-FPM 池；Swagger UI 能直接按路径生成对应版本文档。
注意：v1 上线后，v1 路由逻辑必须冻结，新增字段只能加在 v2，旧字段废弃需走「标记弃用 → 文档警告 → 下线通知 → 最终移除」流程，不能偷偷改 v1 的返回结构。
错误信息要分级：开发环境显示详情，生产环境只给用户友好提示
线上接口返回 "message": "SQLSTATE[HY000]: General error: 1364 Field 'name' doesn't have a default value" 是严重事故。这类信息必须被拦截、脱敏、映射为用户可理解的提示。
实现建议：
- 全局异常处理器捕获
Throwable，检查APP_ENV === 'production' - 对 PDOException、ValidationException 等特定异常类型，预设映射表：
PDOException → '数据保存失败，请稍后重试'，InvalidArgumentException → '参数格式错误' - 开发环境可额外返回
debug字段（含 trace、file、line），但该字段必须被明确排除在生产响应之外，不能靠前端条件渲染隐藏 - 日志中仍需完整记录原始异常，供排查用；只是不返回给调用方
最常被忽略的一点：404 错误也需统一处理。不要让框架默认输出 “Page Not Found” HTML 页面，而应确保所有未匹配路由都走同一 JSON 错误出口，返回 {"code": 404, "message": "接口不存在"}。
