小程序中网络请求相关的api总结

  1. 云栖社区>
  2. 博客>
  3. 正文

小程序中网络请求相关的api总结

webmirror 发布时间:2018-08-30 11:59:21 浏览1668 评论0

摘要: 小程序中网络相关的API 网络API列表: API 说明 wx.request 发起网络请求 wx.uploadFile 上传文件 wx.downloadFile 下载文件 wx.

小程序中网络相关的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 时,需要注意下列问题,请开发者提前了解

服务器域名配置

每个微信小程序需要事先设置一个通讯域名,小程序可以跟指定的域名进行网络通信。包括普通 HTTPS 请求(request)、上传文件(uploadFile)、下载文件(downloadFile) 和 WebSocket 通信(connectSocket)

配置流程

服务器域名请在"小程序后台-设置-开发设置-服务器域名" 中进行配置,配置时需要注意:

1.域名只支持 https (request、uploadFile、downloadFile) 和 wss (connectSocket) 协议;

2.域名不能使用 IP 地址或 localhost

3.域名必须经过 ICP 备案;

4.出于安全考虑,api.weixin.qq.com 不能被配置为服务器域名,相关API也不能在小程序内调用。开发者应将 appsecret 保存到后台服务器中,通过服务器使用 appsecret 获取 accesstoken,并调用相关 API。

5.对于每个接口,分别可以配置最多 20 个域名

HTTPS 证书

小程序必须使用HTTPS请求。小程序内会对服务器域名使用的HTTPS证书进行校验,如果校验失败,则请求不能成功发起。由于系统限制,不同平台对于证书要求的严格程度不同。为了保证小程序的兼容性,建议开发者按照最高标准进行证书配置,并使用相关工具检查现有证书是否符合要求

对证书要求如下:

1.HTTPS 证书必须有效。证书必须被系统信任,部署SSL证书的网站域名必须与证书颁发的域名一致,证书必须在有效期内;

2.iOS 不支持自签名证书;

3.iOS 下证书必须满足苹果 App Transport Security (ATS) 的要求;

4.TLS 必须支持 1.2 及以上版本。部分旧 Android 机型还未支持 TLS 1.2,请确保 HTTPS 服务器的 TLS 版本支持1.2及以下版本;

5.部分 CA 可能不被操作系统信任,请开发者在选择证书时注意小程序和各系统的相关通告。

6.Chrome 56/57 内核对 WoSign、StartCom 证书限制周知:Android X5内核计划将于8月份开始升级到Chrome 57内核(目前 Chrome 53),升级到 Chrome 57 内核后,会对 WoSign CA Free SSL/StartCom 证书进行部分限制。对于小程序来说,如果储存图片资源的服务器使用了上述证书,将会影响图片的正常加载。预计 Chrome 以后版本会再加大对 WoSign CA Free SSL/StartCom 证书限制,我们建议开发者提前更换其它可信证书。

Chrome 56/57 版本对 WoSign CA Free SSL/StartCom 证书限制措施如下:

1).Chrome 56 开始停止信任 2016 年 10 月 21 日后签发的 WoSign CA Free SSL/StartCom 证书;

2).Chrome 57 进一步扩大限制范围,Alexa 排名一百万外的网站都不能使用 WoSign CA Free SSL/StartCom 证书,无论证书何时签发。

附:如何检测网站是否使用了 WoSign/StartCom

1).使用最新版本的 Chrome 打开图片链接,右键 -> 检查,切换到「Security」页卡,点击「View certificate」;

2).检查证书的签发机构是否在限制范围内。

跳过域名校验

在微信开发者工具中,可以临时开启 开发环境不校验请求域名、TLS版本及HTTPS证书 选项,跳过服务器域名的校验。此时,在微信开发者工具中及手机开启调试模式时,不会进行服务器域名的校验

在服务器域名配置成功后,建议开发者关闭此选项进行开发,并在各平台下进行测试,以确认服务器域名配置正确。

如果手机上出现 “打开调试模式可以发出请求,关闭调试模式无法发出请求” 的现象,请确认是否跳过了域名校验,并确认服务器域名和证书配置是否正确

关于请求

