Android HTTP 協定與網路權限

幾乎所有的現代 App 都需要連上網路。在開始串接 API 之前，我們需要先了解 Android 上的網路基礎設定。

網路權限 (Internet Permission)

Android 系統預設是禁止 App 使用網路的。你必須在 AndroidManifest.xml 中明確宣告權限。

打開 app/src/main/AndroidManifest.xml，在 <application> 標籤上方加入：

<manifest ...>
    <!-- 必備：允許 App 存取網路 -->
    <uses-permission android:name="android.permission.INTERNET" />
    
    <!-- 選用：允許 App 檢查網路狀態 (Wi-Fi/4G) -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <application ...>
        ...
    </application>
</manifest>

如果你忘了加這行，App 在發送請求時會直接拋出 SecurityException 並崩潰。

明文傳輸限制 (Cleartext Traffic)

從 Android 9 (API 28) 開始，Google 為了安全性，預設禁止 App 連線到非加密的 HTTP 網站 (http://)，強制要求使用 HTTPS (https://)。

如果你嘗試連線到 http://example.com，會收到 Cleartext HTTP traffic not permitted 錯誤。

解決方案

方法 A：使用 HTTPS (推薦)

將所有的 API 網址改為 https://。這是最安全也最正確的做法。

方法 B：設定 Network Security Config (例外開放)

如果你的測試伺服器只有 HTTP，可以設定例外。

1. 在 res/xml/ 下建立 network_security_config.xml：

   <?xml version="1.0" encoding="utf-8"?>
   <network-security-config>
       <domain-config cleartextTrafficPermitted="true">
           <domain includeSubdomains="true">api.example.com</domain>
           <domain includeSubdomains="true">192.168.1.100</domain> <!-- 內網 IP -->
       </domain-config>
   </network-security-config>
   

2. 在 AndroidManifest.xml 中參照此設定：

   <application
       android:networkSecurityConfig="@xml/network_security_config"
       ...>
   

方法 C：全面開放 (不推薦)

僅限測試階段使用，切勿用於正式版。

<application
    android:usesCleartextTraffic="true"
    ...>

主執行緒限制 (Main Thread Policy)

Android 絕對禁止在主執行緒 (UI Thread) 執行網路操作。這會導致 App 畫面凍結，甚至觸發 ANR (Application Not Responding)。如果你硬要在主執行緒連網，會收到 NetworkOnMainThreadException。

解決方案： 總是使用 Coroutines (Dispatchers.IO) 或第三方函式庫 (Retrofit, OkHttp) 來處理網路請求。這些庫內部會自動切換到背景執行緒。

小結

• 記得加 INTERNET 權限。
• API 盡量使用 HTTPS。
• 網路操作必須在背景執行緒進行。