Effect-TS项目中HttpApiClient对非标记化错误的处理优化

在基于Effect-TS框架开发HTTP API客户端时，开发者可能会遇到一个典型问题：当服务端返回未经标记化处理的错误响应时，客户端会直接抛出解析错误导致程序中断。这种情况在集成第三方认证服务（如AWS API Gateway授权器）时尤为常见。

问题背景

在标准的Effect-TS实践中，我们通常使用标记化错误（TaggedError）来定义API错误类型。例如定义一个401未授权错误：

export class Unauthenticated extends S.TaggedError<Unauthenticated>()(
  "Unauthenticated",
  {},
  HttpApiSchema.annotations({ status: 401 }),
) {}

这种定义方式要求错误响应必须包含_tag字段。然而，当与AWS API Gateway等第三方服务集成时，这些服务返回的错误响应往往不包含Effect-TS预期的标记字段，导致客户端在解析时抛出ParseError：

ParseError: (Unauthorized (Encoded side) <-> Unauthorized)
└─ Encoded side transformation failure
   └─ Unauthorized (Encoded side)
      └─ ["_tag"]
         └─ is missing

解决方案

要解决这个问题，我们可以采用Schema-first的错误定义方式，而不是直接使用TaggedError。通过Effect-TS的Schema模块定义错误结构：

class UnauthFromAWS extends S.Class<UnauthFromAWS>("Schema")({
  message: S.String,
}) {
  readonly _tag = "UnauthFromAWS"; // 解码时自动添加的标记
}

// 注册错误到API客户端
api.addError(UnauthFromAWS, { status: 401 })

这种方案具有以下优势：

1. 兼容性：能够处理第三方服务返回的非标记化错误
2. 灵活性：可以在解码阶段添加必要的标记字段
3. 类型安全：仍然保持完整的类型检查

实现原理

这种解决方案的核心在于Effect-TS强大的Schema系统：

1. 解码阶段：当收到401响应时，Schema会验证响应体是否符合message: string的结构
2. 标记注入：在成功解码后，自动为错误实例添加_tag字段
3. 错误处理：后续的错误处理流程可以像处理标准TaggedError一样处理这个错误

最佳实践

对于需要同时处理内部和第三方错误的情况，建议：

1. 为内部错误保持使用TaggedError定义
2. 为每个需要处理的第三方错误创建对应的Schema类
3. 使用条件逻辑或模式匹配来区分错误来源

const handleError = (error: unknown) => {
  if (error instanceof UnauthFromAWS) {
    // 处理AWS返回的未授权错误
  } else if (error instanceof Unauthenticated) {
    // 处理应用自身的未认证错误
  }
}

总结

Effect-TS框架提供了灵活的错误处理机制，通过合理使用Schema系统，开发者可以优雅地处理各种来源的API错误。这种模式不仅解决了第三方服务集成的问题，也为系统提供了更好的可扩展性——当需要支持新的错误类型时，只需添加新的Schema定义即可，无需修改核心错误处理逻辑。

对于正在将现有系统迁移到Effect-TS的团队，这种Schema优先的错误处理方式尤其有价值，它允许渐进式地引入Effect模式，同时保持与现有系统的兼容性。