胡新敏的个人博客

`nodejs-depd`简介

假如我们开发了一个模块，有一些属性和方法，但是后来觉得这些属性或者方法不好用，于是就废弃了，但是可能使用你模块的用户还是使用旧的方法或者属性，如果没有提示的话，报错了但是用户都不知道为什么，所以我们很需要在对模块更新的时候，当用户使用了一些废弃的方法或者属性的时候，告诉用户，这个方法或者属性已经被废弃了，请使用新的方法或者属性。

nodejs-depd就是一个专门处理模块废弃属性或者方法的工具，它可以很方便地标记出模块已经废弃的方法或者属性，方便模块更新并且不影响用户使用。

安装

使用npm安装即可：

npm install depd --save

nodejs-depd也可以使用webpack等工具进行打包，尽管默认地这个模块会修改它的API不再展示或者追踪废弃的属性或者方法。

开始使用

直接在你的文件中调用即可：

var deprecate = require('depd')('my-module')

该库允许您向用户显示弃用消息。这个库通过反省堆栈（但仅仅是它感兴趣的那些位）而超出了弃用警告。

与其仅仅在第一次调用已弃用的函数时发出警告，这个模块会在第一次调用每个唯一调用站点的弃用函数时发出警告，这使得它非常适合在整个代码库中提醒用户所有不推荐使用的用户，无论先执行了任何函数。

来自该模块的弃用警告还包括调用已弃用函数所在模块的文件和行信息。

注意这个库具有与调试模块类似的接口，并且该模块使用调用文件来获取调用堆栈的边界，所以您应该始终在每个文件中创建一个新的弃用对象，而不是在某个中央文件中。

API

该模块有如下几个API接口可供使用：

depd(namespace)

创建一个新的弃用函数，它在消息中使用给定的名称空间名称，并在堆栈输入该函数被调用的文件之前显示调用站点。强烈建议您使用模块的名称作为命名空间

deprecate(message)

从废弃的代码中调用该方法展示废弃的消息，这个消息将会在每个独立的caller点中显示，caller点就是在不同的文件堆栈中第一次被调用的点。
如果省略该消息，则会根据deprecate()调用的站点为您生成一条消息，并显示所调用函数的名称，类似于堆栈跟踪中显示的名称。

deprecate.function(fn, message)

该方法去包含一个给定的函数，在任何调用这个给定函数的时候都会调用该方法，message是可选的自定义提示消息。

deprecate.property(obj, prop, message)

该方法第一个参数是一个对象，第二个是该对象上的属性（属于该对象自己的属性，而不是继承自prototype的属性），只要这个对象上的该属性被get或者set的时候，就会调用该方法。

process.on('deprecation', fn)

你还可以在全局对象process中捕获deprecation给它添加自定义监听函数，一旦添加了监听函数，将会覆盖所有的废弃消息。监听函数有一个参数是err，这个参数具有以下几个属性：

message - 提示消息
name - 默认为 'DeprecationError'
namespace - 命名空间
stack - 调用栈
例如：

DeprecationError: my-cool-module deprecated oldfunction
    at Object.<anonymous> ([eval]-wrapper:6:22)
    at Module._compile (module.js:456:26)
    at evalScript (node.js:532:25)
    at startup (node.js:80:7)
    at node.js:902:3

process.env.NO_DEPRECATION

如果你想禁止废弃消息，可以在执行环境中设置:

NO_DEPRECATION=my-module1,my-module2,my-module3 node app.js

这样就会禁止这些模块的废弃消息，如果想要禁用所有的使用*即可，如果是Nodejs 0.8或者更高，还能使用--no-deprecation来禁止废弃消息。

process.env.TRACE_DEPRECATION

如果你想看的更多废弃消息的细节，比如堆栈跟踪等，你可以在执行环境中设置：

TRACE_DEPRECATION=my-module1,my-module2,my-module3 node app.js

如果想要查看所有模块的具体消息，可以使用*。如果是Nodejs 0.8或者更高，可以使用--trace-deprecation来显示具体消息，注意，它不会显示被NO_DEPRECATION禁止的废弃消息。

示例

示例一：

var deprecate = require('depd')('my-cool-module')
exports.oldfunction = deprecate.function(function () {}, 'oldfunctionssss')

执行脚本为：

var oldfunction =  require('./oldfunction').oldfunction
oldfunction();

执行结果为：

my-cool-module deprecated oldfunctionssss test.js:2:1

示例二：

var deprecate = require('depd')('my-cool-module')
exports.weirdfunction = function () {
  if (arguments.length < 2) {
    // 如果参数数量小于2则显示废弃消息
    deprecate('weirdfunction args < 2')
  } else if (typeof arguments[0] !== 'string') {
    // 如果第一个参数不等于string则显示废弃消息
    deprecate('weirdfunction non-string first arg')
  }
}

示例三：

var deprecate = require('depd')('my-cool-module')
exports.oldprop = 'something'
// explicit message
deprecate.property(exports, 'oldprop', 'oldprop >= 0.10')
var obj = {a:1, b:2}
deprecate.property(obj, 'a', "a is deprecated")

当你在另一个文件中访问或者赋值了暴露出来的oldprop属性或者obj的a属性的时候，就会显示废弃消息。

ABOUT ME