API 核心觀念

• API = 資料輸出介面，無視圖層（無 MVC 中的 V），通常採用 JSON 格式。
• 客戶端（App、前端 SPA、第三方）透過 HTTP 請求（GET/POST）呼叫，伺服器回傳結構化資料。

最小可行 API 範例 (api.php)

<?php
// 統一回應格式
function jsonResponse(array $data, int $code = 200, string $msg = '') {
    http_response_code($code);
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode(['code' => $code, 'msg' => $msg, 'data' => $data], JSON_UNESCAPED_UNICODE);
    exit;
}

// 參數驗證
$action = $_GET['a'] ?? '';
$uid    = (int)($_GET['uid'] ?? 0);

if (!$action) jsonResponse(null, -201, '缺少動作參數 a');

// 模擬資料庫
$users = [
    10001 => ['uid'=>10001, 'nickname'=>'Shine X', 'email'=>'979137@qq.com', 'level'=>19],
    10002 => ['uid'=>10002, 'nickname'=>'elva',    'email'=>'elva@ezhi.net', 'level'=>112],
];

// 路由分發
switch ($action) {
    case 'get_user':
        if (!$uid) jsonResponse(null, -401, 'uid 不能為空');
        if (!isset($users[$uid])) jsonResponse(null, -402, '用戶不存在');
        jsonResponse($users[$uid], 200, 'success');
        break;

    case 'get_user_list':
        jsonResponse(array_values($users), 200, 'success');
        break;

    default:
        jsonResponse(null, -404, '未知接口');
}
?>

客戶端呼叫範例

// GET
$resp = file_get_contents('https://localhost/api.php?a=get_user&uid=10001');

// POST (需開啟 curl)
$ch = curl_init('https://localhost/api.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query(['a' => 'get_user', 'uid' => 10001]),
    CURLOPT_RETURNTRANSFER => true,
]);
$resp = curl_exec($ch);
curl_close($ch);

$data = json_decode($resp, true);

實戰必備 6 大準則

1. 統一回應格式：{code, msg, data}，前端統一攔截處理。
2. 輸出純 JSON：header('Content-Type: application/json')，絕對不得有多餘輸出（含 BOM、空白、錯誤訊息），否則客戶端 JSON.parse 失敗直接 Crash。
3. 關閉錯誤顯示：生產環境 error_reporting(0); ini_set('display_errors', 0);，改寫入日誌。
4. 接口鑑權：簽名（Sign）、Token（JWT）、API Key、IP 白名單，防止惡意刷單/資料洩漏。
5. 輸入驗證與清洗：嚴格檢查型別、長度、格式，防止 SQL 注入、XSS。
6. 效能考量：API 建議不使用重型框架（如 Laravel 完整啟動），可用 Lumen、Slim、原生 PHP 或 Swoole/Hyperf 獲得極致回應速度。

版本管理與文檔

• URL 含版本：/api/v1/user
• 使用 Swagger (OpenAPI) / Apidoc 自動生成文檔。