PHP RESTful API接口规范

2025-07-19 21:17:41
丁国栋
原创 16
摘要：PHP RESTful API接口规范。

PHP 实现 RESTful API 的标准规范与最佳实践：

HTTP 方法规范

方法 用途 示例
GET 获取资源 GET /users（获取用户列表）
POST 创建资源 POST /users（创建新用户）
PUT 全量更新资源 PUT /users/1（更新用户 1 的所有字段）
PATCH 部分更新资源 PATCH /users/1（仅更新用户 1 的指定字段）
DELETE 删除资源 DELETE /users/1（删除用户 1）

URL 设计规范

  • 资源用名词复数：/users 而非 /getUser
  • 层级关系：/users/1/orders（用户 1 的订单）
  • 过滤分页排序： GET /users?page=1&limit=10&sort=name&status=active
  • 禁用动词：用 HTTP 方法替代 URL 中的动作（如避免 /createUser）

HTTP 状态码

场景 状态码 说明
成功 200 OK GET/PUT/PATCH 成功
创建成功 201 Created POST 成功
无内容 204 No Content DELETE 成功
客户端错误 400 Bad Request 请求参数错误
未授权 401 Unauthorized 身份未验证
禁止访问 403 Forbidden 无权限
未找到 404 Not Found 资源不存在
服务器错误 500 Internal Server Error 服务端异常

请求/响应格式

请求头

Content-Type: application/json
Authorization: Bearer {token}

响应体统一结构（JSON）

{
  "code": 200,
  "message": "success",
  "data": { ... },  // 成功时返回数据
  "error": { // 失败时返回错误详情
    "code": 404,
    "message": "Resource not found",
    "details": "User ID 100 does not exist"
  }
}

版本管理

  • 通过 URL 或请求头管理版本： https://api.example.com/v1/users 或 Accept: application/vnd.example.v1+json

日志记录

为了能实现安全审计、事件溯源、除障排错等需求，需要对API日志的进行精心的审计。 包括不限于以下内容：

时间
IP、
用户ID、
AK ID、
唯一请求ID、
请求URL、
请求参数、
请求 Headers、
请求 Body、
Token ID、
操作对象、
具体操作、
操作状态、
其他

其他工具

发表评论
博客分类