您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 綜合知識

PHP API 接口開發規範與實戰示例：統一響應格式、錯誤碼設計、參數驗證

編輯：PHP 綜合知識

統一響應格式

{
    "code": 200,           // 業務狀態碼
    "msg": "success",      // 人類可讀信息
    "data": { ... },       // 業務數據
    "timestamp": 1699999999,
    "request_id": "req_abc123"  // 鏈路追蹤ID
}

狀態碼設計規範

範圍	含義	示例
200	成功	200
4xx	客戶端錯誤	400 參數錯誤, 401 未授權, 403 禁止, 404 不存在, 422 驗證失敗
5xx	服務端錯誤	500 內部錯誤, 503 服務不可用
-xxx	業務自定義錯誤	-201 缺少動作參數, -401 UID 為空, -402 用戶不存在

完整接口示例

<?php
header('Content-Type: application/json; charset=utf-8');

// 1. 參數獲取與基礎驗證
$action = $_GET['a'] ?? '';
$uid = (int)($_GET['uid'] ?? 0);

if (!$action) {
    exit(json_encode(['code' => -201, 'msg' => '缺少動作參數', 'data' => null]));
}

// 2. 路由分發
switch ($action) {
    case 'get_user':
        handleGetUser($uid);
        break;
    case 'get_games':
        handleGetGames();
        break;
    case 'upload_avatar':
        handleUploadAvatar();
        break;
    default:
        exit(json_encode(['code' => -400, 'msg' => '未知接口', 'data' => null]));
}

function handleGetUser($uid) {
    if ($uid <= 0) {
        exit(json_encode(['code' => -401, 'msg' => 'UID無效', 'data' => null]));
    }
    
    // 模擬數據源（實際對接 DB/Redis/微服務）
    $users = [
        10001 => ['uid'=>10001, 'nickname'=>'Shine', 'vip'=>5, 'gold'=>1500],
        10002 => ['uid'=>10002, 'nickname'=>'Elva', 'vip'=>50, 'gold'=>14320],
    ];
    
    if (!isset($users[$uid])) {
        exit(json_encode(['code' => -402, 'msg' => '用戶不存在', 'data' => null]));
    }
    
    exit(json_encode([
        'code' => 200,
        'msg' => 'success',
        'data' => [
            'userInfo' => $users[$uid],
            'isLogin' => true,
            'unread' => 4,
            'untask' => 3,
        ]
    ]));
}

function handleGetGames() {
    exit(json_encode(['code' => 200, 'msg' => '調用 get_games_result', 'data' => []]));
}

function handleUploadAvatar() {
    exit(json_encode(['code' => 200, 'msg' => '調用 upload_avatars', 'data' => []]));
}

最佳實踐棧

1. 參數驗證層

// 使用 respect/validation 或自建驗證器
$v = new Validator();
$v->rule('required', $uid, 'UID不能為空');
$v->rule('integer', $uid, 'UID必須為整數');
$v->rule('min', $uid, 1, 'UID必須大於0');
if (!$v->validate()) {
    exit(json_encode(['code' => 422, 'msg' => '驗證失敗', 'errors' => $v->errors()]));
}

2. 異常統一處理

try {
    // 業務邏輯
} catch (BusinessException $e) {
    exit(json_encode(['code' => $e->getCode(), 'msg' => $e->getMessage(), 'data' => null]));
} catch (\Throwable $e) {
    log_error($e);
    exit(json_encode(['code' => 500, 'msg' => '服務器內部錯誤', 'data' => null]));
}

3. 簽名驗證（開放平台必備）

function verifySign($params, $secret) {
    ksort($params);
    $sign = $params['sign'];
    unset($params['sign']);
    $str = http_build_query($params) . $secret;
    return hash_hmac('sha256', $str, $secret) === $sign;
}

4. 限流保護

// Redis 滑動窗口限流
$key = "ratelimit:api:{$uid}:{$action}";
$count = $redis->incr($key);
if ($count === 1) $redis->expire($key, 60);
if ($count > 100) exit(json_encode(['code' => 429, 'msg' => '請求過於頻繁']));