用途
该技能用于在 evlog 包中新增一个内置 enricher(增强器)。enricher 的作用是为宽事件(wide events)添加派生的上下文信息,例如部署元数据、租户上下文、功能开关等。每个 enricher 都构建在公共工具包原语 defineEnricher 之上(来自 evlog/toolkit),因此社区 enricher 与内置 enricher 具有相同的形状。
主要能力与改动范围
技能以“接触点清单”(Touchpoints Checklist)的形式规定需要改动的 7 个文件:
packages/evlog/src/enrichers/index.ts:添加 enricher 源码(一次 defineEnricher 调用)。- 同一文件中的
createDefaultEnrichers():决定该 enricher 是否加入默认组合。 packages/evlog/test/toolkit/enrichers.test.ts:添加测试(每个 enricher 一个 describe 块)。apps/docs/content/5.use-cases/5.enrichers.md:添加 enricher 章节,并更新导入列表;若适用,更新“All built-in enrichers”默认组合说明。skills/review-logging-patterns/SKILL.md:在 Enrichers 小节的Built-in:行中加入该 enricher。packages/evlog/README.md:在 Built-in Enrichers 小节加入该 enricher(根README.md是指向它的符号链接)。.changeset/{name}-enricher.md:创建 changeset(minor)。
技能强调:在所有 7 个接触点处理完毕之前,任务不视为完成。
PR 标题格式为 feat(core): add the {name} enricher。由于 enrichers 位于核心包表面(evlog/enrichers),除非存在专用 scope,否则使用 core scope。
是否加入 createDefaultEnrichers()
createDefaultEnrichers() 通过 composeEnrichers(来自 ../shared/compose)组合 user agent、geo、request size 和 trace context。只有当新 enricher 普遍适用且只读取请求(headers/env)时才加入组合;任何需要服务特定设置或额外开销的 enricher 都保持为可选(opt-in)。改变默认组合会对每个现有 createDefaultEnrichers() 用户产生行为变更,必须在 changeset 中明确指出。
命名规范
{name}:camelCase,用于事件字段键,例如userAgent。{Name}:PascalCase,用于函数/接口名,例如UserAgent。{DISPLAY}:人类可读显示名,例如User Agent。
使用方式:源码
在 packages/evlog/src/enrichers/index.ts 中添加 enricher,参考 references/enricher-template.md 获取完整带注释模板。
契约是 defineEnricher<T>({ name, field, compute }, options?)。只需提供一段逻辑:
compute(ctx):返回计算值(类型为 T),或返回undefined以跳过。
defineEnricher 负责其余部分:通过 mergeEventField 合并(遵循 options.overwrite,默认 false);错误隔离(抛出的异常被捕获并记录,不会向上传播);当 compute 返回 undefined 时跳过。
关键规则:
- 使用工具包辅助函数:
getHeader()用于大小写不敏感的 header 查找,normalizeNumber()用于数字字符串。二者来自../shared/headers(由evlog/toolkit重新导出)。 - 单一事件字段:每个 enricher 在
ctx.event上写入一个顶层字段。若 enricher 还必须固定顶层字段(如createTraceContextEnricher对event.traceId/event.parentSpanId所做),则将defineEnricher结果包裹在闭包中,可参考该 enricher 的模式。 - 工厂模式:
create{Name}Enricher(options: EnricherOptions = {})返回defineEnricher(...)的结果;正常情况下直接返回,或在 enricher 还需固定顶层字段时通过轻量闭包包装返回。 - 无副作用:绝不抛出异常、绝不记录日志;出错时依赖
defineEnricher的内置错误处理。 - 导出 Info 类型:导出描述字段形状的
{Name}Info,与工厂函数一起导出。
测试
在 packages/evlog/test/toolkit/enrichers.test.ts 中添加测试,遵循现有结构(每个 enricher 一个 describe 块)和 packages/evlog/test/README.md 约定。必需的测试类别:
- 从来源设置字段:验证 enricher 正确填充事件字段,读取其实际读取的内容(
ctx.request、ctx.response、process.env、ctx.event或 headers)。 - 源数据缺失时跳过:验证所需输入不存在时不设置字段。
- 保留已有数据:验证
overwrite: false(默认)不会替换用户提供的字段。 - 请求时覆盖:验证
overwrite: true替换已有字段。 - 处理边界情况:空字符串与畸形值,以及基于 header 的 enricher 的大小写不敏感查找。
- 默认组合:若 enricher 加入了
createDefaultEnrichers(),扩展该组合的测试。
文档更新
编辑 apps/docs/content/5.use-cases/5.enrichers.md:
- 将 enricher 加入顶部导入列表。
- 添加
## {DISPLAY}章节,遵循现有结构:一句话描述;**Sets:** event.{name};TypeScript 代码块const enrich = create{Name}Enricher();Output shape 的interface {Name}Info { // fields };Example output 的 JSON 示例。 - 若 enricher 加入了默认组合,更新“All built-in enrichers”章节文本。
自定义 enricher 编写文档单独位于 apps/docs/content/6.extend/5.custom-enrichers.md,除非工具包契约本身变化,否则无需改动。
在 skills/review-logging-patterns/SKILL.md(发布于 evlog.dev)中找到 Enrichers 部分,将新 enricher 加入 Built-in: 行。
在 packages/evlog/README.md(根 README.md 是指向它的符号链接)的 Built-in Enrichers 章节加入该 enricher。
创建 .changeset/{name}-enricher.md,使用 minor 版本提升,描述该 enricher 设置什么以及何时使用;若默认组合发生变化需明确提及。
验证
cd packages/evlog
pnpm run lint
pnpm run typecheck
pnpm run test
pnpm run build
适用场景与限制
适用于向 evlog 包贡献新的内置 enricher 的开发者场景,涉及源码、测试与文档的完整改动。限制:需严格完成全部 7 个接触点;仅有普遍适用且只读取 headers/env 的 enricher 才应加入默认组合,否则保持 opt-in,避免对现有用户造成行为变更。