关于这个文档
这个文档的目的是为了全面的阐述Nodejs API,本文将从现有的模块和概念方面入手。每部分将解释一个模块或者概念。属性类型,方法参数和事件处理的参数都会在合适的地方详细的以列表的形式提供在标题的底下。
一个简单的Node.js用法例子
一个用Node.js写的服务器,并提供‘Hello World’的回复。
const http = require('http');
const hostname = '127.0.0.1';
const port = 3000;
const server = http.createServer((req, res) => {
res.statusCode = 200;
res.setHeader('Content-Type', 'text/plain');
res.end('Hello World\n');
});
server.listen(port, hostname, () => {
console.log(`Server running at http://${hostname}:${port}/`);
});
如果要运行这个例子,我们需要把这个代码片放在一个example.js的文件里,然后用node执行。
$ node example.js
Server running at http://127.0.0.1:3000/
断言测试 assert
assert 模块提供了一套断言测试功能。这个模块是为Nodejs内部使用设计的, 但是也可以经过require(‘assert’)外部调用。 但是,这个模块并不是一个测试框架,而且也不是为了当作断言库而设计的。assert模块的API是锁住的,这意味着不能作任何更改和重写。
assert(value[, message]) v0.5.9 加入
assert.ok()的别名。
const assert = require('assert');
assert(true); // OK
assert(1); // OK
assert(false);
// throws "AssertionError: false == true"
assert(0);
// throws "AssertionError: 0 == true"
assert(false, 'it\'s false');
// throws "AssertionError: it's false"
assert.deapEqual(actual, expected[, message]) v0.1.21 加入
真实值和期望值的完全等于性。原始值的比较是用 == 运算符。
只有可以枚举的自身属性可用。deepEqual() 无法测试原型,附带的符号,和不能枚举的属性, 这会带来一些很好玩的结果。例如, 下面这个例子会抛出一个Assertion异常,因为Error属性是无法枚举的。
// WARNING: This does not throw an AssertionError!
assert.deepEqual(Error('a'), Error('b'));
“完全”相等的完全意味着自身可枚举属性的子对象也要比较(基本就是object要完全相等,包括其中的子对象。):
const assert = require('assert');
const obj1 = {
a : {
b : 1
}
};
const obj2 = {
a : {
b : 2
}
};
const obj3 = {
a : {
b : 1
}
}
const obj4 = Object.create(obj1);
assert.deepEqual(obj1, obj1);
// OK, object is equal to itself
assert.deepEqual(obj1, obj2);
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }
// values of b are different
assert.deepEqual(obj1, obj3);
// OK, objects are equal
assert.deepEqual(obj1, obj4);
// AssertionError: { a: { b: 1 } } deepEqual {}
// Prototypes are ignored
如果数据不等, 会被抛出一个可以自定义message的异常。如果message缺失,则是用默认的错误信息。
assert.deapStrictEqual(actual, expected[, message]) v1.2.0 加入
大体上和 deepEqual相似,除了两个不同。第一原始值用严格相等运算符(===)比较,第二严格相等包括原型。
const assert = require('assert');
assert.deepEqual({a:1}, {a:'1'});
// OK, because 1 == '1'
assert.deepStrictEqual({a:1}, {a:'1'});
// AssertionError: { a: 1 } deepStrictEqual { a: '1' }
// because 1 !== '1' using strict equality
异常信息定义和deapEqual一样
assert.doesNotThrow(block[, error][, message]) v0.1.21加入
断言block函数不会抛出异常。当这个函数被调用的时候,他会立即调用block函数。
如果一个异常被抛出并且和指定的error一样那么抛出AssertionError。如果不一样则还给原函数,也就是意味着抛出原有的异常。
assert.doesNotThrow(
() => {
throw new TypeError('Wrong value');
},
SyntaxError
);//抛出TypeError
assert.doesNotThrow(
() => {
throw new TypeError('Wrong value');
},
TypeError
);//抛出 AssertionError: Got unwanted exception (TypeError)
assert.doesNotThrow(
() => {
throw new TypeError('Wrong value');
},
TypeError,
'Whoops'
);//抛出AssertionError: Got unwanted exception (TypeError). Whoops
assert.equal(actual, expected[, message]) v0.1.21加入
测试强等于,和 == 运算符一样。
const assert = require('assert');
assert.equal(1, 1);
// OK, 1 == 1
assert.equal(1, '1');
// OK, 1 == '1'
assert.equal(1, 2);
// AssertionError: 1 == 2
assert.equal({a: {b: 1}}, {a: {b: 1}});
//AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
assert.fail(actual, expected, message, operator) v0.1.21加入
如果message缺失,那么异常信息为 真实值 运算符 期望值。
const assert = require('assert');
assert.fail(1, 2, undefined, '>');
// AssertionError: 1 > 2
assert.fail(1, 2, 'whoops', '>');
// AssertionError: whoops
assert.ifError(value) v0.1.97加入
当value是真值,抛出值为value的异常。这个在检测会掉函数中的error参数很有用。
const assert = require('assert');
assert.ifError(0); // OK
assert.ifError(1); // Throws 1
assert.ifError('error') // Throws 'error'
assert.ifError(new Error()); // Throws Error
assert.notDeapEqual(actual, expected[, message]) v0.1.21 加入
测试深不等,和deepEqual相反。
const assert = require('assert');
const obj1 = {
a : {
b : 1
}
};
const obj2 = {
a : {
b : 2
}
};
const obj3 = {
a : {
b : 1
}
}
const obj4 = Object.create(obj1);
assert.notDeepEqual(obj1, obj1);
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
assert.notDeepEqual(obj1, obj2);
// OK, obj1 and obj2 are not deeply equal
assert.notDeepEqual(obj1, obj3);
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
assert.notDeepEqual(obj1, obj4);
// OK, obj1 and obj2 are not deeply equal
assert.notDeapStrictEqual(actual, expected[, message]) v1.2.0 加入
测试严格深不等,和deepStrictEqual相反。
const assert = require('assert');
assert.notDeepEqual({a:1}, {a:'1'});
// AssertionError: { a: 1 } notDeepEqual { a: '1' }
assert.notDeepStrictEqual({a:1}, {a:'1'});
// OK
assert.notEqual(actual, expected[, message])
和equal相反。等同于!=
const assert = require('assert');
assert.notEqual(1, 2);
// OK
assert.notEqual(1, 1);
// AssertionError: 1 != 1
assert.notEqual(1, '1');
// AssertionError: 1 != '1'
assert.notStrictEqual(actual, expected[, message])
和StrictEuqal相反, 等同于 !==
const assert = require('assert');
assert.notStrictEqual(1, 2);
// OK
assert.notStrictEqual(1, 1);
// AssertionError: 1 != 1
assert.notStrictEqual(1, '1');
// OK
assert.ok(value[, message])
判断value是否为真。等同于 assert.equal(!!value, true, message)
const assert = require('assert');
assert.ok(true); // OK
assert.ok(1); // OK
assert.ok(false);
// throws "AssertionError: false == true"
assert.ok(0);
// throws "AssertionError: 0 == true"
assert.ok(false, 'it\'s false');
// throws "AssertionError: it's false"
assert.strictEqual(actual, expected[, message])
等同于 ===
const assert = require('assert');
assert.strictEqual(1, 2);
// AssertionError: 1 === 2
assert.strictEqual(1, 1);
// OK
assert.strictEqual(1, '1');
// AssertionError: 1 === '1'
assert.throws(block[, error][, message]) v0.1.21加入
检查block函数是否抛出异常。如果指定error,它可以是正则,验证函数或者构造函数。
assert.throws(
() => {
throw new Error('Wrong value');
},
Error
);// 构造函数
assert.throws(
() => {
throw new Error('Wrong value');
},
/value/
);// 正则
assert.throws(
() => {
throw new Error('Wrong value');
},
function(err) {
if ( (err instanceof Error) && /value/.test(err) ) {
return true;
}
},
'unexpected error'
);// 自定义的验证函数
注意这里error不可以是一个字符串,如果字符串被当作第二个参数,那么error参数项被忽略,字符串被当作异常信息。这个是常见易错处。
// THIS IS A MISTAKE! DO NOT DO THIS! 错的不要这样
assert.throws(myFunction, 'missing foo', 'did not throw with expected message');
// Do this instead. 这样
assert.throws(myFunction, /missing foo/, 'did not throw with expected message');