该技能用于指导 @shopify/hydrogen 运行时错误处理与日志记录,适用范围为 packages/hydrogen/src 下新增或修改的运行时逻辑。
用途:界定不同类型的运行时失败应采用何种机制,避免重复上报(对同一失败既抛出又记录)。
主要能力: 分类策略。编程错误(参数错误、不变量违背)同步抛出带类型的错误;有调用方的请求级失败抛出带类型的错误,由调用方决定重试或渲染,例如 StorefrontApiError、CustomerAccountApiError、CartActionError、CartNetworkError;带内部恢复的服务器处理器捕获失败,经限定作用域的 logger 记录并返回结构化错误 Response,例如购物车服务器处理器捕获网络失败后返回 500 和 JSON 错误体;后台浏览器失败使用 error 级限定日志;误用或降级使用 warn 级限定日志;买家可见的用户错误仅暴露响应式状态,不记录日志。
日志契约。getLogger 为内部接口,不属于包的公开 API,在 src 内以相对路径导入,按模块级常量创建带作用域的 logger,消息不加前缀、偏向小写且无尾随冒号;context.error 会成为独立的 console 参数,其余上下文字段作为末尾对象传入。运行时文件禁止直接调用 console.*,由 no-console lint 规则约束。
HydrogenLogger 接口。包含 trace、debug、info、warn、error、fatal 六个级别方法,LogContext 为 { scope?: string; error?: unknown; [key: string]: unknown }。
configureLogging 配置。在应用启动时调用一次,可指定任意 HydrogenLogger 和最低转发级别(默认 info),后调用覆盖先前配置。默认 console 输出格式为 [hydrogen:<level>:<scope>] <message>,随后附 context.error 与剩余上下文字段对象。
序列化内联脚本为例外情况:Hydrogen 序列化进 HTML 的内联/CDN 脚本无法访问应用包全局状态,configureLogging 无法作用于它们。此类代码在共享模块的导入链中应直接使用 consoleLogger 并显式提供 scope,而非 getLogger;仅序列化的叶子模块则内联硬编码前缀的 console.* 调用。
使用方式:在应用启动时通过 configureLogging({ logger, level }) 配置;按失败类别选择抛出、记录或响应式状态;测试中通过注入测试 logger(六个 vi.fn 方法)替代 mock console,断言 (message, { scope, ...context }) 且不含前缀字符串,并在 afterEach 中恢复默认配置。
适用场景:@shopify/hydrogen 包内运行时逻辑的错误处理与日志规范落地,以及相关测试编写。
限制:不提供按请求的子 logger 或请求关联;作用域按子系统划分而非按请求。关于具体 error 类型定义与更多实现细节,资料暂未提供。