PHP API开发:通用响应格式与状态码规范笔记

为了确保接口的返回格式统一且易于维护,我整理了一些通用的响应格式和状态码规范。这些笔记不仅帮助我在开发过程中保持一致性,也便于后续的调试和维护。

设置响应头

每个API的响应头可以统一设置如下,以确保跨域访问和正确的内容类型:

header('Access-Control-Allow-Origin:*'); // 允许所有来源访问
header('Access-Control-Allow-Method:POST,GET'); // 允许的访问方法
header('Content-type: application/json;charset=utf-8'); // 设置响应头编码为UTF-8

JSON格式化

为了确保JSON数据的可读性和一致性,可以使用 json_encode 的以下选项:

$options = JSON_NUMERIC_CHECK | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES;
echo json_encode($response, $options);
  • JSON_NUMERIC_CHECK:将所有数字字符串转换为数字。
  • JSON_PRETTY_PRINT:格式化JSON,便于阅读。
  • JSON_UNESCAPED_UNICODE:不对中文字符进行转义。
  • JSON_UNESCAPED_SLASHES:不对斜杠进行转义。

常见HTTP状态码

在处理HTTP请求时,以下是一些常见的状态码及其说明:

  • 200:请求成功,表示服务器成功处理了请求。
  • 400:请求错误,比如参数错误或请求格式不正确。
  • 401:未授权,通常指用户未提供有效的身份验证信息。
  • 403:禁止访问,用户没有权限访问该资源。
  • 404:资源未找到,表示请求的API端点不存在。

BaseResponse 响应格式

为了使API响应格式保持一致,可以使用一个通用的 BaseResponse 函数:

function BaseResponse($code, $message, $data = []) {
    $response = [
        'code' => $code,
        'message' => $message,
        'data' => $data
    ];
    
    // 设置响应头
    header('Access-Control-Allow-Origin:*');
    header('Access-Control-Allow-Method:POST,GET');
    header('Content-type: application/json;charset=utf-8');
    
    // 输出JSON
    echo json_encode($response, JSON_NUMERIC_CHECK | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    exit();
}

接口文档规范

编写接口文档时,可以按照以下结构进行描述:

  1. 接口标题:简要描述接口的功能。
  2. 接口描述:详细说明接口的作用。
  3. 请求方法:例如 POSTGET
  4. 请求URL:接口的访问地址。
  5. 请求参数
    • 参数名
    • 类型
    • 是否必填
    • 说明
  6. 返回参数
    • 参数名
    • 类型
    • 说明

示例:用户登录API

接口标题:用户登录

接口描述:用于用户登录并获取Token。

请求方法POST

请求URL/api/v1/login

请求参数

参数名类型必填说明
usernamestring用户名
passwordstring密码

返回参数

参数名类型说明
codeint状态码
messagestring响应消息
dataobject返回的数据
tokenstring用户身份Token

请求示例

{
    "username": "user123",
    "password": "password123"
}

返回示例

{
    "code": 200,
    "message": "登录成功",
    "data": {
        "token": "abcdefg123456"
    }
}

最后

这些笔记是我在API开发过程中总结出的经验,希望能对其他开发者有所帮助。通过统一的响应格式和规范的接口文档,可以有效提升API的可维护性和一致性。这些内容虽然是个人观点,但我相信在实际开发中也会带来不少便利。如果你有不同的见解或改进建议,欢迎分享!

© 版权声明
THE END
喜欢就支持一下吧
点赞6 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容