在现代 Web 开发中，前后端分离已成为标准做法。这种架构允许前端和后端独立开发和扩展，但同时也带来了如何高效交互的问题。FastAPI，作为一个新兴的 Python Web 框架，提供了一个优雅的解决方案：自动生成客户端代码。本文将介绍如何利用 FastAPI 的这一功能，为你的前端应用生成 TypeScript 客户端代码。
1. OpenAPI 规范
FastAPI 遵循 OpenAPI 规范，这意味着它可以生成易于理解和使用的 API 文档，同时也支持自动生成客户端代码。
2. 为什么需要自动生成客户端代码？
自动生成的客户端代码可以减少手动编写和维护 API 交互代码的工作量，同时提供类型安全和错误提示，提高开发效率和代码质量。
3. openapi-ts：TypeScript 的 OpenAPI 客户端生成器
openapi-ts 是一个工具，它可以从 OpenAPI 规范生成 TypeScript 客户端代码，非常适合前端开发。
要自动化生成前端应用的 API 客户端代码，你可以使用 openapi-ts 工具，这是一个基于 OpenAPI 规范的 TypeScript 客户端生成器。以下是使用 openapi-ts 自动生成客户端代码的步骤：
步骤 1: 准备你的 FastAPI 应用
首先，确保你的 FastAPI 应用已经定义了遵循 OpenAPI 规范的 API。例如：
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str = None
price: float
tax: float = None
@app.post("/items/")
async def create_item(item: Item):
return {"name": item.name, "price": item.price}
@app.get("/items/")
async def read_items():
return [{"name": "Item1", "price": 10.5}, {"name": "Item2", "price": 20.0}]
步骤 2: 安装 openapi-ts
在你的前端项目中，安装 openapi-ts：
npm install @hey-api/openapi-ts typescript --save-dev
步骤 3: 添加生成脚本到 package.json
在你的前端项目的 package.json 文件中，添加一个脚本来生成客户端代码：
{
"scripts": {
"generate-client": "openapi-ts --input http://localhost:8000/openapi.json --output ./src/api/client --client axios"
},
"devDependencies": {
"@hey-api/openapi-ts": "^0.27.38",
"typescript": "^4.6.2"
}
}
这里假设你的 FastAPI 应用运行在 localhost 的 8000 端口，并且 OpenAPI 文档可以通过 /openapi.json 访问。
步骤 4: 运行生成脚本
在终端中运行以下命令来生成客户端代码：
npm run generate-client
这将生成客户端代码到 ./src/api/client 目录。
步骤 5: 使用生成的客户端代码
在你的前端应用中，你现在可以使用生成的客户端代码来与后端 API 交互。例如：
import { createItem, readItems } from './api/client';
async function addNewItem(item: any) {
try {
const response = await createItem({ item });
console.log(response);
} catch (error) {
console.error('Error creating item:', error);
}
}
async function getAllItems() {
try {
const items = await readItems();
console.log(items);
} catch (error) {
console.error('Error fetching items:', error);
}
}
// 示例调用
addNewItem({ name: 'New Item', price: 15.0 });
getAllItems();
4. 探索生成的客户端代码
查看 openapi-ts 生成的客户端代码，了解其结构和功能，包括服务文件和模型文件。
使用 openapi-ts 生成的 ./src/api/client 目录将包含根据你的 FastAPI 应用的 OpenAPI 规范自动生成的 TypeScript 客户端代码。具体的文件结构和内容会根据你的 API 设计和 openapi-ts 的配置有所不同，但通常你可能会看到以下类型的文件：
4-1. 服务文件（Service Files）
这些文件包含了与特定 API 端点交互的方法。例如，如果你有一个创建项目的端点和一个获取项目列表的端点，你可能会有类似以下的文件：
// Generated by openapi-ts
export class ItemsService {
async createItem(body: { name: string; price: number; description?: string | null; tax?: number | null }): Promise<{ name: string; price: number }> {
const response = await axios.post<{ name: string; price: number }>('http://localhost:8000/items/', body);
return response.data;
}
async getItems(): Promise<{ name: string; price: number }[]> {
const response = await axios.get<{ name: string; price: number }[]>('http://localhost:8000/items/');
return response.data;
}
}
4-2. 模型文件（Model Files）
这些文件定义了请求和响应的数据模型，基于你的 Pydantic 模型或其他类型定义。例如：
// Generated by openapi-ts
export interface Item {
name: string;
description?: string | null;
price: number;
tax?: number | null;
}
export interface CreateItemResponse {
name: string;
price: number;
}
export interface GetItemsResponse {
items: Item[];
}
4-3. 索引文件（Index File）
这个文件通常用于集中导出所有服务和模型，方便在应用的其他部分导入使用：
// Generated by openapi-ts
export * from './ItemsService';
export * from './models';
4-4. 配置文件（Config File）
如果有必要，可能会有一个配置文件，用于定义客户端的一些配置，如基础 URL、请求头等。
4-5. 辅助工具文件（Utility Files）
有时，生成的代码可能包括一些辅助工具函数或类型，用于支持客户端的功能。
示例代码结构
./src/api/client
|-- index.ts
|-- ItemsService.ts
|-- models.ts
代码示例
-
ItemsService.ts:
import { axios } from 'axios'; export class ItemsService { async createItem(body: { name: string; price: number; description?: string | null; tax?: number | null }) { const response = await axios.post<{ name: string; price: number }>('http://localhost:8000/items/', body); return response.data; } async getItems() { const response = await axios.get<{ name: string; price: number }[]>('http://localhost:8000/items/'); return response.data; } } -
models.ts:
export interface Item { name: string; description?: string | null; price: number; tax?: number | null; } -
index.ts:
export * from './ItemsService'; export * from './models';
这些文件提供了一个类型安全的方式来与后端 API 进行交互，减少了手动编写和维护 API 客户端代码的工作量。
5. 在前端应用中使用客户端代码
将生成的客户端代码集成到你的前端应用中，开始与后端 API 进行交互。
结语
FastAPI 的自动客户端代码生成功能，为前后端分离的开发模式提供了一个强大的工具。通过 openapi-ts，你可以轻松地为你的 TypeScript 前端应用生成类型安全的 API 客户端代码，提高开发效率，减少错误。这是一个值得探索和利用的功能，尤其是在快速迭代和维护大型项目时。
本文介绍了如何利用 FastAPI 和 openapi-ts 自动生成 TypeScript 客户端代码，帮助你的前端应用与后端 API 高效交互。通过自动化这个过程，你可以节省时间，减少错误，并提高代码质量。
