Android JSON 解析錯誤：JSONObject 無法轉換為 JSONArray

錯誤現象

回應內容為單一 JSON 物件 {"id":"602414132",...}，程式碼嘗試 new JSONArray(response) 拋出 JSONException: Value ... of type JSONObject cannot be converted to JSONArray。

根本原因

JSON 結構不匹配：伺服器回傳單一物件 {...}，而非陣列 [{...}]。JSONArray 建構子只接受以 [ 開頭的字串。

正確解析方式

情況一：回傳單一物件（最常見）

// 直接建立 JSONObject
JSONObject json = new JSONObject(responseString);
String id = json.getString("id");
String name = json.getString("name");
// ... 直接取值，無需迴圈

情況二：回傳包含陣列的物件

// {"users": [{...}, {...}]}
JSONObject json = new JSONObject(responseString);
JSONArray array = json.getJSONArray("users");  // 取得陣列
for (int i = 0; i < array.length(); i++) {
    JSONObject obj = array.getJSONObject(i);
    // 處理每個物件
}

情況三：不確定結構，防禦性解析

Object parsed = new JSONTokener(responseString).nextValue();
if (parsed instanceof JSONObject) {
    JSONObject obj = (JSONObject) parsed;
    // 單一物件處理
} else if (parsed instanceof JSONArray) {
    JSONArray array = (JSONArray) parsed;
    // 陣列處理
}

修正原程式碼

// 原錯誤
// JSONArray json = new JSONArray(DownloadText(url));  // 崩潰

// 修正
JSONObject json = new JSONObject(DownloadText(url));
// 如果確定有陣列欄位
// JSONArray array = json.getJSONArray("your_array_key");

FBUser user = new FBUser();
user.id = json.getString("id");
user.name = json.getString("name");
// ... 其他欄位

最佳實踐

1. 先印出/Log 完整回應字串，確認結構再寫解析碼。
2. 使用 Gson/Moshi 直接映射到資料類別：

// Gson
FBUser user = new Gson().fromJson(responseString, FBUser.class);
// 自動處理巢狀、型別轉換、null 安全

優勢：零樣板碼、編譯期型別檢查、重構安全、效能優於手寫解析。

避坑指南

• {} = JSONObject，[] = JSONArray，首字元決定結構。
• Facebook Graph API 等 REST API 多回傳單一物件，非陣列。
• 手寫解析易出錯、難維護，生產環境強烈建議用 Gson/Moshi/Kotlinx.serialization。

JSON 解析的鐵律：先看結構，再選工具，拒絕盲目試錯。