在Next.js中结合openapi-typescript和React Query的最佳实践

背景介绍

在现代前端开发中，Next.js、TypeScript和状态管理库的组合已经成为主流技术栈。openapi-typescript项目提供了一个强大的工具链，能够根据OpenAPI规范自动生成TypeScript类型定义，而openapi-fetch则是基于这些类型定义提供类型安全的API请求客户端。

问题分析

在Next.js应用中使用openapi-fetch与React Query结合时，开发者可能会遇到一个常见错误："Invariant: headers() expects to have requestAsyncStorage, none available"。这个错误通常发生在以下场景：

1. 在客户端组件中直接使用openapi-fetch客户端
2. 中间件中调用了仅服务器端可用的API（如Next.js的headers()）
3. 环境变量未正确配置为客户端可用

解决方案

服务器端执行API请求

最可靠的解决方案是将API请求逻辑完全放在服务器端执行，然后通过React Query在客户端进行状态管理。这种模式有以下几个优势：

1. 安全性：敏感逻辑和认证信息保留在服务器端
2. 性能：可以利用Next.js的缓存机制
3. 稳定性：避免客户端环境差异导致的问题

实现方式如下：

// 服务器端action
"use server";

export async function getConfigProperties() {
  const { data, error } = await client.GET("/api/settings/config-properties");
  return { data, error };
}

// 客户端组件
"use client";

const { data } = useQuery({
  queryKey: ["getConfigProperties"],
  queryFn: async () => {
    const { data, error } = await getConfigProperties();
    if (error) throw new Error(error.message);
    return data;
  },
});

错误处理策略

在服务器端返回原始错误信息，在客户端进行错误处理和展示，这种分层处理方式有以下好处：

1. 服务器端可以保持简洁的错误日志
2. 客户端可以根据业务需求定制错误展示
3. 符合Next.js推荐的安全实践

架构考量

在选择解决方案时，需要考虑以下架构因素：

1. 网络拓扑：直接客户端请求还是通过Next.js代理
2. 认证机制：如何安全地传递认证令牌
3. 性能影响：额外的网络跳转对用户体验的影响
4. 开发体验：如何保持类型安全的同时简化开发流程

最佳实践建议

1. 对于需要认证的API请求，优先使用服务器端执行
2. 将环境变量前缀设置为NEXT_PUBLIC_以在客户端使用
3. 使用TypeScript严格模式确保类型安全
4. 考虑使用Next.js的Route Handlers作为API代理层
5. 实现统一的错误处理中间件

总结

在Next.js应用中结合openapi-typescript和React Query时，理解服务器端和客户端执行的边界至关重要。通过将API请求逻辑放在服务器端action中，可以避免常见的环境相关问题，同时保持类型安全和良好的开发体验。这种架构模式特别适合需要认证、敏感数据处理或复杂业务逻辑的应用场景。