FastAPI 项目实战：如何自动生成前端客户端代码

最新推荐文章于 2025-06-08 00:00:00 发布

孟元毓Pandora

最新推荐文章于 2025-06-08 00:00:00 发布

阅读量382

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00540/article/details/148323450

FastAPI 项目实战：如何自动生成前端客户端代码

fastapi FastAPI framework, high performance, easy to learn, fast to code, ready for production 项目地址: https://gitcode.com/gh_mirrors/fa/fastapi

前言

在现代Web开发中，前后端分离架构已成为主流。作为后端开发者，我们经常需要为前端团队提供API文档和客户端SDK。FastAPI基于OpenAPI规范，为我们提供了自动生成客户端代码的能力，这可以显著提高前后端协作效率。

为什么需要自动生成客户端代码

提高开发效率：前端可以直接调用生成的客户端方法，无需手动编写API调用代码
保证类型安全：生成的客户端代码会包含完整的类型定义
减少沟通成本：前后端通过API规范自动同步，减少人为错误
快速响应变更：API变更时，只需重新生成客户端代码即可

FastAPI 客户端生成原理

FastAPI会自动生成OpenAPI规范文档，这是生成客户端代码的基础。OpenAPI规范包含了：

所有API端点信息
请求/响应模型定义
参数类型和验证规则
接口分组信息

实战：生成TypeScript前端客户端

1. 准备FastAPI应用

首先，我们需要一个简单的FastAPI应用作为示例：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

class ResponseMessage(BaseModel):
    message: str

@app.post("/items/")
async def create_item(item: Item) -> ResponseMessage:
    return {"message": f"Item {item.name} created"}

2. 安装客户端生成工具

推荐使用openapi-ts工具生成TypeScript客户端：

npm install @hey-api/openapi-ts --save-dev

3. 配置生成脚本

在package.json中添加生成脚本：

{
  "scripts": {
    "generate-client": "openapi-ts --input http://localhost:8000/openapi.json --output ./src/client --client axios"
  }
}

4. 生成客户端代码

运行生成命令：

npm run generate-client

5. 使用生成的客户端

生成的客户端代码可以直接导入使用：

import { ItemsService } from './client';

const response = await ItemsService.createItem({ name: "Plumbus", price: 5 });

高级技巧：优化客户端方法名

默认生成的方法名可能不够友好，我们可以通过自定义操作ID来优化：

1. 自定义生成唯一ID函数

def generate_unique_id(route: APIRoute):
    return f"{route.tags[0]}-{route.name}"

app = FastAPI(generate_unique_id_function=generate_unique_id)

2. 预处理OpenAPI规范

生成后可以进一步处理operationId：

const fs = require('fs');

const spec = JSON.parse(fs.readFileSync('openapi.json'));
for (const path in spec.paths) {
    for (const method in spec.paths[path]) {
        const operation = spec.paths[path][method];
        if (operation.operationId.includes('-')) {
            operation.operationId = operation.operationId.split('-')[1];
        }
    }
}
fs.writeFileSync('openapi.json', JSON.stringify(spec));