QQ小程序 網(wǎng)絡(luò)

使用說(shuō)明

在小程序/小游戲中使用網(wǎng)絡(luò)相關(guān)的 API 時(shí)，需要注意下列問(wèn)題，請(qǐng)開(kāi)發(fā)者提前了解。

1. 服務(wù)器域名配置

每個(gè)QQ小程序需要事先設(shè)置一個(gè)通訊域名，小程序只可以跟指定的域名與進(jìn)行網(wǎng)絡(luò)通信。包括普通 HTTPS 請(qǐng)求（qq.request）、上傳文件（qq.uploadFile）、下載文件（qq.downloadFile) 和 WebSocket 通信（qq.connectSocket）

配置流程

• 服務(wù)器域名請(qǐng)?jiān)?「小程序后臺(tái)-設(shè)置-開(kāi)發(fā)設(shè)置-服務(wù)器域名」 中進(jìn)行配置，配置時(shí)需要注意：
• 域名只支持 https (qq.request、qq.uploadFile、qq.downloadFile) 和 wss (qq.connectSocket) 協(xié)議；
• 域名不能使用 IP 地址或 localhost；
• 可以配置端口，如 https://QQminiApp.com:8080，但是配置后只能向 https://QQminiApp.com:8080 發(fā)起請(qǐng)求。如果向 https://QQminiApp.com、https://QQminiApp.com:9091 等 URL 請(qǐng)求則會(huì)失敗。
• 如果不配置端口。如 https://QQminiApp.com，那么請(qǐng)求的 URL 中也不能包含端口，甚至是默認(rèn)的 443 端口也不可以。如果向 https://QQminiApp.com:443 請(qǐng)求則會(huì)失敗。
• 域名必須經(jīng)過(guò) ICP 備案；
• 出于安全考慮，api.q.qq.com 不能被配置為服務(wù)器域名，相關(guān)API也不能在小程序內(nèi)調(diào)用。 開(kāi)發(fā)者應(yīng)將 AppSecret 保存到后臺(tái)服務(wù)器中，通過(guò)服務(wù)器使用 getAccessToken 接口獲取 access_token，并調(diào)用相關(guān) API；
• 對(duì)于每個(gè)接口，分別可以配置最多 20 個(gè)域名。

2. 網(wǎng)絡(luò)請(qǐng)求

超時(shí)時(shí)間

• 默認(rèn)超時(shí)時(shí)間和最大超時(shí)時(shí)間都是 60s；
• 超時(shí)時(shí)間可以在 app.json 中配置。

使用限制

• 網(wǎng)絡(luò)請(qǐng)求的 referer header 不可設(shè)置。其格式固定為 https://appservice.qq.com/{appid}/{version}/page-frame.html，其中 {appid} 為小程序的 appid，{version} 為小程序的版本號(hào)，版本號(hào)為 0 表示為開(kāi)發(fā)版、體驗(yàn)版以及審核版本，版本號(hào)為 devtools 表示為開(kāi)發(fā)者工具，其余為正式版本；
• qq.request、qq.uploadFile、qq.downloadFile 的最大并發(fā)限制是 10 個(gè)；
• 小程序進(jìn)入后臺(tái)運(yùn)行后（非置頂聊天），如果 5s 內(nèi)網(wǎng)絡(luò)請(qǐng)求沒(méi)有結(jié)束，會(huì)回調(diào)錯(cuò)誤信息 fail interrupted；在回到前臺(tái)之前，網(wǎng)絡(luò)請(qǐng)求接口調(diào)用都會(huì)無(wú)法調(diào)用。

返回值編碼

• 建議服務(wù)器返回值使用 UTF-8 編碼。對(duì)于非 UTF-8 編碼，小程序會(huì)嘗試進(jìn)行轉(zhuǎn)換，但是會(huì)有轉(zhuǎn)換失敗的可能。
• 小程序會(huì)自動(dòng)對(duì) BOM 頭進(jìn)行過(guò)濾（只過(guò)濾一個(gè)BOM頭）。

回調(diào)函數(shù)

• 只要成功接收到服務(wù)器返回，無(wú)論 statusCode 是多少，都會(huì)進(jìn)入 success 回調(diào)。請(qǐng)開(kāi)發(fā)者根據(jù)業(yè)務(wù)邏輯對(duì)返回值進(jìn)行判斷。

• HTTPS 證書(shū)必須有效；
  • 證書(shū)必須被系統(tǒng)信任，即根證書(shū)被已系統(tǒng)內(nèi)置
  • 部署 SSL 證書(shū)的網(wǎng)站域名必須與證書(shū)頒發(fā)的域名一致
  • 證書(shū)必須在有效期內(nèi)
  • 證書(shū)的信任鏈必需完整（需要服務(wù)器配置）
• iOS 不支持自簽名證書(shū);
• iOS 下證書(shū)必須滿(mǎn)足蘋(píng)果 App Transport Security (ATS) 的要求;
• TLS 必須支持 1.2 及以上版本。部分舊 Android 機(jī)型還未支持 TLS 1.2，請(qǐng)確保 HTTPS 服務(wù)器的 TLS 版本支持 1.2 及以下版本;
• 部分 CA 可能不被操作系統(tǒng)信任，請(qǐng)開(kāi)發(fā)者在選擇證書(shū)時(shí)注意小程序和各系統(tǒng)的相關(guān)通告

證書(shū)有效性可以使用 openssl s_client -connect example.com:443 命令驗(yàn)證，也可以使用其他在線(xiàn)工具

除了網(wǎng)絡(luò)請(qǐng)求 API 外，小程序中其他 HTTPS 請(qǐng)求如果出現(xiàn)異常，也請(qǐng)按上述流程進(jìn)行檢查。如 https 的圖片無(wú)法加載、音視頻無(wú)法播放等。

跳過(guò)域名校驗(yàn)

在QQ開(kāi)發(fā)者工具中，可以臨時(shí)開(kāi)啟 開(kāi)發(fā)環(huán)境不校驗(yàn)請(qǐng)求域名、TLS版本及HTTPS證書(shū) 選項(xiàng)，跳過(guò)服務(wù)器域名的校驗(yàn)。此時(shí)，在QQ開(kāi)發(fā)者工具中及手機(jī)開(kāi)啟調(diào)試模式時(shí)，不會(huì)進(jìn)行服務(wù)器域名的校驗(yàn)。

在服務(wù)器域名配置成功后，建議開(kāi)發(fā)者關(guān)閉此選項(xiàng)進(jìn)行開(kāi)發(fā)，并在各平臺(tái)下進(jìn)行測(cè)試，以確認(rèn)服務(wù)器域名配置正確。

如果手機(jī)上出現(xiàn) “打開(kāi)調(diào)試模式可以發(fā)出請(qǐng)求，關(guān)閉調(diào)試模式無(wú)法發(fā)出請(qǐng)求” 的現(xiàn)象，請(qǐng)確認(rèn)是否跳過(guò)了域名校驗(yàn)，并確認(rèn)服務(wù)器域名和證書(shū)配置是否正確。