PHP 串接新浪短網址 API 完整教學

前言

新浪短網址服務（t.cn）曾是國內開發者常用的縮網址工具。本文提供完整的 PHP 實作範例，示範如何透過 cURL 呼叫新浪 API 實現長網址轉短網址、短網址還原長網址的雙向功能。

核心程式碼實作

以下封裝為可直接複用的函數庫，包含請求發送、URL 格式化、JSON 解析與錯誤處理：

<?php
// 新浪 App Key（範例 Key，建議申請專屬 Key）
define('SINA_APPKEY', '31641035');

/**
 * 發送 cURL GET 請求
 */
function curlQuery($url) {
    $headers = ['Content-type: application/json'];
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_HEADER => 0,
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_TIMEOUT => 15,
    ]);
    $result = curl_exec($ch);
    curl_close($ch);
    return $result;
}

/**
 * 規範化 URL：補齊協議、小寫化、URL 編碼
 */
function filterUrl($url = '') {
    $url = trim(strtolower($url));
    $url = preg_replace('/^http:\/\//', '', $url);
    if ($url === '') return false;
    return urlencode('https://' . $url);
}

/**
 * 長網址轉短網址
 */
function sinaShortenUrl($long_url) {
    $url = 'https://api.t.sina.com.cn/short_url/shorten.json?source=' . SINA_APPKEY . '&url_long=' . $long_url;
    $result = curlQuery($url);
    $json = json_decode($result, true);
    if (isset($json['error']) || empty($json[0]['url_short'])) return false;
    return $json[0]['url_short'];
}

/**
 * 短網址還原長網址
 */
function sinaExpandUrl($short_url) {
    $url = 'https://api.t.sina.com.cn/short_url/expand.json?source=' . SINA_APPKEY . '&url_short=' . $short_url;
    $result = curlQuery($url);
    $json = json_decode($result, true);
    if (isset($json['error']) || empty($json[0]['url_long'])) return false;
    return $json[0]['url_long'];
}

// === 使用範例 ===
$originalUrl = 'https://www.example.com/very/long/url/with/parameters?foo=bar&baz=qux';
$encodedUrl = filterUrl($originalUrl);
$shortUrl = sinaShortenUrl($encodedUrl);
$restoredUrl = sinaExpandUrl($shortUrl);

echo "原始網址: $originalUrl\n";
echo "短網址: $shortUrl\n";
echo "還原網址: $restoredUrl\n";
?>

關鍵細節說明

1. App Key 來源：範例使用公開測試 Key，正式專案請至 新浪開放平台 申請專屬應用獲取獨立 Key，確保服務穩定性。
2. URL 預處理：filterUrl() 確保傳遞給 API 的網址格式正確（必須含 https:// 協議），避免 API 回傳錯誤。
3. 錯誤處理：函數回傳 false 表示失敗，呼叫端需自行判斷並處理（如記錄日誌、降級策略）。
4. 編碼問題：長網址經 urlencode() 編碼後再傳遞，防止特殊字元導致請求失敗。

進階應用建議

• 將上述函數封裝為 Composer 套件，方便專案間複用。
• 加入快取機制（Redis/Memcached），避免重複請求相同長網址。
• 監控 API 回應時間與成功率，異常時自動切換備用縮網址服務（如 Bitly、TinyURL）。

完整程式碼已整理為可直接執行的 PHP 檔案，開發者可根據專案需求調整錯誤處理與日誌記錄邏輯。