1.默认超时时间和最大超时时间都是 60s

2.request、uploadFile、downloadFile 的最大并发限制是 10 个

3.网络请求的 referer header 不可设置。其格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html,其中 {appid} 为小程序的 appid,{version} 为小程序的版本号,版本号为 0 表示为开发版、体验版以及审核版本,版本号为 devtools 表示为开发者工具,其余为正式版本。

4.小程序进入后台运行后(非置顶聊天),如果 5s 内网络请求没有结束,会回调错误信息 fail interrupted;在回到前台之前,网络请求接口调用都会无法调用

关于服务器返回

返回值编码

1.建议服务器返回值使用 UTF-8 编码。对于非 UTF-8 编码,小程序会尝试进行转换,但是会有转换失败的可能。

2.小程序会自动对 BOM 头进行过滤。

回调

只要成功接收到服务器返回,无论statusCode是多少,都会进入success回调。请开发者根据业务逻辑对返回值进行判断

wx.request(OBJECT)

发起网络请求

OBJECT参数说明:

参数名 类型 必填 默认值 说明 最低版本
url String 开发者服务器接口地址
data Object/String/ArrayBuffer 请求的参数
header Object 设置请求的 header,header 中不能设置 Referer
method String GET (需大写)有效值:OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT
dataType String json 如果设为json,会尝试对返回的数据做一次 JSON.parse
responseType String text 设置响应的数据类型。合法值:text、arraybuffer 1.7.0
success Function 收到开发者服务成功返回的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数 类型 说明 最低版本
data Object/String/ArrayBuffer 开发者服务器返回的数据
statusCode Number 开发者服务器返回的 HTTP 状态码
header Object 开发者服务器返回的 HTTP Response Header 1.2.0

data 数据说明:

最终发送给服务器的数据是 String 类型,如果传入的 data 不是 String 类型,会被转换成 String 。转换规则如下:

1.对于 GET 方法的数据,会将数据转换成 query string(encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...)

2.对于 POST 方法且 header['content-type'] 为 application/json 的数据,会对数据进行 JSON 序列化

3.对于 POST 方法且 header['content-type'] 为 application/x-www-form-urlencoded 的数据,会将数据转换成 query string (encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...)

wx.request({
  url: 'test.php', //仅为示例,并非真实的接口地址
  data: {
     x: '' ,
     y: ''
  },
  header: {
    'content-type': 'application/json' // 默认值
  },
  success: function(res) {
    console.log(res.data)
  }
})

返回值:

返回一个 requestTask 对象,通过 requestTask,可中断请求任务; 基础库 1.4.0 开始支持,低版本需做兼容处理

requestTask 对象的方法列表:

方法 参数 说明 最低版本
abort 中断请求任务 1.4.0
const requestTask = wx.request({
  url: 'test.php', //仅为示例,并非真实的接口地址
  data: {
     x: '' ,
     y: ''
  },
  header: {
    'content-type': 'application/json'
  },
  success: function(res) {
    console.log(res.data)
  }
})
requestTask.abort() // 取消请求任务

Bug & Tip

1.tip: content-type 默认为 'application/json';

2.bug: 开发者工具 0.10.102800 版本,header 的 content-type 设置异常;

上传 下载

wx.uploadFile(OBJECT)

将本地资源上传到开发者服务器,客户端发起一个 HTTPS POST 请求,其中 content-type 为 multipart/form-data 。使用前请先阅读说明。

如页面通过 wx.chooseImage 等接口获取到一个本地资源的临时文件路径后,可通过此接口将本地资源上传到指定服务器

OBJECT参数说明:

参数名 类型 必填 说明
url String 开发者服务器 url
filePath String 要上传文件资源的路径
name String 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容
header Object HTTP 请求 Header, header 中不能设置 Referer
formData Object HTTP 请求中其他额外的 form data
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

success返回参数说明:

参数名 类型 说明
data String 开发者服务器返回的数据
statusCode Number 开发者服务器返回的 HTTP 状态码
wx.chooseImage({
  success: function(res) {
    var tempFilePaths = res.tempFilePaths
    wx.uploadFile({
      url: 'https://example.weixin.qq.com/upload', //仅为示例,非真实的接口地址
      filePath: tempFilePaths[0],
      name: 'file',
      formData:{
        'user': 'test'
      },
      success: function(res){
        var data = res.data
        //do something
      }
    })
  }
})

