node-postgres 的 ESM/CJS 双模块导出兼容性测试实践:深入 pg-esm-test 内部测试包
node-postgres 的 ESM/CJS 双模块导出兼容性测试实践:深入 pg-esm-test 内部测试包
导读
node-postgres 采用 monorepo 架构,pg 主包及其周边库(pg-pool、pg-cursor、pg-protocol、pg-native、pg-cloudflare 等)需要同时支持 ESM(import)与 CommonJS(require)两种模块体系,而这正是 npm 生态中最容易踩坑的"双包"问题。pg-esm-test 就是 node-postgres 为验证这一兼容性而专门设立的内部测试包:本文以 packages/pg-esm-test/README.md 为骨架,结合该包内全部测试文件与 pg 主包的 exports 映射、ESM 包装层源码,完整拆解这套模块导出兼容性测试的设计思路、运行方式与实现细节,帮助读者理解 node-postgres 如何保证"同一套 API,两种模块体系都能用"。
一、背景:为什么一个"几乎可以忽略"的包是必要的
packages/pg-esm-test/README.md 的定位非常直白——它是 node-postgres 内部用于测试 ESM 与 CJS 模块导出兼容性(esm & cjs module export compatibility)的专用包,原文甚至直言"你可以直接忽略它"。但从工程角度看,这个包承担着不可替代的职责:
- 双模块体系并存:node-postgres 的消费者既可能是传统 CommonJS 项目(
const { Pool } = require('pg')),也可能是现代 ESM 项目(import pg from 'pg'或import { Pool } from 'pg')。任何一侧的导出方式回归,都会直接影响下游生态。 - 导出面广:主包
pg暴露的不止Client与Pool,还包括Connection、defaults、types、DatabaseError、escapeIdentifier、escapeLiteral、Result、TypeOverrides等十余个命名导出;周边每个子包又有各自的默认导出/命名导出约定。 - 回归成本低但破坏性高:模块导出问题通常无法在运行时被编译器或类型系统提前拦截,只有在真实
import/require那一刻才会暴露。因此用一套独立测试包在每次 CI 中系统性验证,是最经济的防线。
二、运行方式:一行命令,随全仓测试一起执行
README 给出了唯一的运行入口——在仓库根目录执行:
yarn && yarn test
这条命令不仅会运行 pg-esm-test 的用例,还会触发整个 monorepo 的所有测试。结合根目录 package.json 可以看出其工作机制:
{
"workspaces": ["packages/*"],
"scripts": {
"pretest": "yarn build",
"test": "yarn lerna exec --concurrency 1 yarn test"
}
}
workspaces将packages/*下所有包(包括pg-esm-test)链接进统一依赖树,因此测试文件里直接import from 'pg'、from 'pg-pool'等裸模块名即可解析到本地源码。pretest先执行tsc --build,保证pg-protocol等 TypeScript 包的产物(dist/目录)已生成——这一点很关键,因为pg-esm-test的部分测试直接加载pg-protocol/dist/messages.js。- 根
yarn test通过lerna exec --concurrency 1 yarn test逐个包运行各自的test脚本,pg-esm-test正是其中一环。
也就是说:开发者在日常开发中不需要单独关心这个包,只要按 monorepo 的标准流程跑测试,模块导出兼容性就会被自动覆盖。
三、包的工程形态:一个纯 ESM 测试包
packages/pg-esm-test/package.json 揭示了该包的关键工程决策:
{
"name": "pg-esm-test",
"version": "1.9.0",
"type": "module",
"main": "index.js",
"scripts": {
"test": "node --test --conditions=workerd"
},
"devDependencies": {
"pg": "^8.23.0",
"pg-cloudflare": "^1.4.0",
"pg-cursor": "^2.22.0",
"pg-native": "^3.9.0",
"pg-pool": "^3.14.0",
"pg-protocol": "^1.16.0",
"pg-query-stream": "^4.17.0"
}
}
值得注意的细节有三点:
"type": "module":整个包以 ESM 模式运行,.js文件默认按 ESM 解析——这与被测试的"ESM 消费方"视角一致。- 测试脚本
node --test --conditions=workerd:使用 Node.js 内置的 test runner(无需额外测试框架),并显式声明workerd条件。--conditions会传递给 Node 的模块解析器,使得package.json的exports字段中标注"workerd"条件的条目(如pg-cloudflare相关导出)能被正确命中。这正是本包能同时覆盖 Cloudflare Workers 场景的奥秘。 - devDependencies 覆盖全部被验证的包:
pg、pg-cloudflare、pg-cursor、pg-native、pg-pool、pg-protocol、pg-query-stream——验证范围与 node-postgres 的包矩阵一一对应。
测试文件后缀也体现了双模块策略:以 .js 结尾的是 ESM 用例,以 .cjs 结尾的(common-js-imports.test.cjs)则强制以 CommonJS 解析,node --test 会同时收集这两类文件。
四、主包 pg 的 ESM 命名导出验证
4.1 测试用例:逐一断言命名导出
packages/pg-esm-test/pg.test.js 是对主包 pg 最完整的 ESM 契约测试,它一次性导入全部导出并逐一验证:
import pg, {
Client, Pool, Connection, defaults, types, DatabaseError,
escapeIdentifier, escapeLiteral, Result, TypeOverrides,
} from 'pg'
describe('pg', () => {
it('should export Client constructor', () => {
assert.ok(new Client())
})
it('should export Pool constructor', () => {
assert.ok(new Pool())
})
it('should still provide default export', () => {
assert.ok(new pg.Pool())
})
// Connection、defaults、types、DatabaseError、
// escapeIdentifier、escapeLiteral、Result、TypeOverrides 同样逐一断言
})
这段代码同时验证了两条契约:所有命名导出可用(且 Client、Pool 等是可实例化的构造函数),以及 默认导出仍然存在(pg.Pool 可用),确保既兼容 import { Pool } from 'pg' 也兼容 import pg from 'pg' 两种主流写法。
4.2 底层原理:exports 映射 + ESM 包装层
上述测试能通过,依赖 pg 主包的两层设计。首先是 packages/pg/package.json 中的 exports 条件导出:
"main": "./lib",
"exports": {
".": {
"import": "./esm/index.mjs",
"require": "./lib/index.js",
"default": "./lib/index.js"
},
"./package.json": { "default": "./package.json" },
"./lib/*": "./lib/*.js",
"./lib/*.js": "./lib/*.js"
}
- 当消费者以 ESM
import方式加载时,Node 命中"import"条件,指向 ESM 包装层esm/index.mjs; - 当以 CommonJS
require方式加载时,命中"require"条件,直接指向lib/index.js; - 同时保留
./lib/*与./lib/*.js子路径导出,允许深层引用(如require('pg/lib/connection-parameters')),这一点在 CJS 测试中也被显式覆盖。
其次,packages/pg/esm/index.mjs 是一个轻量的"再导出"包装层:它先以 CommonJS 方式加载 ../lib/index.js,再把其所有属性显式 export 出去,同时保留默认导出:
// ESM wrapper for pg
import pg from '../lib/index.js'
export const Client = pg.Client
export const Pool = pg.Pool
export const Connection = pg.Connection
export const types = pg.types
export const Query = pg.Query
export const DatabaseError = pg.DatabaseError
export const escapeIdentifier = pg.escapeIdentifier
export const escapeLiteral = pg.escapeLiteral
export const Result = pg.Result
export const TypeOverrides = pg.TypeOverrides
export const defaults = pg.defaults
export default pg
这种"单一事实来源(lib/index.js)+ ESM 薄包装"的模式,避免了双包中常见的"同一模块被加载两份实例、状态不共享"问题——ESM 与 CJS 最终引用的是同一个底层模块对象,这也是 pg.test.js 中默认导出与命名导出能指向同一 Pool 的原因。从源码结构可以推断,这也是 node-postgres 各子包(pg-pool、pg-cursor 等)统一采用 esm/index.mjs 包装层设计的共同模式。
五、CommonJS 侧:require 兼容性回归测试
ESM 只是半边天,CommonJS 依然是海量存量项目的主战场。common-js-imports.test.cjs 以 .cjs 后缀强制按 CommonJS 解析,验证了从根目录到深层路径的一整套 require 契约:
const paths = [
'pg',
'pg/lib/index.js',
'pg/lib/index',
'pg/lib/connection-parameters',
'pg/lib/connection-parameters.js',
'pg/lib/type-overrides',
'pg-protocol/dist/messages.js',
'pg-protocol/dist/messages',
'pg-native/lib/build-result.js',
'pg-cloudflare/package.json',
]
for (const path of paths) {
describe(`importing ${path}`, () => {
it('works with require', () => {
const mod = require(path)
assert(mod)
})
})
}
这段测试覆盖了三种典型的 CJS 使用姿势:
- 裸包名:
require('pg')、require('pg-protocol')—— 验证exports根映射; - 带/不带扩展名的深层路径:
pg/lib/index.js与pg/lib/index、pg/lib/connection-parameters与pg/lib/connection-parameters.js—— 验证子路径导出在两种书写方式下都可用(对老代码库兼容性尤为重要); - JSON 资源:
require('pg-cloudflare/package.json')—— 验证exports中为./package.json单独开放的通道。
此外该文件还包含一个真实的端到端冒烟用例:通过 pg 的 native 模式(pg-native)创建 Pool 并执行 SELECT 1,断言 result.rowCount === 1。需要说明的是,这个用例依赖本机存在可连接的 PostgreSQL 实例,属于集成性质的检查。
六、周边包的 ESM 导出契约测试
主包之外,node-postgres 的每个子包都配了独立的 ESM 导入测试,形成了"一包一测"的契约矩阵:
| 测试文件 | 验证目标 | 断言要点 |
|---|---|---|
| pg-pool.test.js | pg-pool |
默认导出 Pool 构造函数可实例化 |
| pg-cursor.test.js | pg-cursor |
默认导出 Cursor 构造函数可实例化 |
| pg-query-stream.test.js | pg-query-stream |
默认导出 QueryStream 构造函数可实例化 |
| pg-native.test.js | pg-native |
默认导出 Client 构造函数可实例化 |
| pg-protocol.test.js | pg-protocol |
从 dist/messages.js 命名导出 DatabaseError、NoticeMessage、noData、parseComplete |
其中 pg-protocol.test.js 尤其值得关注,因为 pg-protocol 是仓库中的 TypeScript 包,产物输出到 dist/ 目录。它验证了两件事:一是从 pg-protocol/dist/messages.js 直接命名导入 DatabaseError、NoticeMessage 等消息类;二是验证默认导出的协议常量对象上挂载了 noData、parseComplete 等消息构造器。这类"从 dist 目录导入"的模式,正是很多下游工具链(例如把 pg-protocol 用作协议解析基础库的场景)的实际用法,单独测试能防止 TypeScript 编译产物变动破坏导出结构。
从各测试文件的写法可以归纳出 node-postgres 的导出约定:pg-pool、pg-cursor、pg-query-stream、pg-native 均以默认导出为主(构造函数直接作为 default),而 pg 主包与 pg-protocol 同时提供命名导出。这为外部消费者提供了稳定的导入范式参考。
七、pg-cloudflare:workerd 条件下的运行时行为验证
pg-cloudflare.test.js 是最特殊的一份测试——它不止验证导出,还深入验证了 CloudflareSocket 在模拟 Cloudflare Workers 环境下的三个关键运行时行为:
- 构造函数可用:
new CloudflareSocket()可直接实例化; - 底层 socket 关闭后安全 end:模拟
closedPromise 已 resolve 后调用end()不抛异常,且内部_cfSocket引用被清空; write(data, callback)回调恰好调用一次:无论底层写入成功与否,回调不得重复触发;- closed Promise 永不 settle 时仍能发出 close 事件:即使底层 socket 的关闭承诺永远不兑现,
end()也会在 100ms 超时保护下主动发出close事件,避免事件泄漏。
这些用例之所以能在本包运行,正是因为测试命令中携带了 --conditions=workerd:Node 在解析 pg-cloudflare 等包的 exports 时会额外启用 workerd 条件,让测试环境尽可能逼近真实 Workers 运行时。这四类行为直接关系到 Cloudflare Workers 场景下连接的生命周期管理,是"导出存在"之外的更深一层质量保障。
八、本地复现与排查
想单独跑这套模块兼容性测试,可以这样做(仓库为只读,以下均为查看与运行类操作):
# 1. 在仓库根目录安装依赖(workspaces 会链接全部包)
yarn
# 2. 先构建 TypeScript 包(pg-protocol 等需要 dist 产物)
yarn build
# 3. 进入测试包单独运行
yarn workspace pg-esm-test test
或者直接按 README 建议在根目录执行 yarn && yarn test,让 lerna 连同其他包的测试一并运行。若怀疑是模块导出问题而非业务逻辑问题,pg-esm-test 的所有用例几乎都是"导入 + 实例化/属性断言",失败信息能直接定位到具体包与具体导出名,排查成本极低。
九、总结
从 packages/pg-esm-test/README.md 的一句话说明出发,可以看到 node-postgres 在模块兼容性上投入的完整工程化设计:
- 单一事实来源:所有包的 ESM 支持都基于
lib/下的 CJS 实现加esm/index.mjs薄包装,配合package.json的exports条件映射,避免双包状态分裂; - 双视角回归:
.js(ESM)与.cjs(CommonJS)两类测试文件,覆盖命名导出、默认导出、深层路径、扩展名有无、JSON 资源等多种消费姿势; - 环境仿真:
node --test --conditions=workerd让 Cloudflare Workers 相关代码在本地即可获得运行时行为验证; - 零成本集成:作为 workspace 成员自动接入
yarn test流水线,开发者无需额外心智负担。
对于任何维护"一库多包、双模块体系"的 JavaScript 项目,pg-esm-test 这套"包契约回归测试"模式都值得直接借鉴。