深入理解@hey-api/client-fetch中的客户端管理机制

背景介绍

在现代Web开发中，前后端分离架构已成为主流。@hey-api/client-fetch作为一个强大的OpenAPI客户端生成工具，能够根据后端API定义自动生成类型安全的客户端代码。然而，在实际应用中，特别是在服务端渲染(SSR)场景下，客户端实例的管理方式可能会带来一些挑战。

核心问题分析

在@hey-api/client-fetch的默认实现中，服务函数接收一个包含可选client属性的options参数。当不显式传递client时，系统会使用services.gen.ts中定义的默认客户端实例。这种设计在浏览器端运行良好，因为每个用户都有自己的浏览器环境，客户端实例自然隔离。

但在服务端场景下，特别是需要处理多用户请求时，这种单例模式会带来问题：

1. 不同用户共享同一个客户端实例
2. 认证信息(如access token)可能被错误地跨用户共享
3. 可能导致安全问题和功能异常

解决方案演进

项目维护者针对这一问题提供了两种解决方案：

1. 配置禁用默认客户端

最新版本中，可以通过设置sdk.client为false来禁用默认客户端生成。这样所有服务调用都必须显式提供客户端实例，强制开发者正确处理每个请求的客户端隔离。

2. Next.js专用客户端

针对Next.js应用场景，项目计划提供专门的客户端实现，这将更好地处理服务端渲染环境下的客户端管理问题。虽然目前优先级不高，但这是未来的发展方向。

最佳实践建议

对于需要在服务端使用@hey-api/client-fetch的开发者，建议：

1. 升级到最新版本，利用sdk.client = false配置
2. 为每个用户请求创建独立的客户端实例
3. 在中间件层统一处理客户端创建和配置
4. 避免在全局作用域存储任何与用户相关的客户端状态

技术实现细节

在底层实现上，这个功能是通过修改代码生成逻辑实现的。当禁用默认客户端时：

1. services.gen.ts不再包含默认客户端导出
2. 所有生成的服务函数类型定义将client标记为必需属性
3. 调用时必须显式提供配置好的客户端实例

这种设计既保持了API的简洁性，又解决了服务端环境下的隔离问题。

总结

@hey-api/client-fetch通过灵活的客户端管理机制，既支持简单的浏览器端使用场景，也能满足复杂的服务端多用户隔离需求。理解这一机制对于构建安全、可靠的Web应用至关重要，特别是在全栈应用和服务器渲染场景下。随着框架的不断发展，未来还会提供更多针对特定环境的优化解决方案。