返回值:

返回一个 uploadTask 对象,通过 uploadTask,可监听上传进度变化事件,以及取消上传任务; 基础库 1.4.0 开始支持,低版本需做兼容处理

uploadTask

uploadTask 对象的方法列表:

方法 参数 说明 最低版本
onProgressUpdate callback 监听上传进度变化 1.4.0
abort 中断上传任务 1.4.0

onProgressUpdate 返回参数说明:

参数名 类型 说明
progress Number 上传进度百分比
totalBytesSent Number 已经上传的数据长度,单位 Bytes
totalBytesExpectedToSend Number 预期需要上传的数据总长度,单位 Bytes
const uploadTask = wx.uploadFile({
    url: 'http://example.weixin.qq.com/upload', //仅为示例,非真实的接口地址
    filePath: tempFilePaths[0],
    name: 'file',
    formData:{
        'user': 'test'
    },
    success: function(res){
        var data = res.data
        //do something
    }
})
uploadTask.onProgressUpdate((res) => {
    console.log('上传进度', res.progress)
    console.log('已经上传的数据长度', res.totalBytesSent)
    console.log('预期需要上传的数据总长度', res.totalBytesExpectedToSend)
})
uploadTask.abort() // 取消上传任务

wx.downloadFile(OBJECT)

下载文件资源到本地,客户端直接发起一个 HTTP GET 请求,返回文件的本地临时路径

OBJECT参数说明:

参数名 类型 必填 说明
url String 下载资源的 url
header Object HTTP 请求 Header, header 中不能设置 Referer
success Function 下载成功后以 tempFilePath 的形式传给页面,res = {tempFilePath: '文件的临时路径'}
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

注:文件的临时路径,在小程序本次启动期间可以正常使用,如需持久保存,需在主动调用 wx.saveFile,才能在小程序下次启动时访问得到。 注:请在 header 中指定合理的 Content-Type 字段,以保证客户端正确处理文件类型

success返回参数说明:

参数名 类型 说明
tempFilePath String 临时文件路径,下载后的文件会存储到一个临时文件
statusCode Number 开发者服务器返回的 HTTP 状态码
wx.downloadFile({
  url: 'https://example.com/audio/123', //仅为示例,并非真实的资源
  success: function(res) {
    // 只要服务器有响应数据,就会把响应内容写入文件并进入 success 回调,业务需要自行判断是否下载到了想要的内容
    if (res.statusCode === 200) {
        wx.playVoice({
          filePath: res.tempFilePath
        })
    }
  }
})

返回值:返回一个 downloadTask 对象,通过 downloadTask,可监听下载进度变化事件,以及取消下载任务

基础库 1.4.0 开始支持,低版本需做兼容处理

downloadTask

downloadTask 对象的方法列表:

方法 参数 说明 最低版本
onProgressUpdate callback 监听下载进度变化 1.4.0
abort 中断下载任务 1.4.0

onProgressUpdate 返回参数说明:

参数名 类型 说明
progress Number 下载进度百分比
totalBytesWritten Number 已经下载的数据长度,单位 Bytes
totalBytesExpectedToWrite Number 预期需要下载的数据总长度,单位 Bytes
const downloadTask = wx.downloadFile({
    url: 'http://example.com/audio/123', //仅为示例,并非真实的资源
    success: function(res) {
        wx.playVoice({
            filePath: res.tempFilePath
        })
    }
})
downloadTask.onProgressUpdate((res) => {
    console.log('下载进度', res.progress)
    console.log('已经下载的数据长度', res.totalBytesWritten)
    console.log('预期需要下载的数据总长度', res.totalBytesExpectedToWrite)
})
downloadTask.abort() // 取消下载任务

tip: 6.5.3 以及之前版本的 iOS 微信客户端 header 设置无效

WebSocket

wx.connectSocket(OBJECT)

