模块系统

NodeJS Modules

module.exports & exports

我们可以将module.exports看做require()的返回值,默认情况下是一个空对象,并且可以被设置为任意的值。而exports则是对于module.exports的引用,来减少开发者的代码量。其基本用法如下所示 :

exports.method = function() {}
module.exports.method = function() {}

在具体的使用中,譬如我们在calculator.js文件中添加了add函数,在需要将其导出时,可以进行如下导出 :

// calculator.js
module.exports.add = (a,b) => a+b

而在使用时 :

// app-use-calculator.js
const calculator = require('./calculator.js')
console.log(calculator.add(2,2)) // prints 4

模块搜索顺序

require(X) from module at path Y
1. If X is a core module,
a. return the core module
b. STOP
2. If X begins with './' or '/' or '../'
a. LOAD_AS_FILE(Y + X)
b. LOAD_AS_DIRECTORY(Y + X)
3. LOAD_NODE_MODULES(X, dirname(Y))
4. THROW "not found"
LOAD_AS_FILE(X)
1. If X is a file, load X as JavaScript text. STOP
2. If X.js is a file, load X.js as JavaScript text. STOP
3. If X.json is a file, parse X.json to a JavaScript Object. STOP
4. If X.node is a file, load X.node as binary addon. STOP
LOAD_AS_DIRECTORY(X)
1. If X/package.json is a file,
a. Parse X/package.json, and look for "main" field.
b. let M = X + (json main field)
c. LOAD_AS_FILE(M)
2. If X/index.js is a file, load X/index.js as JavaScript text. STOP
3. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP
4. If X/index.node is a file, load X/index.node as binary addon. STOP
LOAD_NODE_MODULES(X, START)
1. let DIRS=NODE_MODULES_PATHS(START)
2. for each DIR in DIRS:
a. LOAD_AS_FILE(DIR/X)
b. LOAD_AS_DIRECTORY(DIR/X)
NODE_MODULES_PATHS(START)
1. let PARTS = path split(START)
2. let I = count of PARTS - 1
3. let DIRS = []
4. while I >= 0,
a. if PARTS[I] = "node_modules" CONTINUE
c. DIR = path join(PARTS[0 .. I] + "node_modules")
b. DIRS = DIRS + DIR
c. let I = I - 1
5. return DIRS

本文翻译自 Lazlojuly 的 are-node-js-modules-singletons。本文从属于笔者的NodeJS 入门与最佳实践中的NodeJS 基础系列文章,包括NodeJS 入门NodeJS 模块导出与解析NodeJS IOStreamNodeJS HTTPS这几部分。

笔者之前在使用 require 导入模块时,特别是在导入有状态的模块时,笔者会考虑其是否在多次导入情况下依然保持单例特性,或者说对于同一个文件在不同路径下导入时,是否能够识别为一致?本文即是对该特性进行解析。

NodeJS 的模块默认情况下是单例性质的,不过其并不能保证如我们编程时设想的那样一定是单例,根据 NodeJS 的官方文档中描述,某个模块导入是否为单例受以下两个因素的影响:

  • Node 模块的缓存机制是大小写敏感的,譬如如果你require('/foo')require('/FOO')会返回两个不同的对象,尽管你的 foo 与 FOO 是完全相同的文件。

  • 模块是基于其被解析得到的文件名进行缓存的,鉴于不同的模块会依赖于其被调用的路径进行缓存鉴别,因此并不能保证你使用require('foo')会永远返回相同的对象,可能会根据不同的文件路径得到不同的对象。

创建新的 NodeJS 模块

根据 NodeJS 文档所述,文件和模块是一一对应的关系。这个也是解释上文提及的模块缓存机制的基础,我们首先创建一个简单的模块:

// counter.js
let value = 0
module.exports = {
increment: () => value++,
get: () => value,
}

在 counter.js 中我们创建了某个私有变量,并且只能通过公共的 increment 与 get 方法进行操作。在应用中我们可以如下方法使用该模块:

// app.js
const counter = require(‘./counter.js’)
counter.increment()
counter.increment()
console.log(counter.get()) // prints 2
console.log(counter.value) // prints undefined as value is private

Module Caching

NodeJS 会在第一次导入某个模块之后将该模块进行缓存,在官方文档中有如下描述:

Every call to require(‘foo’) will get exactly the same object returned, if it would resolve to the same file.

我们也可以通过如下简单的例子来验证这句话:

