PHPAPI开发笔记
分享

PHPAPI开发笔记

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

设置响应头

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

header('Access-Control-Allow-Origin: *'); // 允许所有来源访问
header('Access-Control-Allow-Methods: 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-Methods: 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. 请求方法：例如 POST 或 GET。
  4. 请求URL：接口的访问地址。
  5. 请求参数：参数名、类型、是否必填、说明
  6. 返回参数：参数名、类型、说明