新留园

首页
首页 信息技术 码工码农

第 7 节：搭建 FastAPI 基础框架

小新 正七品 (知县) 2026-03-17 03:55 1 0 返回 码工码农
小
小新 正七品 (知县) 楼主
2026-03-17 03:55
第1楼

摘要：第 7 节：搭建 FastAPI 基础框架

阅读时间：约 7 分钟 难度级别：实战 前置知识：Python 基础、HTTP 协议基础

本节概要 通过本节学习，你将掌握：

使用 Vibe Coding 设计和创建项目结构 FastAPI 应用的基础配置和启动 CORS 跨域配置的正确方法 创建健康检查和基础路由 自动生成 API 文档的使用 项目的测试和验证方法

引言 从本节开始，我们将进入实战环节。txt

Step 2: 创建主应用文件 与 AI 对话： 创建 main.CubeJS 配置 CUBEJS_URL=http://localhost:4000

应用配置

APP_ENV=development LOG_LEVEL=INFO

.

第 7 节：搭建 FastAPI 基础框架

阅读时间：约 7 分钟
难度级别：实战
前置知识：Python 基础、HTTP 协议基础

本节概要

通过本节学习，你将掌握：

  • 使用 Vibe Coding 设计和创建项目结构
  • FastAPI 应用的基础配置和启动
  • CORS 跨域配置的正确方法
  • 创建健康检查和基础路由
  • 自动生成 API 文档的使用
  • 项目的测试和验证方法

引言

从本节开始，我们将进入实战环节。首先从搭建 FastAPI 基础框架开始，这是整个后端系统的基石。我们将使用 Vibe Coding 的方式，通过与 AI 对话来快速搭建项目结构。

🎯 本章目标

完成后，你将拥有：

  • ✅ 一个可运行的 FastAPI 应用
  • ✅ 完整的项目结构
  • ✅ CORS 配置
  • ✅ 基础的健康检查接口
  • ✅ 自动生成的 API 文档

📁 项目结构设计

使用 Vibe Coding 创建结构

与 AI 的对话：

我要创建一个 FastAPI 项目，用于构建 Text-to-BI 系统。

项目结构需求：
- backend/ 作为后端根目录
- 使用模块化设计，分离路由、服务、Agent
- 支持环境变量配置
- 包含依赖管理文件

请帮我设计项目结构并创建必要的文件。

AI 生成的结构：

backend/
├── main.py                 # FastAPI 主应用
├── requirements.txt        # Python 依赖
├── .env                    # 环境变量
├── .env.example           # 环境变量示例
├── .gitignore             # Git 忽略文件
├── start.sh               # 启动脚本
├── routers/               # API 路由
│   ├── __init__.py
│   ├── chat.py           # 聊天路由
│   └── workflow.py       # Workflow 路由
├── agents/                # AI Agent
│   ├── __init__.py
│   └── cubejs_agent.py
├── services/              # 外部服务
│   ├── __init__.py
│   └── cubejs_service.py
├── workflows/             # Workflow 定义
│   ├── __init__.py
│   └── text_to_bi.py
└── tmp/                   # 临时文件
    └── workflows.db       # Workflow 存储

🚀 创建主应用

Step 1: 安装依赖

与 AI 对话：

创建 requirements.txt，包含以下依赖：
- FastAPI：Web 框架
- Uvicorn：ASGI 服务器
- Agno：AI Agent 框架
- Python-dotenv：环境变量管理
- Requests：HTTP 客户端
- PyYAML：YAML 解析

请列出具体的版本号。

生成的 requirements.txt：

# Web 框架
fastapi==0.109.0
uvicorn[standard]==0.27.0

# AI Agent 框架
agno==0.1.0

# 工具库
python-dotenv==1.0.0
requests==2.31.0
pyyaml==6.0.1

# 数据库
sqlalchemy==2.0.25

安装依赖：

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

Step 2: 创建主应用文件

与 AI 对话：

创建 main.py，要求：
1. 创建 FastAPI 应用实例
2. 配置 CORS，允许前端访问
3. 添加根路径和健康检查接口
4. 包含 API 文档配置
5. 添加启动代码

前端运行在 http://localhost:5173

生成的 main.py：

"""
Ask SQL Backend - 主应用
整合了基础聊天和 Text-to-BI Workflow 功能的 FastAPI 应用
"""
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

# 创建 FastAPI 应用实例
app = FastAPI(
    title="Ask SQL API",
    description="Natural language to SQL with Agno Workflow and AI Chat",
    version="1.0.0",
    docs_url="/docs",
    redoc_url="/redoc",
)

# 配置 CORS 中间件
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:5173",
        "http://127.0.0.1:5173",
        "http://localhost:3000",
        "http://127.0.0.1:3000",
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)


