PHP 獲取新浪微博數據 API 實戰：OAuth 認證、CURL 請求、JSON 解析

調用新浪微博開放平台 API 獲取用戶時間線數據，涉及 OAuth 2.0 授權、HTTPS CURL 請求、JSON 解析 完整流程。本文提供可直接運行的封裝類，並解析關鍵細節。

前置準備

1. 在 微博開放平台 創建應用，獲取 App Key (client_id) 和 App Secret (client_secret)。
2. 配置授權回調頁域名，完成 OAuth 2.0 授權碼流程獲取 access_token。
3. 確保 PHP 環境開啟 curl 和 openssl 擴展。

完整封裝類

accessToken = $accessToken;
        $this->clientId = $clientId;
        $this->clientSecret = $clientSecret;
    }

    /** 通用 GET 請求 */
    private function get($endpoint, $params = []) {
        $params['access_token'] = $this->accessToken;
        $url = $this->baseUrl . $endpoint . '?' . http_build_query($params);
        
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_SSL_VERIFYPEER => true,  // 生產環境必須驗證
            CURLOPT_SSL_VERIFYHOST => 2,
            CURLOPT_TIMEOUT => 15,
            CURLOPT_USERAGENT => 'PHP-WeiboApi/1.0',
        ]);
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 200) {
            throw new RuntimeException("HTTP $httpCode: $response");
        }
        $data = json_decode($response, true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new RuntimeException('JSON 解析失敗: ' . json_last_error_msg());
        }
        // 微博 API 業務錯誤碼檢查
        if (isset($data['error_code']) && $data['error_code'] > 0) {
            throw new RuntimeException("Weibo API Error {$data['error_code']}: {$data['error']}");
        }
        return $data;
    }

    /** 獲取當前登入用戶及關注人最新微博 (home_timeline) */
    public function getHomeTimeline($count = 20, $page = 1) {
        return $this->get('statuses/home_timeline.json', [
            'count' => min($count, 200), // 最大 200
            'page'  => $page,
        ]);
    }

    /** 獲取指定用戶微博 (user_timeline) */
    public function getUserTimeline($uid, $count = 20, $page = 1) {
        return $this->get('statuses/user_timeline.json', [
            'uid'   => $uid,
            'count' => min($count, 200),
            'page'  => $page,
        ]);
    }

    /** 發布微博 (需 POST 權限) */
    public function postStatus($status, $lat = 0, $long = 0) {
        $url = $this->baseUrl . 'statuses/update.json';
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => http_build_query([
                'access_token' => $this->accessToken,
                'status' => $status,
                'lat' => $lat,
                'long' => $long,
            ]),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_SSL_VERIFYPEER => true,
            CURLOPT_TIMEOUT => 15,
        ]);
        $response = curl_exec($ch);
        // ... 錯誤處理同 get()
        return json_decode($response, true);
    }
}

// 使用示例
$accessToken = 'YOUR_ACCESS_TOKEN_FROM_OAUTH'; // 存儲在 Session/Redis/DB 中
$weibo = new WeiboApi($accessToken);

try {
    $timeline = $weibo->getHomeTimeline(15, 1);
    echo '
'; print_r($timeline); echo '
';
} catch (Exception $e) {
    echo "錯誤: " . $e->getMessage();
}

關鍵細節解析

1. OAuth 2.0 授權碼流程 (獲取 access_token)

// 1. 導向授權頁
$authUrl = 'https://api.weibo.com/oauth2/authorize?' . http_build_query([
    'client_id' => $appKey,
    'redirect_uri' => $callbackUrl,
    'response_type' => 'code',
    'scope' => 'statuses_to_me_read', // 申請權限
]);
header("Location: $authUrl");

// 2. 回調頁換取 token
$code = $_GET['code'];
$tokenUrl = 'https://api.weibo.com/oauth2/access_token';
$ch = curl_init($tokenUrl);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'client_id' => $appKey,
        'client_secret' => $appSecret,
        'grant_type' => 'authorization_code',
        'code' => $code,
        'redirect_uri' => $callbackUrl,
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$tokenRes = json_decode(curl_exec($ch), true);
$accessToken = $tokenRes['access_token'];
$expiresIn = $tokenRes['expires_in']; // 存儲並設置過期時間

2. CURL 關鍵設置

• CURLOPT_SSL_VERIFYPEER => true：**生產環境必須開啟**，防中間人攻擊。若證書問題，配置 CURLOPT_CAINFO 指定 CA 憑證包。
• CURLOPT_TIMEOUT：設置超時 (建議 10-30s)，防止請求阻塞。
• CURLOPT_USERAGENT：標識客戶端，便於平台監控統計。

3. JSON 解析：json_decode($json, true)

• 第 2 參數 true 強制返回**關聯陣列**，而非 stdClass 對象。
• 陣列訪問 $data['key'] 比對象 $data->key 更統一、可預測，尤其鍵名為數字時。
• 配合 json_last_error() 檢測解析錯誤。

4. 錯誤處理體系

• HTTP 狀態碼非 200：網絡/平台層面錯誤。
• JSON 解析失敗：響應非標準 JSON (如 HTML 錯誤頁)。
• 業務錯誤碼 error_code：微博 API 具體錯誤 (如 21327 權限不足、10023 參數錯誤)。
• 統一拋出異常，上層捕獲記錄日誌、降級處理、用戶提示。

進階優化建議

1. Access Token 管理：Redis 存儲 weibo_token:{uid}，過期時間比 expires_in 短 5 分鐘，自動刷新機制 (refresh_token)。
2. 限流與重試：微博 API 有頻率限制，實現令牌桶限流 + 指數退避重試 (針對 5xx/網絡錯誤)。
3. 異步處理：發布微博等寫操作放入消息隊列，異步執行，提升響應速度。
4. 數據緩存：時間線數據緩存 1-5 分鐘，減少 API 調用，應對高併發讀取。
5. SDK 選擇：生產建議使用成熟 SDK (如 overtrue/weibo Composer 包)，封裝完善、持續維護。

總結

微博 API 調用核心在於：**OAuth 權限管理、HTTPS CURL 規範配置、健壯的 JSON 解析與錯誤處理、Token 生命週期維護**。封裝為可復用類，接入業務邏輯即可快速實現社交功能集成。