使用Hey API的OpenAPI-TS为Next.js项目生成类型安全客户端

前言

在现代Web开发中，类型安全和API调用的便捷性是两个非常重要的考量因素。Hey API的openapi-ts项目为Next.js开发者提供了一个优雅的解决方案，能够自动生成类型安全的API客户端，大幅提升开发效率和代码质量。

核心特性

openapi-ts的Next.js客户端具有以下显著优势：

1. 无缝集成：与openapi-ts生态系统完美融合
2. 类型安全：自动生成的类型定义确保API调用时的类型安全
3. 数据验证：内置响应数据验证和转换功能
4. 请求控制：提供原始请求和响应访问能力
5. 高度可定制：支持请求和响应的细粒度定制
6. 学习成本低：基于Fetch API扩展，开发者可以快速上手
7. 打包支持：支持在生成输出中打包客户端代码

安装与配置

基本安装

在项目配置文件中添加@hey-api/client-next插件即可开始生成客户端代码：

// 配置文件示例
export default {
  input: 'https://api.example.com/spec',
  output: 'src/client',
  plugins: ['@hey-api/client-next'],
};

或者使用CLI命令：

npx @hey-api/openapi-ts \
  -i https://api.example.com/spec \
  -o src/client \
  -c @hey-api/client-next

配置方式

openapi-ts提供了多种客户端配置方式，适应不同场景需求：

1. 运行时API配置（推荐）
   • 创建自定义配置文件并导出createClientConfig方法
   • 这种方式确保客户端在服务端和客户端环境都能正确初始化

// src/hey-api.ts
import type { CreateClientConfig } from './client/client.gen';

export const createClientConfig: CreateClientConfig = (config) => ({
  ...config,
  baseUrl: 'https://example.com',
});

2. setConfig方法
   • 简单直接，适合快速配置
   • 需注意调用时机，避免在配置前使用客户端

import { client } from 'client/client.gen';

client.setConfig({
  baseUrl: 'https://example.com',
});

3. createClient方法
   • 创建独立客户端实例
   • 适合需要连接多个API端点的场景

import { createClient } from './client/client';

const myClient = createClient({
  baseUrl: 'https://example.com',
});

高级功能

拦截器机制

openapi-ts提供了强大的拦截器系统，可以在请求发送前和响应返回后进行拦截处理：

// 请求拦截器示例
const interceptorId = client.interceptors.request.use(async (request) => {
  // 添加认证头
  request.headers.set('Authorization', 'Bearer token');
  return request;
});

// 响应拦截器示例
client.interceptors.response.use(async (response) => {
  // 统一处理错误
  if (!response.ok) {
    throw new Error('API请求失败');
  }
  return response;
});

拦截器支持动态添加、更新和移除，为API调用提供了极大的灵活性。

认证集成

openapi-ts支持多种认证方式：

1. 全局认证配置

client.setConfig({
  auth: () => localStorage.getItem('token'),
});

2. 拦截器认证

client.interceptors.request.use((request) => {
  request.headers.set('Authorization', `Bearer ${token}`);
  return request;
});

3. 单次请求认证

const response = await getData({
  auth: 'special-token'
});

URL构建工具

客户端提供了buildUrl方法，帮助构建类型安全的API URL：

const url = client.buildUrl<{
  path: { userId: number };
  query: { page?: number };
  url: '/users/{userId}';
}>({
  path: { userId: 123 },
  query: { page: 2 },
  url: '/users/{userId}',
});
// 输出: '/users/123?page=2'

最佳实践

1. 服务端组件使用：在Next.js服务端组件中，建议使用运行时API配置方式
2. 错误处理：利用拦截器统一处理API错误
3. 类型扩展：通过泛型参数扩展自动生成的类型定义
4. 性能优化：对于高频API，考虑创建专用客户端实例
5. 测试策略：利用拦截器mock API响应进行组件测试

结语

Hey API的openapi-ts为Next.js项目提供了强大的类型安全API客户端解决方案。通过自动生成的客户端代码，开发者可以专注于业务逻辑而不用操心API调用的底层细节。其灵活的配置方式和丰富的功能特性，使得它能够适应各种复杂的应用场景。

虽然目前Next.js客户端仍处于测试阶段，但其设计理念和功能实现已经展现出极高的实用价值。对于追求开发效率和代码质量的团队来说，这无疑是一个值得尝试的工具。