CommonJS 模塊規范 1.1.1

本規范致力于描述一類可以同時適用于客戶端和服務器端的模塊系統。該系統中的模塊擁有自己的作用域，可以從其他模塊導入單例對象，或者對外提供 API。

Require

require 是一個函數對象。

1. require 函數接受一個稱為模塊標識符的參數。
2. require 函數返回外部模塊提供的 API。
3. 當發生循環依賴時，一個外部模塊被其依賴模塊導入時，它可能未被完全執行。在此種情況下，當前模塊調用 require 函數所返回的對象必須包含該外部模塊已經準備好的輸出物。
4. 如果不能返回所請求的模塊，則 require 函數應該拋出異常。

5. require 函數可以有一個 main 屬性。

   1. 當屬性 main 存在，它應該是只讀的且不能刪除。
   2. main 屬性應該是 undefined，或是已加載模塊的 module 對象。

6. require 函數可以有一個 paths 屬性，該屬性是一個具有優先秩序的路徑數組，優先級從高到低， 路徑一直回溯到頂級模塊目錄 。

   1. paths 屬性不應存在于沙盒中。
   2. 所有模塊中的 paths 屬性應該一致 。
   3. 使用另一個對象替換 paths 對象是無效的。
   4. 如果 paths 屬性存在，修改 paths 內容會對模塊搜索行為產生影響。
   5. 如果 paths 屬性存在，它所包含的路徑可能不是全部的搜索路徑。因為加載器可以能會在搜索 paths 提供的路徑之前或之后去檢查其它的路徑。
   6. 如果 paths 屬性存在， 加載器責任去解析、標準化、規范化路徑 。

模塊上下文

1. 一個模塊中只有一個自由變量 require，該變量符合以上對 require 函數的定義。

2. 一個模塊中只有一個自由變量 exports，當模塊被執行時，該模塊對外提供的 API 被添加到該 exports 對象上。

   1. 模塊必須使用 exports 對象作為唯一的輸出手段。

3. 一個模塊中應該包含一個自由變量 module，該變量是一個 Object 對象。

   1. module 對象應該擁有一個 id 屬性，它是模塊的 頂級屬性 。當執行 require(module.id) 時，返回 module.id 所屬模塊的輸出對象。如果該屬性被實現，則它應該是一個只讀屬性，不能刪除。
   2. module 對象可以有一個 uri 屬性，該屬性指向模塊源文件。uri 屬性不應存在于沙盒中。

模塊標識符

1. 模塊標識符是一個由多個詞匯組成的字符串，不同詞匯之間使用正斜杠分隔。
2. 單個詞匯應該是駝峰標識符，.或..。
3. 模塊標識符不能包含文件后綴名，例如.js。
4. 模塊標識符可以是相對的，也可以是頂級的。如果標識符首個單詞是.或..，那么該標識符就是相對的。
5. 頂級標識符是相對于所謂根命名空間而言。
6. 相對標識符是相對于 require 函數所處的模塊而言。

未說明

本規范有以下重要點未說明：

1. 模塊是否存儲于數據庫、文件系統或工廠函數中， 又或者可以和鏈接庫進行互換 。
2. 模塊加載器是否支持使用 PATH 環境變量來解析模塊標識符。

PS：本規范從 CommonJS 官方英文版本轉譯而來，斜體部分表示譯文存在商榷。

Ref.:

(CommonJS Module 1.1.1)[ http://wiki.commonjs.org/wiki/Modules/1.1.1 ]