node-postgres 的 ESM/CJS 双模块导出兼容性测试实践:深入 pg-esm-test 内部测试包

原创2026-09-21 21:23:271,736 阅读
文章标签:数据库关系型数据库后端

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"
  }
}

值得注意的细节有三点:

  1. "type": "module":整个包以 ESM 模式运行,.js 文件默认按 ESM 解析——这与被测试的"ESM 消费方"视角一致。
  2. 测试脚本 node --test --conditions=workerd:使用 Node.js 内置的 test runner(无需额外测试框架),并显式声明 workerd 条件。--conditions 会传递给 Node 的模块解析器,使得 package.json 的 exports 字段中标注 "workerd" 条件的条目(如 pg-cloudflare 相关导出)能被正确命中。这正是本包能同时覆盖 Cloudflare Workers 场景的奥秘。
  3. 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 环境下的三个关键运行时行为:

  1. 构造函数可用:new CloudflareSocket() 可直接实例化;
  2. 底层 socket 关闭后安全 end:模拟 closed Promise 已 resolve 后调用 end() 不抛异常,且内部 _cfSocket 引用被清空;
  3. write(data, callback) 回调恰好调用一次:无论底层写入成功与否,回调不得重复触发;
  4. 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 这套"包契约回归测试"模式都值得直接借鉴。

登录后查看全文
node-postgres