概述

FastAPI 是一个现代、高性能的 Python Web 框架，基于标准 Python 类型提示构建。它能够自动生成 OpenAPI 文档，具备自动数据验证和序列化能力，开发体验极佳。

为什么选择 FastAPI？

• 自动文档：自动生成 Swagger UI 和 ReDoc 交互式文档
• 高性能：基于 Starlette 和 Pydantic，性能媲美 Node.js 和 Go
• 类型安全：利用 Python 类型提示进行自动验证和文档生成
• 异步支持：原生支持 async/await，适合高并发场景

技术特性

特性	说明
编程语言	Python 3.11+
架构模式	路由 + 依赖注入
ORM 支持	SQLAlchemy, Tortoise ORM
数据库	PostgreSQL, MySQL, SQLite
性能评分	★★★★★
学习曲线	低（有 Python 基础即可）
API 文档	Swagger / ReDoc 自动生成
测试支持	pytest

生成的项目结构

ThesisAI 生成的 FastAPI 项目遵循清晰的分层架构：

backend/
├── main.py                    # 入口文件
├── requirements.txt           # 依赖列表
├── app/
│   ├── __init__.py
│   ├── api/                   # API 路由
│   │   ├── __init__.py
│   │   ├── routes/            # 路由定义
│   │   └── deps.py            # 依赖注入
│   ├── core/                  # 核心配置
│   │   ├── config.py          # 应用配置
│   │   └── security.py        # 安全相关
│   ├── models/                # 数据库模型
│   ├── schemas/               # Pydantic 数据模型
│   ├── crud/                  # CRUD 操作
│   └── db/                    # 数据库配置
├── alembic/                   # 数据库迁移（可选）
│   └── versions/
├── tests/                     # 测试文件
├── .env.example               # 环境变量示例
└── Dockerfile

开发环境

环境要求

依赖	版本要求	说明
Python	>= 3.11	推荐 3.11+
pip	最新版	包管理器

创建虚拟环境

macOS / Linux：

cd backend
python3 -m venv venv
source venv/bin/activate

Windows：

cd backend
python -m venv venv
venv\Scripts\activate

关于虚拟环境

虚拟环境可以隔离项目依赖，避免不同项目之间的冲突。每次运行项目前都需要激活虚拟环境。

安装依赖

pip install -r requirements.txt

使用国内镜像加速：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

pip 镜像配置

如需永久使用国内镜像，可执行以下命令：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

环境变量

cp .env.example .env

变量名	说明	必填	默认值
DATABASE_URL	数据库连接字符串	是	-
SECRET_KEY	应用密钥	是	-
DEBUG	调试模式	否	True
CORS_ORIGINS	允许的跨域来源	否	http://localhost:5173

数据库迁移（如使用 Alembic）

alembic upgrade head

启动开发服务器

uvicorn main:app --reload

指定端口：

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

--reload 参数

--reload 参数启用热重载，代码修改后会自动重启服务器，开发时非常方便。

:::success 服务启动成功

• API 地址: http://localhost:8000
• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

如果看到 Uvicorn running on http://127.0.0.1:8000 的消息，说明服务启动成功！访问 /docs 可以看到自动生成的 API 文档，这是 FastAPI 的特色功能。 :::

自动生成的 API 文档

FastAPI 会自动根据代码生成两种交互式文档：

• Swagger UI（/docs）- 可交互的 API 测试界面，直接在浏览器中测试接口
• ReDoc（/redoc）- 更美观的 API 文档，适合阅读和分享

常用命令

命令	说明
uvicorn main:app --reload	开发模式启动（热重载）
uvicorn main:app --workers 4	生产模式（多进程）
alembic revision --autogenerate -m "msg"	创建数据库迁移
alembic upgrade head	执行数据库迁移
pytest	运行测试
pytest -v	运行测试（详细输出）

常见问题

uvicorn 命令找不到

确保虚拟环境已激活，或者使用：

python -m uvicorn main:app --reload

导入错误

检查 Python 路径：

export PYTHONPATH=$PWD

数据库连接失败

1. 确保数据库服务已启动
2. 检查 DATABASE_URL 格式：
   • SQLite: sqlite:///./app.db
   • PostgreSQL: postgresql://user:pass@localhost/dbname
   • MySQL: mysql://user:pass@localhost/dbname

CORS 错误

确保在 .env 中配置了前端地址：

CORS_ORIGINS=http://localhost:5173,http://localhost:3000

相关资源

• FastAPI 官方文档
• FastAPI GitHub
• Pydantic 文档
• Uvicorn 文档