// app-singleton.js
const counter1 = require(./counter.js’)
const counter2 = require(./counter.js’)
counter1.increment()
counter1.increment()
counter2.increment()
console.log(counter1.get()) // prints 3
console.log(counter2.get()) // also prints 3

可以看出尽管我们两次导入了该模块,但是还是指向了同一个对象。不过并不是每次我们导入同一个模块时,都会得到相同的对象。在 NodeJS 中,模块对象有个内置的方法:Module._resolveFilename(),其负责寻找 require 中合适的模块,在找到正确的文件之后,会根据其文件名作为缓存的键名。官方的搜索算法伪代码为:

require(X) from module at path Y
1. If X is a core module,
a. return the core module
b. STOP
2. If X begins with './' or '/' or '../'
a. LOAD_AS_FILE(Y + X)
1. If X is a file, load X as JavaScript text. STOP
2. If X.js is a file, load X.js as JavaScript text. STOP
3...
4...
b. LOAD_AS_DIRECTORY(Y + X)
1. If X/package.json is a file,
a. Parse X/package.json, and look for "main" field.
b. let M = X + (json main field)
c. LOAD_AS_FILE(M)
2. If X/index.js is a file, load X/index.js as JS text. STOP
3...
4...
3. LOAD_NODE_MODULES(X, dirname(Y))
4. THROW "not found"

简单来说,加载的逻辑或者说优先级为:

  • 优先判断是不是核心模块

  • 如果不是核心模块则搜索 node_modules

  • 否则在相对路径中进行搜索

解析之后的文件名可以根据 module 对象或得到:

// counter-debug.js
console.log(module.filename) // prints absolute path to counter.js
console.log(__filename) // prints same as above
// i get: "/Users/laz/repos/medium/modules/counter-debug.js"
let value = 0
module.exports = {
increment: () => value++,
get: () => value,

在上述的例子中我们可以看出,解析得到的文件名即使被加载模块的绝对路径。而根据文件与模块一一映射的原则,我们可以得出下面两个会破坏模块导入单例性的特例。

Case Sensitivity

在大小写敏感的文件系统中或者操作系统中,不同的解析之后的文件可能会指向相同的文件,但是其缓存键名会不一致,即不同的导入会生成不同的对象。

// app-no-singleton-1.js
const counter1 = require('./counter.js')
const counter2 = require('./COUNTER.js')
counter1.increment()
console.log(counter1.get()) // prints 1
console.log(counter2.get()) // prints 0, not same object as counter1
/*
We have two different resolved filenames:
- “Users/laz/repos/medium/modules/counter.js”
- “Users/laz/repos/medium/modules/COUNTER.js”
*/

在上面的例子中,我们分别用counterCOUNTER这仅仅是大小写不同的方式导入相同的某个文件,如果是在某个大小写敏感的系统中,譬如 UBUNTU 中会直接抛出异常:

解析为不同的文件名

当我们使用require(x)并且 x 不属于核心模块时,其会自动搜索node_modules文件夹。而在 npm3 之前,项目会以嵌套的方式安装依赖。因此当我们的项目依赖 module-a 与 module-b,并且 module-a 与 module-b 也相互依赖时,其会生成如下文件路径格式:

// npm2 installed dependencies in nested way
app.js
package.json
node_modules/
|---module-a/index.js
|---module-b/index.js
|---node_modules
|---module-a/index.js

这样的话,我们对于同一个模块就有两个副本,那当我们在应用中导入 module-a 时,岂会载入如下文件:

// app.js
const moduleA = require(‘module-a’)
loads: “/node_modules/module-a/index.js”

而从 module-b 中载入 module-a 时,其载入的是如下文件:

// /node_modules/module-b/index.js
const moduleA = require(‘module-a’)
loads “/node_modules/module-b/node_modules/module-a/index.js”

不过在 npm3 之后,其以扁平化方式进行文件加载,其文件目录结构如下所示:

// npm3 flattens secondary dependencies by installing in same folder
app.js
package.json
node_modules/
|---module-a/index.js
|---module-b/index.js

不过此时就存在另一个场景,即我们应用本身依赖 module-a@v1.1 与 module-b,而 module-b 又依赖于 module-a@v1.2,在这种情况下还是会采用类似于 npm3 之前的嵌套式目录结构。这样的话对于 module-a 一样会产生不同的对象,不过此时本身就是不同的文件了,因此相互之间不会产生冲突。