AWS Lambda Powertools (TypeScript) 日志格式化中的属性修改问题解析

背景介绍

AWS Lambda Powertools for TypeScript 是一个帮助开发者构建无服务器应用的实用工具库。其中的 Logger 组件提供了强大的日志记录功能，允许开发者通过自定义日志格式化器（LogFormatter）来控制日志输出格式。

问题现象

在版本 2.13.1 升级到 2.14.0 后，开发者发现日志格式化过程中原始事件字段被意外修改。具体表现为：在自定义日志格式化器中屏蔽敏感字段（如 authorization）时，不仅日志输出中的字段被修改，原始事件对象也被同步修改。

技术分析

根本原因

问题并非由版本升级直接导致，而是与 JavaScript 的对象引用机制有关。在自定义日志格式化器实现中，开发者直接修改了传入的日志属性对象，而非创建副本进行操作。

对象引用机制

JavaScript 中对象是通过引用传递的。当直接修改传入的对象属性时，所有引用该对象的地方都会看到这些修改。这就是为什么原始事件对象会被意外修改的原因。

版本差异解释

在 2.14.0 版本中，Powertools 内部优化了属性处理逻辑，减少了不必要的对象复制以提升性能。这一优化使得之前"侥幸"工作的代码（直接修改传入对象）不再适用。

解决方案

正确的实现方式

开发者应该始终遵循不修改输入参数的原则，特别是在日志格式化这样的场景中。以下是改进后的实现建议：

1. 使用 structuredClone 或深拷贝方法创建对象副本
2. 在副本上进行修改操作
3. 返回新的日志项而不影响原始数据

示例代码

class SafeLogFormatter extends LogFormatter {
  private hideFields = ['authorization', 'password', 'secret'];

  private sanitizeObject(obj: Record<string, any>): Record<string, any> {
    const copy = JSON.parse(JSON.stringify(obj)); // 创建深拷贝
    for (const key in copy) {
      if (typeof copy[key] === 'object') {
        copy[key] = this.sanitizeObject(copy[key]);
      } else if (this.hideFields.includes(key)) {
        copy[key] = '**** hidden ****';
      }
    }
    return copy;
  }

  public formatAttributes(
    attributes: UnformattedAttributes,
    additionalLogAttributes: LogAttributes
  ): LogItem {
    const { message, ...rest } = this.sanitizeObject(attributes);
    const safeAdditional = this.sanitizeObject(additionalLogAttributes);
    
    const logItem = new LogItem({ message });
    logItem.addAttributes(rest);
    logItem.addAttributes(safeAdditional);
    
    return logItem;
  }
}

最佳实践

1. 不可变数据处理：始终假设传入的参数不应被修改，先创建副本再操作
2. 防御性编程：考虑添加类型检查和处理边界情况
3. 性能考量：对于大型对象，考虑更高效的深拷贝方法
4. 错误处理：妥善处理可能的异常情况

总结

在实现自定义日志格式化器时，正确处理对象引用是关键。AWS Lambda Powertools 的设计遵循函数式编程原则，鼓励不可变数据处理。开发者应当注意避免直接修改输入参数，而是通过创建副本来实现所需功能。

这一实践不仅适用于 Powertools 的日志组件，也是 JavaScript/TypeScript 开发中的通用最佳实践，能够避免许多潜在的副作用和难以调试的问题。