API 稳定性

LoggerJS 仍处于 pre-1.0。签入仓库的 api-reports/ 文件描述了每一个已导出的 TypeScript 声明，但这并不表示每个导出符号都已经冻结为 v1 API。

本页是面向人的稳定性契约。机器可读分类位于 docs/api-stability.policy.json，当某个 package export 未被纳入策略时，pnpm verify:api-stability 会失败。

当前策略

在 v1 前，项目选择收窄兼容承诺，而不是冻结整个仓库。稳定集合被刻意限制在 core logger model、core pipeline contracts、主要 browser 和 Node delivery paths、pretty output、processors 和 codecs。

其他部分仍然可能是公开的、经过测试的、可用的，但并不全部属于 v1 兼容承诺。尤其是 vendor、observability 和 database packages，在获得更多真实使用和失败模式验证前，都保持 experimental。

状态级别

状态	含义
Stable v1 Candidate	计划带入 v1，不做移除、重命名或签名破坏；安全、数据丢失或 wire-protocol 正确性修复除外。允许 additive changes。
Compatible Public Surface	公开且有测试，但还没稳定到 v1 candidate。pre-v1 minor releases 可能通过 release notes 调整 option names、captured fields 或 runtime edge behavior。
Experimental Before v1	公开 packages 或 subpaths 在 v1 前可能变化。当前行为适合时可以使用，但不要把它们视为冻结的兼容契约。

内部源码路径、dist 文件路径、生成 bundle 布局、private class fields，以及只从测试推断出的行为，在任何状态下都不是 public API。

Stable v1 Candidate

稳定 exports 在 api-stability.policy.json 中跟踪。当前稳定 packages 和入口家族如下：

Package	稳定 surface
@loggerjs/core	Root package，以及 middleware、codecs、events、context、trace propagation、payload transforms 和 core transports 的文档化 core subpaths。
@loggerjs/browser	用于 HTTP delivery、IndexedDB/offline-first storage、payload transforms，以及主要 console/error/fetch/XHR/context/performance/page-lifecycle integrations 的文档化稳定 subpaths。
@loggerjs/node	用于 stdout/stderr/file/rotating-file/HTTP/syslog/worker transports、payload transforms、process capture、outgoing HTTP capture、diagnostics 和 AsyncLocalStorage context 的文档化稳定 subpaths。
@loggerjs/pretty	Root package、formatter、console transport 和 stream transports。
@loggerjs/processors	Root package processor 和 middleware catalog。
@loggerjs/codecs	Root package codec catalog。

稳定语义包括：

• 用于应用和 library-safe logging 的 createLogger(options)、getLogger(category) 和 configure(...)。
• Logger instance methods：trace、debug、info、warn、error、fatal、log、capture、event、child、withTags、withType、setLevel、getLevel、isEnabled、isLevelEnabled、addTransport、addProcessor、addIntegration、ready、flush、flushSync 和 close。
• Level 名称和数值：trace=10、debug=20、info=30、warn=40、error=50、fatal=60 和 silent。
• Middleware、Processor、Transport、Integration、Codec 的 pipeline interfaces，包括 TransportContext.toEvent(record) 的 memoized projection。
• 禁用级别在 record 分配和 lazy message 求值前返回。
• Middleware、processors、codecs、integrations 和 transports 的错误与应用代码隔离。
• 序列化仍然归 transport 所有；middleware 和 processors 保持结构化值。

Compatible Public Surface

Compatible exports 仍然会保持文档化和测试，但还没有稳定到 v1 candidate。当前 compatible areas 包括：

• Browser 和 Node root packages（@loggerjs/browser、@loggerjs/node）是 compatible convenience aggregators，因为它们同时 re-export stable 和 compatible components。需要 v1 candidate 兼容边界时，优先使用上面的 stable subpaths。
• Browser secondary transports 和 collectors：BroadcastChannel、service worker、WebSocket、ZIP export、framework errors、framework routers、generic router capture、ReportingObserver、runtime host、service worker messages、user actions 和 WebSocket capture。
• Node framework 和 data integrations：Express、Fastify、Koa、Nest、Hapi、Prisma、Redis、generic queues、BullMQ、serverless lifecycle、database method wrapping 和 CLI capture。

pre-v1 期间这些 public import paths 应保持可用，但具体 captured fields、hook coverage 和 edge behavior 仍可能被调整。如果真实使用表明当前 API 太宽，这些区域也是 v1 前收窄命名或降低承诺的合适位置。

Experimental Before v1

这些 packages 是公开的，因为它们对集成测试和早期采用者有用，但不是 v1 兼容承诺：

Package family	Experimental exports
Observability adapters	@loggerjs/otel/*, @loggerjs/sentry/*
Vendor wire transports	@loggerjs/datadog/*, @loggerjs/elastic/*, @loggerjs/loki/*, @loggerjs/cloudwatch/*
Database transports	@loggerjs/database/*

Experimental 不等于未测试。它表示 v1 前的 minor releases 可能根据 design partners 或 live endpoints 暴露出的更好形态，调整 option names、payload mapping、retry expectations、batching guidance 或 subpath layout。

Raw vendor transports 本身不是 durable。生产投递应使用 batchTransport() 和 retryTransport() 包装，或投递到由 collector endpoint 负责 queueing、retry、authentication 和 backoff 的服务。

变更策略

对 Stable v1 Candidate APIs：

• v1 前不故意移除、重命名或破坏签名，除非有 deprecation note 和 migration path。
• 允许 additive changes：新 options、fields、overloads、processors、transports、integrations 和 subpaths。
• 影响 delivery、privacy 或 performance 的 defaults 需要文档和 release notes。
• 安全修复、数据丢失修复、vendor wire-protocol 正确性修复可能改变 edge-case behavior。Release notes 必须说明这些变化。

对 Compatible 和 Experimental APIs：

• Public exports 仍保持 typechecked、tested、API-reported 和 documented。
• pre-v1 minor releases 可以调整 names、options、field shape 或具体 behavior。
• Breaking changes 仍应带 release notes 和 migration guidance，因为 public 不等于 disposable。

新增 Public API

新的 package exports 必须：

1. 在最接近实际 runtime 的层级新增或更新测试。
2. 更新 import boundaries 和 caveats 的文档与示例。
3. 把 export 加入 docs/api-stability.policy.json。
4. 运行 pnpm verify:api-stability 和 pnpm api:check。

当现有稳定 API 能解决问题时，优先使用示例和组合，而不是新增 exports。

如何评估未来升级

1. 阅读 package changelog 和 release notes。
2. 查看本页和 api-stability.policy.json，确认你依赖的 export 状态。
3. 如果你是贡献者，在本仓库运行 pnpm check；如果你是消费者，运行自己的应用测试套件。
4. 热路径变更用 pnpm bench:node 或 pnpm bench:browser 复现相关 benchmark。
5. 远程投递要测试你的真实 collector/vendor endpoint，并监控 transport.dropped.*、transport.retry.* 和 queue-depth metrics。

相关链接

• 英文原文
• 中文首页