第 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 基础框架的搭建：
- 项目结构：使用 Vibe Coding 创建了清晰的模块化项目结构
- FastAPI 应用：创建了基础的 FastAPI 应用，配置了 CORS 和中间件
- 路由设计：实现了健康检查接口，为后续功能奠定基础
- 环境配置：使用 .env 文件管理配置，支持不同环境
- 依赖管理：创建了 requirements.txt，明确项目依赖
- 测试验证：通过多种方式验证应用正常运行
- API 文档：FastAPI 自动生成交互式文档
现在我们有了一个可运行的 FastAPI 基础框架，可以在此基础上添加更多功能。
思考与练习
思考题
- 为什么要使用模块化的项目结构？如果所有代码都写在 main.py 会有什么问题？
- CORS 配置中的
allow_origins为什么不建议设置为["*"]？ - 健康检查接口在生产环境中有什么作用？
- FastAPI 的自动文档生成是如何实现的？
实践练习
-
扩展项目结构：
- 添加
models/目录用于数据模型 - 添加
utils/目录用于工具函数 - 添加
tests/目录用于测试代码
- 添加
-
添加新路由：
- 创建一个
/api/info接口 - 返回项目名称、版本、作者等信息
- 使用 Pydantic 模型定义响应格式
- 创建一个
-
环境配置优化：
- 使用 pydantic-settings 管理配置
- 支持从环境变量读取配置
- 添加配置验证
-
中间件实践：
- 添加请求日志中间件
- 记录每个请求的耗时
- 添加请求 ID 追踪
上一节：第 6 节：技术架构与设计思路
下一节：第 8 节：集成 CubeJS 数据模型