@app.get("/")
def read_root():
    """
    根路径 - 健康检查和 API 信息
    """
    return {
        "status": "ok",
        "service": "Ask SQL API",
        "version": "1.0.0",
        "endpoints": {
            "docs": "/docs",
            "redoc": "/redoc",
        }
    }


@app.get("/health")
def health_check():
    """
    健康检查端点
    """
    return {
        "status": "healthy",
        "service": "ask-sql-backend"
    }


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        reload=True
    )

Step 3: 测试基础应用

启动服务：

python main.py

测试接口：

# 测试根路径
curl http://localhost:8000/

# 测试健康检查
curl http://localhost:8000/health

# 访问 API 文档
open http://localhost:8000/docs

预期输出：

{
  "status": "ok",
  "service": "Ask SQL API",
  "version": "1.0.0",
  "endpoints": {
    "docs": "/docs",
    "redoc": "/redoc"
  }
}

🔧 配置环境变量

Step 1: 创建环境变量文件

与 AI 对话：

创建 .env.example 文件，包含：
- OpenAI API Key（用于 AI 模型）
- CubeJS URL
- 其他必要的配置

同时创建 .gitignore，确保 .env 不被提交。

.env.example：

# AI 模型配置
OPENAI_API_KEY=your_api_key_here

# CubeJS 配置
CUBEJS_URL=http://localhost:4000

# 应用配置
APP_ENV=development
LOG_LEVEL=INFO

.gitignore：

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
venv/
env/

# 环境变量
.env

# 数据库
*.db
*.sqlite

# IDE
.vscode/
.idea/
*.swp
*.swo

# 临时文件
tmp/
*.log

Step 2: 加载环境变量

修改 main.py：

from dotenv import load_dotenv
import os

# 加载环境变量
load_dotenv()

# 创建 FastAPI 应用
app = FastAPI(
    title="Ask SQL API",
    description="Natural language to SQL with Agno Workflow and AI Chat",
    version="1.0.0",
)

# 验证必要的环境变量
required_env_vars = ["OPENAI_API_KEY"]
missing_vars = [var for var in required_env_vars if not os.getenv(var)]

if missing_vars:
    raise ValueError(f"缺少必要的环境变量: {', '.join(missing_vars)}")

📝 创建路由模块

Step 1: 创建基础聊天路由

与 AI 对话：

在 routers/chat.py 中创建一个基础的聊天接口：
- POST /chat/ask
- 接收 message 参数
- 返回简单的响应
- 使用 Pydantic 模型验证输入

routers/chat.py：

"""
聊天路由 - 基础 AI 聊天功能
"""
from fastapi import APIRouter
from pydantic import BaseModel

router = APIRouter(
    prefix="/chat",
    tags=["chat"]
)


class ChatRequest(BaseModel):
    """聊天请求模型"""
    message: str


class ChatResponse(BaseModel):
    """聊天响应模型"""
    response: str


@router.post("/ask", response_model=ChatResponse)
async def ask(request: ChatRequest):
    """
    基础聊天接口

    Args:
        request: 包含用户消息的请求

    Returns:
        AI 的响应
    """
    # 暂时返回简单响应
    return ChatResponse(
        response=f"收到消息: {request.message}"
    )

Step 2: 注册路由

修改 main.py：

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from dotenv import load_dotenv

# 导入路由
from routers import chat

load_dotenv()

app = FastAPI(
    title="Ask SQL API",
    description="Natural language to SQL with Agno Workflow and AI Chat",
    version="1.0.0",
)

# 配置 CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:5173",
        "http://127.0.0.1:5173",
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 注册路由
app.include_router(chat.router)

@app.get("/")
def read_root():
    return {
        "status": "ok",
        "service": "Ask SQL API",
        "version": "1.0.0",
        "endpoints": {
            "docs": "/docs",
            "chat": {
                "ask": "POST /chat/ask - 基础 AI 聊天"
            }
        }
    }

Step 3: 测试聊天接口

# 测试聊天接口
curl -X POST "http://localhost:8000/chat/ask" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

预期输出：

{
  "response": "收到消息: Hello"
}

🎨 创建启动脚本

与 AI 对话：

创建 start.sh 启动脚本，包含：
1. 激活虚拟环境
2. 检查环境变量
3. 启动 uvicorn 服务器
4. 支持热重载

start.sh：

#!/bin/bash

# 颜色定义
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m' # No Color

echo -e "${GREEN}=== Ask SQL Backend 启动脚本 ===${NC}\n"

# 检查虚拟环境
if [ ! -d "venv" ]; then
    echo -e "${RED}错误: 虚拟环境不存在${NC}"
    echo "请先运行: python -m venv venv"
    exit 1