创建一个 WebSocket 连接。基础库 1.7.0 之前,一个微信小程序同时只能有一个 WebSocket 连接,如果当前已存在一个 WebSocket 连接,会自动关闭该连接,并重新创建一个 WebSocket 连接。基础库版本 1.7.0 及以后,支持存在多个 WebSokcet 连接,每次成功调用 wx.connectSocket 会返回一个新的 SocketTask

OBJECT参数说明:

参数名 类型 必填 说明 最低版本
url String 开发者服务器接口地址,必须是 wss 协议,且域名必须是后台配置的合法域名
header Object HTTP 请求 Header, header 中不能设置 Referer
protocols StringArray 子协议数组 1.4.0
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)
wx.connectSocket({
  url: 'wss://example.qq.com',
  data:{
    x: '',
    y: ''
  },
  header:{ 
    'content-type': 'application/json'
  },
  protocols: ['protocol1'],
  method:"GET"
})

wx.onSocketOpen(CALLBACK)

监听WebSocket连接打开事件

callback 回调函数

res

属性 类型 说明 最低版本
header object 连接成功的 HTTP 响应 Header 2.0.0
wx.connectSocket({
  url: 'test.php'
})
wx.onSocketOpen(function(res) {
  console.log('WebSocket连接已打开!')
})

wx.onSocketError(CALLBACK)

监听WebSocket错误

wx.connectSocket({
  url: 'test.php'
})
wx.onSocketOpen(function(res){
  console.log('WebSocket连接已打开!')
})
wx.onSocketError(function(res){
  console.log('WebSocket连接打开失败,请检查!')
})

wx.sendSocketMessage(OBJECT)

通过 WebSocket 连接发送数据,需要先 wx.connectSocket,并在 wx.onSocketOpen 回调之后才能发送

OBJECT参数说明:

参数名 类型 必填 说明
data String/ArrayBuffer 需要发送的内容
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)
var socketOpen = false
var socketMsgQueue = []
wx.connectSocket({
  url: 'test.php'
})
wx.onSocketOpen(function(res) {
  socketOpen = true
  for (var i = 0; i < socketMsgQueue.length; i++){
     sendSocketMessage(socketMsgQueue[i])
  }
  socketMsgQueue = []
})
function sendSocketMessage(msg) {
  if (socketOpen) {
    wx.sendSocketMessage({
      data:msg
    })
  } else {
     socketMsgQueue.push(msg)
  }
}

wx.onSocketMessage(CALLBACK)

监听WebSocket接受到服务器的消息事件

callback 回调参数

参数 类型 说明
data String/ArrayBuffer 服务器返回的消息
wx.connectSocket({
  url: 'test.php'
})
wx.onSocketMessage(function(res) {
  console.log('收到服务器内容:' + res.data)
})

wx.closeSocket(OBJECT)

关闭 WebSocket 连接

OBJECT参数说明:

参数名 类型 必填 说明 最低版本
code Number 一个数字值表示关闭连接的状态号,表示连接被关闭的原因。如果这个参数没有被指定,默认的取值是1000 (表示正常连接关闭) 1.4.0
reason String 一个可读的字符串,表示连接被关闭的原因。这个字符串必须是不长于123字节的UTF-8 文本(不是字符) 1.4.0
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

wx.onSocketClose(CALLBACK)

监听WebSocket关闭

wx.connectSocket({
  url: 'test.php'
})
//注意这里有时序问题,如果 wx.connectSocket 还没回调 wx.onSocketOpen,而先调用 wx.closeSocket,那么就做不到关闭 WebSocket 的目的。必须在 WebSocket 打开期间调用 wx.closeSocket 才能关闭。
wx.onSocketOpen(function() {
  wx.closeSocket()
})
wx.onSocketClose(function(res) {
  console.log('WebSocket 已关闭!')
})

返回值:

返回一个 SocketTask;基础库 1.7.0 开始支持,低版本需做兼容处理

tip: 基础库 1.7.0 开始,支持同时存在 2 条 WebSocket 连接

【云栖快讯】云栖专辑 | 阿里开发者们的第20个感悟:好的工程师为人写代码,而不仅是为编译器  详情请点击

网友评论