util.promisify 的那些事儿

util.promisify是在node.js 8.x版本中新增的一个工具，用于将老式的Error first callback转换为Promise对象，让老项目改造变得更为轻松。

在官方推出这个工具以前，民间已经有不少相似的工具了，好比es6-promisify、thenify、bluebird.promisify。

以及不少其余优秀的工具，都是实现了这样的功能，帮助咱们在处理老项目的时候，没必要费神将各类代码使用Promise再从新实现一遍。

工具实现的大体思路

首先要解释一下这种工具大体的实现思路，由于在Node中异步回调有一个约定：Error first，也就是说回调函数中的第一个参数必定要是Error对象，其他参数才是正确时的数据。

知道了这样的规律之后，工具就很好实现了，在匹配到第一个参数有值的状况下，触发reject，其他状况触发resolve，一个简单的示例代码：

function util (func) {
  return (...arg) => new Promise((resolve, reject) => {
    func(...arg, (err, arg) => {
      if (err) reject(err)
      else resolve(arg)
    })
  })
}
复制代码

1. 调用工具函数返回一个匿名函数，匿名函数接收原函数的参数。
2. 匿名函数被调用后根据这些参数来调用真实的函数，同时拼接一个用来处理结果的callback。
3. 检测到err有值，触发reject，其余状况触发resolve

resolve 只能传入一个参数，因此callback中没有必要使用...arg获取全部的返回值

常规的使用方式

拿一个官方文档中的示例

const { promisify } = require('util')
const fs = require('fs')

const statAsync = promisify(fs.stat)

statAsync('.').then(stats => {
  // 拿到了正确的数据
}, err => {
  // 出现了异常
})
复制代码

以及由于是Promise，咱们可使用await来进一步简化代码：

const { promisify } = require('util')
const fs = require('fs')

const statAsync = promisify(fs.stat)

// 假设在 async 函数中
try {
  const stats = await statAsync('.')
  // 拿到正确结果
} catch (e) {
  // 出现异常
}
复制代码

用法与其余工具并无太大的区别，咱们能够很轻易的将回调转换为Promise，而后应用于新的项目中。

自定义的 Promise 化

有那么一些场景，是不可以直接使用promisify来进行转换的，有大概这么两种状况：

1. 没有遵循Error first callback约定的回调函数
2. 返回多个参数的回调函数

首先是第一个，若是没有遵循咱们的约定，极可能致使reject的误判，得不到正确的反馈。
而第二项呢，则是由于Promise.resolve只能接收一个参数，多余的参数会被忽略。

因此为了实现正确的结果，咱们可能须要手动实现对应的Promise函数，可是本身实现了之后并不可以确保使用方不会针对你的函数调用promisify。

因此，util.promisify还提供了一个Symbol类型的key，util.promisify.custom。

Symbol类型的你们应该都有了解，是一个惟一的值，这里是util.prosimify用来指定自定义的Promise化的结果的，使用方式以下：

const { promisify } = require('util')
// 好比咱们有一个对象，提供了一个返回多个参数的回调版本的函数
const obj = {
  getData (callback) {
    callback(null, 'Niko', 18) // 返回两个参数，姓名和年龄
  }
}

// 这时使用promisify确定是不行的
// 由于Promise.resolve只接收一个参数，因此咱们只会获得 Niko

promisify(obj.getData)().then(console.log) // Niko

// 因此咱们须要使用 promisify.custom 来自定义处理方式

obj.getData[promisify.custom] = async () => ({ name: 'Niko', age: 18 })

// 固然了，这是一个曲线救国的方式，不管如何 Promise 不会返回多个参数过来的
promisify(obj.getData)().then(console.log) // { name: 'Niko', age: 18 }
复制代码

关于Promise为何不能resolve多个值，我有一个大胆的想法，一个没有通过考证，强行解释的理由：若是能resolve多个值，你让async函数怎么return（当个乐子看这句话就好，不要当真）
不过应该确实跟return有关，由于Promise是能够链式调用的，每一个Promise中执行then之后都会将其返回值做为一个新的Promise对象resolve的值，在JavaScript中并无办法return多个参数，因此即使第一个Promise能够返回多个参数，只要通过return的处理就会丢失

在使用上就是很简单的针对可能会被调用promisify的函数上添加promisify.custom对应的处理便可。
当后续代码调用promisify时就会进行判断：

1. 若是目标函数存在promisify.custom属性，则会判断其类型：
   1. 若是不是一个可执行的函数，抛出异常
   2. 若是是可执行的函数，则直接返回其对应的函数
2. 若是目标函数不存在对应的属性，按照Error first callback的约定生成对应的处理函数而后返回

添加了这个custom属性之后，就不用再担忧使用方针对你的函数调用promisify了。
并且能够验证，赋值给custom的函数与promisify返回的函数地址是一处：

