util.promisify 的那些事儿

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

在官方推出这个工具之前,民间已经有很多类似的工具了,比如es6-promisifythenifybluebird.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类型的keyutil.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以外会包含两个,stdoutstderr,一个是命令执行后的正确输出,一个是命令执行后的错误输出:

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' }

包括像setTimeoutsetImmediate也都实现了对应的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,遂抓过来研究了一下,感觉还挺有意思,总结了下分享给大家。

参考资料


全沾开发(huā)
各种前端相关&Node.js

GitHub: [链接]

5k 声望
4.7k 粉丝
0 条评论
推荐阅读
Verdaccio publish 时包含 deprecated 导致历史版本丢失问题原因分析
公司内部的 NPM 因为一些固有的 bug 经常被吐槽,最近刚好有时间可以来做优化,然后就尝试解一下之前遇到的一个 publish 的 bug,下边是分析记录。

贾顺名阅读 2.2k

正则表达式实例
收集在业务中经常使用的正则表达式实例,方便以后进行查找,减少工作量。常用正则表达式实例1. 校验基本日期格式 {代码...} {代码...} 2. 校验密码强度密码的强度必须是包含大小写字母和数字的组合,不能使用特殊...

寒青56阅读 8.4k评论 11

JavaScript有用的代码片段和trick
平时工作过程中可以用到的实用代码集棉。判断对象否为空 {代码...} 浮点数取整 {代码...} 注意:前三种方法只适用于32个位整数,对于负数的处理上和Math.floor是不同的。 {代码...} 生成6位数字验证码 {代码...} ...

jenemy48阅读 7k评论 12

从零搭建 Node.js 企业级 Web 服务器(十五):总结与展望
总结截止到本章 “从零搭建 Node.js 企业级 Web 服务器” 主题共计 16 章内容就更新完毕了,回顾第零章曾写道:搭建一个 Node.js 企业级 Web 服务器并非难事,只是必须做好几个关键事项这几件必须做好的关键事项就...

乌柏木75阅读 7.1k评论 16

再也不学AJAX了!(二)使用AJAX ① XMLHttpRequest
「再也不学 AJAX 了」是一个以 AJAX 为主题的系列文章,希望读者通过阅读本系列文章,能够对 AJAX 技术有更加深入的认识和理解,从此能够再也不用专门学习 AJAX。本篇文章为该系列的第二篇,最近更新于 2023 年 1...

libinfs42阅读 6.8k评论 12

封面图
从零搭建 Node.js 企业级 Web 服务器(一):接口与分层
分层规范从本章起,正式进入企业级 Web 服务器核心内容。通常,一块完整的业务逻辑是由视图层、控制层、服务层、模型层共同定义与实现的,如下图:从上至下,抽象层次逐渐加深。从下至上,业务细节逐渐清晰。视图...

乌柏木45阅读 8.5k评论 6

从零搭建 Node.js 企业级 Web 服务器(二):校验
校验就是对输入条件的约束,避免无效的输入引起异常。Web 系统的用户输入主要为编辑与提交各类表单,一方面校验要做在编辑表单字段与提交的时候,另一方面接收表单的接口也要做足校验行为,通过前后端共同控制输...

乌柏木35阅读 6.7k评论 10

GitHub: [链接]

5k 声望
4.7k 粉丝
宣传栏