微信小程序云开发云函数

由 Carrie 创建， 最后一次修改 2018-11-06

一个云函数的写法与一个在本地定义的 JavaScript 方法无异，代码运行在云端 Node.js 中。当云函数被小程序端调用时，定义的代码会被放在 Node.js 运行环境中执行。我们可以如在 Node.js 环境中使用 JavaScript 一样在云函数中进行网络请求等操作，而且我们还可以通过云函数后端 SDK 搭配使用多种服务，比如使用云函数 SDK 中提供的数据库和存储 API 进行数据库和存储的操作，这部分可参考数据库和 存储后端 API 文档。

云开发的云函数的独特优势在于与微信登录鉴权的无缝整合。当小程序端调用云函数时，云函数的传入参数中会被注入小程序端用户的 openid，开发者无需校验 openid 的正确性因为微信已经完成了这部分鉴权，开发者可以直接使用该 openid。

接下来，我们将逐步学习以下内容：

• 我的第一个云函数
• 获取小程序用户信息
• 异步返回结果
• 使用 wx-server-sdk
• 在开发者工具中管理云函数
• 测试、日志与监控
• 注意事项

---

我的第一个云函数

我们以定义一个将两个数字相加的函数作为我们第一个云函数的示例。

在项目根目录找到 project.config.json 文件，新增 cloudfunctionRoot 字段，指定本地已存在的目录作为云函数的本地根目录

示例：

{
   "cloudfunctionRoot": "./functions/"
}

project.config.json 的其他配置，详见项目配置文件。

完成指定之后，云函数的根目录的图标会变成 “云目录图标”，云函数根目录下的第一级目录（云函数目录）是与云函数名字相同的，如果对应的线上环境存在该云函数，则我们会用一个特殊的 “云图标” 标明

接着，我们在云函数根目录上右键，在右键菜单中，可以选择创建一个新的 Node.js 云函数，我们将该云函数命名为 add。开发者工具在本地创建出云函数目录和入口 index.js 文件，同时在线上环境中创建出对应的云函数。创建成功后，工具会提示是否立即本地安装依赖，确定后工具会自动安装 wx-server-sdk。我们可以看到类似如下的一个云函数模板：

const cloud = require('wx-server-sdk')
// 云函数入口函数
exports.main = async (event, context) => {

}

云函数的传入参数有两个，一个是 event 对象，一个是 context 对象。event 指的是触发云函数的事件，当小程序端调用云函数时，event 就是小程序端调用云函数时传入的参数，外加后端自动注入的小程序用户的 openid 和小程序的 appid。context 对象包含了此处调用的调用信息和运行状态，可以用它来了解服务运行的情况。在模板中也默认 require 了 wx-server-sdk，这是一个帮助我们在云函数中操作数据库、存储以及调用其他云函数的微信提供的库，关于 wx-server-sdk 的使用我们在另一个章节讲述。

我们填充一下模板：

exports.main = async (event, context) => {
  return {
    sum: event.a + event.b
  }
}

本段代码的意思是将传入的 a 和 b 相加并作为 sum 字段返回给调用端。

在小程序中调用这个云函数前，我们还需要先将该云函数部署到云端。在云函数目录上右键，在右键菜单中，我们可以将云函数整体打包上传并部署到线上环境中。

部署完成后，我们可以在小程序中调用该云函数：

wx.cloud.callFunction({
  // 云函数名称
  name: 'add',
  // 传给云函数的参数
  data: {
    a: 1,
    b: 2,
  },
  success: function(res) {
    console.log(res.result) // 3
  },
  fail: console.error
})

当然，Promise 风格的调用也是支持的：

wx.cloud.callFunction({
  // 云函数名称
  name: 'add',
  // 传给云函数的参数
  data: {
    a: 1,
    b: 2,
  },
})
.then(res => {
  console.log(res.result) // 3
})
.catch(console.error)

那么到这里，我们就成功创建了我们的第一个云函数，并在小程序中成功调用！

接下来，我们介绍云函数和小程序登录态如何无缝结合，以及如何在云函数端获取小程序用户信息（openid 和 appid）。

---

