Cognito IAuthenticationCallback.onFailure类型及err对象结构查询

版本变更带来的结构差异 #

使用amazon-cognito-identity-js实现用户名密码认证时，cognitoUser.authenticateUser方法传入的onFailure回调，在1.31.0到5.2.9的版本跨度中存在不兼容的结构变更：

• 1.31.0版本返回的错误对象外层包含@timestamp、level字段，内层message对象携带错误码、错误描述、请求ID、重试延迟、是否可重试、HTTP状态码、请求时间等全量上下文

{
  "@timestamp": "2022-07-11T10:41:50.924Z",
  "level": "ERROR",
  "message": {
    "code": "UserNotFoundException",
    "message": "User does not exist.",
    "requestId": "346602ab-aaaa-aaaa-babd-a7c252232604",
    "retryDelay": 74.33847546147882,
    "retryable": false,
    "statusCode": 400,
    "time": "2022-07-11T10:41:50.922Z"
  }
}

• 5.2.9版本返回的错误对象外层保留@timestamp、level字段，内层message对象仅保留code、name两个错误标识字段，移除了HTTP状态码、请求ID等请求层上下文

{
  "@timestamp": "2022-07-11T10:39:27.963Z",
  "level": "ERROR",
  "message": {
    "code": "UserNotFoundException",
    "name": "UserNotFoundException"
  }
}

错误对象无官方稳定结构的核心原因 #

该回调的参数类型被标注为any并非文档遗漏，本质是这个错误对象属于库内部实现的封装产物，官方从未对外承诺其结构稳定性：

• 错误来源不统一：回调抛出的错误包含三类——Cognito服务端返回的鉴权错误、底层HTTP请求层抛出的网络错误、库本身的参数校验错误，三类错误的原始结构本身差异极大，无法统一为固定的公开类型
• 封装逻辑随版本迭代调整：v5版本对错误透传逻辑做了精简，不再把底层HTTP层的状态码、请求ID等字段透传到业务回调层，这类内部逻辑调整不会在版本更新日志中作为不兼容变更单独说明

跨版本兼容的最佳实践 #

• 业务逻辑仅依赖跨版本稳定的字段：所有已发布版本中，err.message.code是始终存在的稳定字段，取值为Cognito服务端定义的固定错误码（如UserNotFoundException、NotAuthorizedException、PasswordResetRequiredException等），所有错误分支判断都应该基于该字段实现，不要依赖statusCode这类请求层的临时透传字段
• 字段取值增加兜底逻辑：如果业务确实需要用到状态码、请求ID这类非稳定字段，取值时必须用可选链+默认值做兼容，例如const statusCode = err?.message?.statusCode ?? err?.statusCode ?? 500，避免字段缺失导致代码运行异常
• 回调层做错误归一化处理：不要把第三方库返回的原始错误对象直接透传到下游业务逻辑，在onFailure回调内部就将错误转换为业务侧自定义的固定结构，从根源上隔离第三方库的内部变更影响
• 版本升级前覆盖错误场景测试：升级依赖版本时，必须覆盖用户不存在、密码错误、账号锁定、网络异常等常见认证失败场景，验证错误处理逻辑符合预期后再发布上线

内容的提问来源于stack exchange，提问作者artbristol