API 开发流程

1. 定义数据模型

在 app/models/schema.py 中定义数据模型

from pydantic import BaseModel

class MyRequest(BaseModel):
    param1: str
    param2: int

class MyResponse(BaseModel):
    success: bool
    data: dict

2. 创建 API 路由

在 app/api/ 对应模块中创建路由

from fastapi import APIRouter
from app.models.schema import MyRequest, MyResponse

router = APIRouter()

@router.post("/my-endpoint", response_model=MyResponse)
async def my_endpoint(request: MyRequest):
    # 业务逻辑
    return MyResponse(success=True, data={})

3. 生成前端代码

1. 启动后端

python main.py

2. 使用 openapi-generator-typescript 生成前端代码

cd frontend
yarn openapi

如果没有输出，代表已经生成完成了；如果报错了，请自行查阅报错内容。

注意

frontend/src/api 由 OpenAPI 生成器维护。后端 schema 或 API 契约变更后，只能重新生成该目录，不要为了修类型或接口手动修改生成文件。

注意

当你阅读至此，说明你正在开发一个新的 API，请你牢记，你直接使用 yarn dev 时，后端实际上使用的是 GitHub 上 dev 分支中的后端代码，而非你当前开发的后端。

因此，为了在前端测试你的 API，你必须先在本地启动后端，再运行前端，您可以参考 使用来自本地的后端。

4. 在前端调用 API

前端业务代码不要在页面组件中直接散落调用生成的 Service.ts。应先在 frontend/src/composables 中封装面向业务的 composable，再由页面或组件调用该 composable。

生成的 frontend/src/api/services/Service.ts 只作为底层 API 客户端使用：

import { Service } from '@/api';

export function useMyApi() {
    const submitMyRequest = async (param1: string, param2: number) => {
        return Service.myEndpoint({
            param1,
            param2,
        });
    };

    return {
        submitMyRequest,
    };
}

页面组件只负责组织交互、加载态、错误提示和数据展示；API 参数整理、响应兼容处理和复用逻辑放在 composable 中。