關於小程序中網絡相關API的說明

關於小程序中網絡相關API的說明

網絡API列表：

API	說明
wx.request	發起網絡請求
wx.uploadFile	上傳文件
wx.downloadFile	下載文件
wx.connectSocket	建立 WebSocket 鏈接
wx.onSocketOpen	監聽 WebSocket 打開
wx.onSocketError	監聽 WebSocket 錯誤
wx.sendSocketMessage	發送 WebSocket 消息
wx.onSocketMessage	接受 WebSocket 消息
wx.closeSocket	關閉 WebSocket 鏈接
wx.onSocketClose	監聽 WebSocket 關閉

在小程序中使用網絡相關的 API 時，須要注意下列問題，請開發者提早了解。

1. 服務器域名配置

每一個微信小程序須要事先設置一個通信域名，小程序能夠跟指定的域名與進行網絡通訊。包括普通 HTTPS 請求（request）、上傳文件（uploadFile）、下載文件（downloadFile) 和 WebSocket 通訊（connectSocket）

配置流程

服務器域名請在 小程序後臺-設置-開發設置-服務器域名 中進行配置，配置時須要注意：

• 域名只支持 https (request、uploadFile、downloadFile) 和 wss (connectSocket) 協議；
• 域名不能使用 IP 地址或 localhost，且不能帶端口號；
• 域名必須通過 ICP 備案；
• 出於安全考慮，api.weixin.qq.com 不能被配置爲服務器域名，相關API也不能在小程序內調用。開發者應將 appsecret 保存到後臺服務器中，經過服務器使用 appsecret 獲取 accesstoken，並調用相關 API。
• 對於每一個接口，分別能夠配置最多 20 個域名

HTTPS 證書

小程序必須使用 HTTPS 請求。小程序內會對服務器域名使用的 HTTPS 證書進行校驗，若是校驗失敗，則請求不能成功發起。因爲系統限制，不一樣平臺對於證書要求的嚴格程度不一樣。爲了保證小程序的兼容性，建議開發者按照最高標準進行證書配置，並使用相關工具檢查現有證書是否符合要求。

對證書要求以下：

• HTTPS 證書必須有效。證書必須被系統信任，部署SSL證書的網站域名必須與證書頒發的域名一致，證書必須在有效期內;
• iOS 不支持自簽名證書;
• iOS 下證書必須知足蘋果 App Transport Security (ATS) 的要求;
• TLS 必須支持 1.2 及以上版本。部分舊 Android 機型還未支持 TLS 1.2，請確保 HTTPS 服務器的 TLS 版本支持1.2及如下版本;
• 部分 CA 可能不被操做系統信任，請開發者在選擇證書時注意小程序和各系統的相關通告。
  • Chrome 56/57 內核對 WoSign、StartCom 證書限制周知

跳過域名校驗

在微信開發者工具中，能夠臨時開啓 開發環境不校驗請求域名、TLS版本及HTTPS證書 選項，跳過服務器域名的校驗。此時，在微信開發者工具中及手機開啓調試模式時，不會進行服務器域名的校驗。

在服務器域名配置成功後，建議開發者關閉此選項進行開發，並在各平臺下進行測試，以確認服務器域名配置正確。

若是手機上出現 「打開調試模式能夠發出請求，關閉調試模式沒法發出請求」 的現象，請確認是否跳過了域名校驗，並確認服務器域名和證書配置是否正確。

2. 關於請求

• 默認超時時間和最大超時時間都是 60s
• request、uploadFile、downloadFile 的最大併發限制是 10 個
• 網絡請求的 referer header 不可設置。其格式固定爲 https://servicewechat.com/{appid}/{version}/page-frame.html，其中 {appid} 爲小程序的 appid，{version} 爲小程序的版本號，版本號爲 0 表示爲開發版、體驗版以及審覈版本，版本號爲 devtools 表示爲開發者工具，其他爲正式版本。
• 小程序進入後臺運行後（非置頂聊天），若是 5s 內網絡請求沒有結束，會回調錯誤信息 fail interrupted；在回到前臺以前，網絡請求接口調用都會沒法調用。

3. 關於服務器返回

返回值編碼

• 建議服務器返回值使用 UTF-8 編碼。對於非 UTF-8 編碼，小程序會嘗試進行轉換，可是會有轉換失敗的可能。
• 小程序會自動對 BOM 頭進行過濾。

回調

• 只要成功接收到服務器返回，不管statusCode是多少，都會進入success回調。請開發者根據業務邏輯對返回值進行判斷。