fi

# 激活虚拟环境
echo -e "${YELLOW}激活虚拟环境...${NC}"
source venv/bin/activate

# 检查 .env 文件
if [ ! -f ".env" ]; then
    echo -e "${YELLOW}警告: .env 文件不存在${NC}"
    echo "请复制 .env.example 并配置必要的环境变量"
    echo "cp .env.example .env"
    exit 1
fi

# 检查依赖
echo -e "${YELLOW}检查依赖...${NC}"
pip list | grep fastapi > /dev/null
if [ $? -ne 0 ]; then
    echo -e "${YELLOW}安装依赖...${NC}"
    pip install -r requirements.txt
fi

# 启动服务器
echo -e "${GREEN}启动 FastAPI 服务器...${NC}"
echo -e "访问 API 文档: ${GREEN}http://localhost:8000/docs${NC}\n"

uvicorn main:app --reload --host 0.0.0.0 --port 8000

使脚本可执行：

chmod +x start.sh

使用脚本启动：

./start.sh

📚 API 文档

FastAPI 自动生成交互式 API 文档：

Swagger UI

访问 http://localhost:8000/docs

特点：

  • 📝 交互式测试
  • 🎯 请求/响应示例
  • 🔍 模型定义
  • ✅ 参数验证

ReDoc

访问 http://localhost:8000/redoc

特点：

  • 📖 更适合阅读
  • 🎨 美观的布局
  • 📊 清晰的结构

🧪 测试清单

完成基础框架后，确保以下功能正常：

  • 服务器可以启动
  • 根路径返回正确信息
  • 健康检查接口正常
  • CORS 配置生效
  • 聊天接口可以调用
  • API 文档可以访问
  • 环境变量正确加载

🎯 Vibe Coding 要点

在这个过程中，我们应用了以下 Vibe Coding 原则：

1. 清晰的需求描述

❌ "创建一个 FastAPI 应用"
✅ "创建一个 FastAPI 应用，包含 CORS 配置、健康检查接口和 API 文档"

2. 小步迭代

步骤1: 创建基础应用
步骤2: 添加环境变量
步骤3: 创建路由模块
步骤4: 测试验证

3. 及时验证

每完成一个步骤，立即测试：

# 创建应用后
curl http://localhost:8000/

# 添加路由后
curl -X POST http://localhost:8000/chat/ask -d '{"message": "test"}'

4. 保持上下文

在与 AI 对话时，提供项目背景：

"我正在开发一个 Text-to-BI 系统，使用 FastAPI 作为后端框架..."

本节小结

本节我们完成了 FastAPI 基础框架的搭建：

  1. 项目结构：使用 Vibe Coding 创建了清晰的模块化项目结构
  2. FastAPI 应用：创建了基础的 FastAPI 应用，配置了 CORS 和中间件
  3. 路由设计：实现了健康检查接口，为后续功能奠定基础
  4. 环境配置：使用 .env 文件管理配置，支持不同环境
  5. 依赖管理：创建了 requirements.txt，明确项目依赖
  6. 测试验证：通过多种方式验证应用正常运行
  7. API 文档：FastAPI 自动生成交互式文档

现在我们有了一个可运行的 FastAPI 基础框架，可以在此基础上添加更多功能。

思考与练习

思考题

  1. 为什么要使用模块化的项目结构？如果所有代码都写在 main.py 会有什么问题？
  2. CORS 配置中的 allow_origins 为什么不建议设置为 ["*"]？
  3. 健康检查接口在生产环境中有什么作用？
  4. FastAPI 的自动文档生成是如何实现的？

实践练习

  1. 扩展项目结构：

    • 添加 models/ 目录用于数据模型
    • 添加 utils/ 目录用于工具函数
    • 添加 tests/ 目录用于测试代码

  2. 添加新路由：

    • 创建一个 /api/info 接口
    • 返回项目名称、版本、作者等信息
    • 使用 Pydantic 模型定义响应格式

  3. 环境配置优化：

    • 使用 pydantic-settings 管理配置
    • 支持从环境变量读取配置
    • 添加配置验证

  4. 中间件实践：

    • 添加请求日志中间件
    • 记录每个请求的耗时
    • 添加请求 ID 追踪

上一节：第 6 节：技术架构与设计思路
下一节：第 8 节：集成 CubeJS 数据模型

分享

暂无回复，快来抢沙发吧！

  • 1 / 1 页
上一篇在vscode copilot里使用IDA mcp
返回码工码农
下一篇 SWE-bench 都 80% 了，AI 真能修 Bug？我拿 3 个真实场景测了 5 个
敬请注意：文中内容观点和各种评论不代表本网立场！若有违规侵权，请联系我们。
登录后参与讨论