obj.getData[promisify.custom] = async () => ({ name: 'Niko', age: 18 })

// 上边的赋值为 async 函数也能够改成普通函数，只要保证这个普通函数会返回 Promise 实例便可
// 这两种方式与上边的 async 都是彻底相等的

obj.getData[promisify.custom] = () => Promise.resolve({ name: 'Niko', age: 18 })
obj.getData[promisify.custom] = () => new Promise(resolve({ name: 'Niko', age: 18 }))

console.log(obj.getData[promisify.custom] === promisify(obj.getData)) // true
复制代码

一些内置的 custom 处理

在一些内置包中，也可以找到promisify.custom的踪影，好比说最经常使用的child_process.exec就内置了promisify.custom的处理：

const { exec } = require('child_process')
const { promisify } = require('util')

console.log(typeof exec[promisify.custom]) // function
复制代码

由于就像前边示例中所提到的曲线救国的方案，官方的作法也是将函数签名中的参数名做为key，将其全部参数存放到一个Object对象中进行返回，好比child_process.exec的返回值抛开error之外会包含两个，stdout和stderr，一个是命令执行后的正确输出，一个是命令执行后的错误输出：

promisify(exec)('ls').then(console.log)
// -> { stdout: 'XXX', stderr: '' }
复制代码

或者咱们故意输入一些错误的命令，固然了，这个只能在catch模块下才可以捕捉到，通常命令正常执行stderr都会是一个空字符串：

promisify(exec)('lss').then(console.log, console.error)
// -> { ..., stdout: '', stderr: 'lss: command not found' }
复制代码

包括像setTimeout、setImmediate也都实现了对应的promisify.custom。
以前为了实现sleep的操做，还手动使用Promise封装了setTimeout：

const sleep = promisify(setTimeout)

console.log(new Date())

await sleep(1000)

console.log(new Date())
复制代码

内置的 promisify 转换后函数

若是你的Node版本使用10.x以上的，还能够从不少内置的模块中找到相似.promises的子模块，这里边包含了该模块中经常使用的回调函数的Promise版本（都是async函数），无需再手动进行promisify转换了。

并且我本人以为这是一个很好的指引方向，由于以前的工具实现，有的选择直接覆盖原有函数，有的则是在原有函数名后边增长Async进行区分，官方的这种在模块中单独引入一个子模块，在里边实现Promise版本的函数，其实这个在使用上是很方便的，就拿fs模块进行举例：

// 以前引入一些 fs 相关的 API 是这样作的
const { readFile, stat } = require('fs')

// 而如今能够很简单的改成
const { readFile, stat } = require('fs').promises
// 或者
const { promises: { readFile, stat } } = require('fs')
复制代码

后边要作的就是将调用promisify相关的代码删掉便可，对于其余使用API的代码来说，这个改动是无感知的。
因此若是你的node版本够高的话，能够在使用内置模块以前先去翻看文档，有没有对应的promises支持，若是有实现的话，就能够直接使用。

promisify 的一些注意事项

1. 必定要符合Error first callback的约定
2. 不能返回多个参数
3. 注意进行转换的函数是否包含this的引用

前两个问题，使用前边提到的promisify.custom均可以解决掉。
可是第三项可能会在某些状况下被咱们所忽视，这并非promisify独有的问题，就一个很简单的例子：

const obj = {
  name: 'Niko',
  getName () {
    return this.name
  }
}

obj.getName() // Niko

const func = obj.getName

func() // undefined
复制代码

相似的，若是咱们在进行Promise转换的时候，也是相似这样的操做，那么可能会致使生成后的函数this指向出现问题。
修复这样的问题有两种途径：

1. 使用箭头函数，也是推荐的作法
2. 在调用promisify以前使用bind绑定对应的this

不过这样的问题也是创建在promisify转换后的函数被赋值给其余变量的状况下会发生。
若是是相似这样的代码，那么彻底没必要担忧this指向的问题：

const obj = {
  name: 'Niko',
  getName (callback) {
    callback(null, this.name)
  }
}

// 这样的操做是不须要担忧 this 指向问题的
obj.XXX = promisify(obj.getName)

// 若是赋值给了其余变量，那么这里就须要注意 this 的指向了
const func = promisify(obj.getName) // 错误的 this
复制代码

小结

我的认为Promise做为当代javaScript异步编程中最核心的一部分，了解如何将老旧代码转换为Promise是一件颇有意思的事儿。
而我去了解官方的这个工具，缘由是在搜索Redis相关的Promise版本时看到了这个readme：

This package is no longer maintained. node_redis now includes support for promises in core, so this is no longer needed.

而后跳到了node_redis里边的实现方案，里边提到了util.promisify，遂抓过来研究了一下，感受还挺有意思，总结了下分享给你们。

参考资料

• util.promisify
• child_process.exec
• fs.promises