获取小程序用户信息

云开发的云函数的独特优势在于与微信登录鉴权的无缝整合。当小程序端调用云函数时，云函数的传入参数中会被注入小程序端用户的 openid，开发者无需校验 openid 的正确性，因为微信已经完成了这部分鉴权，开发者可以直接使用该 openid。与 openid 一起同时注入云函数的还有小程序的 appid。

从小程序端调用云函数时，开发者可以在云函数内使用 wx-server-sdk 提供的 getWXContext 方法获取到每次调用的上下文（appid、openid等），无需维护复杂的鉴权机制，即可获取天然可信任的用户登录态（openid）。可以写这么一个云函数进行测试：

// index.js
const cloud = require('wx-server-sdk')
exports.main = (event, context) => {
  // 这里获取到的 openId、 appId 和 unionId 是可信的，注意 unionId 仅在满足 unionId 获取条件时返回
  let { OPENID, APPID, UNIONID } = cloud.getWXContext() 

  return {
    OPENID,
    APPID,
    UNIONID,
  }
}

假设云函数命名为 test，上传并部署该云函数后，可在小程序中测试调用：

wx.cloud.callFunction({
  name: 'test',
  complete: res => {
    console.log('callFunction test result: ', res)
  }
})

会在调试器看到输出的 res 为如下结构的对象：

{
  "APPID": "xxx",
  "OPENID": "yyy",
  "UNIONID": "zzz", // 仅在满足 unionId 获取条件时返回
}

接下来，我们一起看看如果在云函数中需要进行一段异步操作再返回的时候该如何处理。

---

异步返回结果

经常，我们需要在云函数中处理一些异步操作，在异步操作完成后再返回结果给到调用方。此时我们可以通过在云函数中返回一个 Promise 的方法来完成。

一个最简的 setTimeout 示例：

// index.js
exports.main = async (event, context) => {
  return new Promise((resolve, reject) => {
    // 在 3 秒后返回结果给调用方（小程序 / 其他云函数）
    setTimeout(() => {
      resolve(event.a + event.b)
    }, 3000)
  })
}

假设云函数名字为 test，上传部署该云函数后，我们可以在小程序端测试调用：

// 在小程序代码中：
wx.cloud.callFunction({
  name: 'test',
  data: {
    a: 1,
    b: 2,
  },
  complete: res => {
    console.log('callFunction test result: ', res)
  },
})

此时应该看到调试器输出：

callFunction test result: 3

---

使用 npm

在云函数中我们可以引入第三方依赖来帮助我们更快的开发。云函数的运行环境是 Node.js，因此我们可以使用 npm 安装第三方依赖。比如除了使用 Node.js 提供的原生 http 接口在云函数中发起网络请求，我们还可以使用一个流行的 Node.js 网络请求库 request 来更便捷的发起网络请求。

注意，现在上传云函数时不会在云端自动安装依赖，需要开发者在本地安装好依赖后一起打包上传。

接下来，我们一起了解下官方提供的云函数端 SDK： wx-server-sdk。

---

在云函数中使用 wx-server-sdk

云函数属于管理端，在云函数中运行的代码拥有不受限的数据库读写权限和云文件读写权限。需特别注意，云函数运行环境即是管理端，与云函数中的传入的 openId 对应的微信用户是否是小程序的管理员 / 开发者无关。

云函数中使用 wx-server-sdk 需在对应云函数目录下安装 wx-server-sdk 依赖，在创建云函数时会在云函数目录下默认新建一个 package.json 并提示用户是否立即本地安装依赖。请注意云函数的运行环境是 Node.js，因此在本地安装依赖时务必保证已安装 Node.js，同时 node 和 npm 都在环境变量中。如不本地安装依赖，可以用命令行在该目录下运行：

npm install --save wx-server-sdk@latest

在云函数中调用其他 API 前，同小程序端一样，也需要执行一次初始化方法：

const cloud = require('wx-server-sdk')
// 默认配置
cloud.init()
// 或者传入自定义配置
cloud.init({
  env: 'some-env-id'
})

wx-server-sdk 与小程序端的云 API 以同样的风格提供了数据库、存储