FastAPI 从入门到实战 — 完整学习指南#

技术栈：FastAPI + Uvicorn

📑 目录#

一、环境准备与项目初始化
二、第一个 FastAPI 程序
三、路径参数与验证
四、查询参数与验证
五、响应格式
六、异常处理
七、依赖注入系统
八、中间件 Middleware
九、文件上传
附录：常见问题与易错点

一、环境准备与项目初始化#

1.1 工具介绍#

工具	说明
Uvicorn	基于 `asyncio` 的 ASGI 服务器，用于运行 FastAPI 异步应用
uv	Python 包管理工具，类似 pip，速度更快
FastAPI	现代、高性能的 Python Web 框架，基于类型提示构建 API
VS Code	推荐的代码编辑器

📌 官方文档

uv 文档：https://uv.doczh.com/getting-started

FastAPI 文档：https://fastapi.org.cn/

1.2 创建项目#

1
# 初始化项目
2
uv init example_project
3

4
# 进入项目目录
5
cd example_project
6

7
# 创建虚拟环境并安装 ruff（代码格式化工具）
8
uv add ruff
9

10
# 安装 FastAPI（注意加引号，确保所有终端兼容）
11
uv add "fastapi[standard]"

1.3 项目目录结构#

1
example_project/
2
├── main.py          # 📌 项目入口文件
3
├── pyproject.toml   # 项目配置文件
4
├── venv/            # 虚拟环境
5
├── .gitignore       # Git 忽略文件
6
├── uv.lock          # 依赖锁定文件
7
├── python-version   # Python 版本文件
8
├── README.md        # 项目说明
9
├── .git/            # Git 仓库
10
└── __pycache__/     # Python 缓存文件

二、第一个 FastAPI 程序#

将以下代码写入 main.py：

1
from fastapi import FastAPI
2

3
app = FastAPI()
4

5
@app.get("/")
6
def read_root():
7
    return {"Hello": "World"}

启动项目#

1
# --reload 表示代码修改后自动重新加载（开发环境推荐）
2
uvicorn main:app --reload

启动后访问 http://127.0.0.1:8000/，浏览器会显示：

1
{ "Hello": "World" }

💡 main:app 的含义：main 是文件名（main.py），app 是文件中创建的 FastAPI 实例变量名。

三、路径参数与验证#

路径参数是 URL 路径中的一部分，用于标识具体资源（如用户 ID、书名等）。

3.1 基本用法#

1
from fastapi import FastAPI, Path
2

3
app = FastAPI()
4

5
@app.get("/users/{id}")
6
async def get_user(id: int = Path(..., gt=0, lt=100, description="用户ID范围1-99")):
7
    return {"id": id}
8

9
@app.get("/users/{name}")
10
async def get_user_by_name(name: str = Path(..., min_length=2, max_length=10, description="用户名2-10个字符")):
11
    return {"name": name}

3.2 Path 验证参数速查表#

参数	全称	含义	示例
`gt`	greater than	大于	`gt=0` 表示大于 0
`lt`	less than	小于	`lt=100` 表示小于 100
`ge`	greater than or equal	大于等于	`ge=1` 表示大于等于 1
`le`	less than or equal	小于等于	`le=99` 表示小于等于 99
`min_length`	—	字符串最小长度	`min_length=2`
`max_length`	—	字符串最大长度	`max_length=10`
`...`	—	表示参数必填	`Path(...)`

四、查询参数与验证#

查询参数通常用于分页、过滤等操作，出现在 URL 的 ? 后面，如 /users?skip=0&limit=10。

1
from fastapi import FastAPI, Query
2

3
app = FastAPI()
4

5
@app.get("/users")
6
async def get_users(
7
    skip: int = Query(0, description="跳过的记录数", lt=100),
8
    limit: int = Query(10, description="返回的记录数")
9
):
10
    return {"skip": skip, "limit": limit}

💡 路径参数 vs 查询参数

类型位置示例 URL 用途
路径参数 URL 路径中 /users/42 标识具体资源
查询参数 ? 之后 /users?skip=0&limit=10 过滤、分页、排序

类型	位置	示例 URL	用途
路径参数	URL 路径中	`/users/42`	标识具体资源
查询参数	`?` 之后	`/users?skip=0&limit=10`	过滤、分页、排序

五、响应格式#

FastAPI 支持多种响应格式，可在路由装饰器中通过 response_class 指定。

5.1 内置响应格式#

1
from fastapi import FastAPI, HTMLResponse, FileResponse, JSONResponse
2

3
app = FastAPI()
4

5
# 返回 HTML 页面
6
@app.get("/html", response_class=HTMLResponse)
7
async def get_html():
8
    return "<h1>这是标题</h1>"
9

10
# 返回文件下载
11
@app.get("/file", response_class=FileResponse)
12
async def get_file():
13
    return FileResponse("./files/demo.png")
14

15
# 返回 JSON 数据
16
@app.get("/json", response_class=JSONResponse)
17
async def get_json():
18
    return {"message": "hello world", "code": 200}

5.2 自定义响应模型（Pydantic）#

使用 Pydantic 的 BaseModel 可以定义数据结构并自动进行数据验证。

1
from pydantic import BaseModel, Field
2
from fastapi import FastAPI
3

4
app = FastAPI()
5

6
class User(BaseModel):
7
    id: int = Field(description="用户ID")
8
    username: str = Field(min_length=2, max_length=10, description="用户名，2-10个字符")
9
    password: str = Field(min_length=3, max_length=20, description="密码，3-20个字符")
10

11
@app.post("/register")
12
async def user_register(user: User):
13
    return {
14
        "id": user.id,
15
        "username": user.username,
16
        "password": user.password,
17
        "message": "注册成功"
18
    }

💡 Pydantic 的作用：它会自动验证请求体中的数据是否符合定义的类型和约束，不符合则返回 422 Unprocessable Entity 错误，无需手动写验证逻辑。

六、异常处理#

使用 HTTPException 可以向客户端返回标准的 HTTP 错误响应。

1
from fastapi import FastAPI, HTTPException
2

3
app = FastAPI()
4

5
@app.get("/news/{id}")
6
async def get_news(id: int):
7
    if id not in [1, 2, 3, 4, 5, 6]:
8
        raise HTTPException(status_code=404, detail="当前ID不存在")
9
    return {
10
        "id": id,
11
        "title": f"标题{id}",
12
        "content": f"内容{id}"
13
    }

参数	说明	示例
`status_code`	HTTP 状态码	`404`（未找到）、`400`（请求错误）、`500`（服务器错误）
`detail`	错误描述信息	`"当前ID不存在"`

七、依赖注入系统#

7.1 什么是依赖注入？#

依赖注入（Dependency Injection） 是 FastAPI 的核心特性之一。简单来说，它允许你把公共逻辑（如数据库连接、参数解析）抽取出来，在多个路由中复用。

7.2 基本用法#

1
from fastapi import FastAPI, Depends, Query
2

3
app = FastAPI()
4

5
# ① 定义依赖项（公共参数逻辑）
6
async def common_parameters(
7
    skip: int = Query(0, ge=0),
8
    limit: int = Query(10, le=60)
9
):
10
    return {"skip": skip, "limit": limit}
11

12
# ② 在路由中注入依赖项
13
@app.get("/news")
14
async def get_news(commons: dict = Depends(common_parameters)):
15
    return {"message": "hello", "commons": commons}

⚠️ 易错点：Depends(common_parameters) 不要加括号调用！

✅ 正确：Depends(common_parameters)

❌ 错误：Depends(common_parameters())

7.3 依赖注入的好处#

好处	说明
代码复用	多个接口共享相同的参数验证逻辑
关注点分离	路由只关注业务逻辑，参数处理交给依赖
易于测试	可以轻松替换依赖项进行单元测试

八、中间件 Middleware#

中间件用于在请求到达路由之前、或响应返回客户端之前执行一些通用操作（如日志记录、身份验证、CORS 处理等）。

8.1 基本用法#

1
from fastapi import FastAPI
2

3
app = FastAPI()
4

5
@app.middleware("http")
6
async def middleware1(request, call_next):
7
    print("中间件1：请求开始")
8
    response = await call_next(request)  # 传递给下一个中间件或路由
9
    print("中间件1：请求结束")
10
    return response
11

12
@app.middleware("http")
13
async def middleware2(request, call_next):
14
    print("中间件2：请求开始")
15
    response = await call_next(request)
16
    print("中间件2：请求结束")
17
    return response
18

19
@app.get("/")
20
async def root():
21
    return {"message": "Hello World"}

8.2 执行顺序#

1
请求进入 → Middleware2 → Middleware1 → 路由处理
2
响应返回 ← Middleware2 ← Middleware1 ← 路由处理

控制台输出顺序：

1
中间件2：请求开始
2
中间件1：请求开始
3
中间件1：请求结束
4
中间件2：请求结束

💡 记忆口诀：中间件像洋葱模型，请求从外到内，响应从内到外。后注册的中间件先接收请求。

九、文件上传#

9.1 基本上传（保存在内存中）#

FastAPI 使用 UploadFile 类处理文件上传，默认将文件保存在内存中。

1
import os
2
from typing import Annotated
3
from fastapi import FastAPI, File, UploadFile
4

5
app = FastAPI()
6

7
# 单文件上传（文件内容以 bytes 形式接收）
8
@app.post("/files")
9
async def create_file(
10
    files: Annotated[list[bytes], File(description="多个文件以bytes形式")]
11
):
12
    return {"file_sizes": [len(file) for file in files]}
13

14
# 多文件上传（使用 UploadFile，可获取文件名等信息）
15
@app.post("/mult_files")
16
async def create_upload_files(
17
    files: Annotated[list[UploadFile], File(description="多个文件")]
18
):
19
    return {"filenames": [file.filename for file in files]}

9.2 将文件保存到服务器#

需要安装异步文件处理库：

1
uv add aiofiles

完整示例：

1
import os
2
from typing import Annotated
3
import aiofiles
4
from fastapi import FastAPI, File, UploadFile
5
from fastapi.staticfiles import StaticFiles
6

7
app = FastAPI()
8

9
# 挂载静态文件目录，可通过 /static/xxx 访问上传的文件
10
app.mount("/static", StaticFiles(directory="uploads"), name="static")
11

12
# 确保上传目录存在
13
os.makedirs("./uploads", exist_ok=True)
14

15
# 单文件上传并保存
16
@app.post("/upload_file")
17
async def upload_file(file: Annotated[UploadFile, File(description="单文件上传")]):
18
    async with aiofiles.open(f"./uploads/{file.filename}", "wb") as f:
19
        content = await file.read()   # 读取上传内容
20
        await f.write(content)        # 写入文件
21
    return {
22
        "filename": file.filename,
23
        "content_type": file.content_type,
24
        "size": file.size,
25
        "path": f"/static/{file.filename}",
26
        "message": "上传成功",
27
    }
28

29
# 多文件上传并保存
30
@app.post("/upload_files")
31
async def upload_files(
32
    files: Annotated[list[UploadFile], File(description="多文件上传")]
33
):
34
    for file in files:
35
        async with aiofiles.open(f"./uploads/{file.filename}", "wb") as f:
36
            content = await file.read()
37
            await f.write(content)
38
    return {"filenames": [file.filename for file in files], "message": "上传成功"}

💡 Annotated 的作用：它是 Python 3.9+ 的类型注解语法，用于在类型提示上附加额外的元数据（如描述信息），FastAPI 会利用这些信息生成 API 文档。

附录：常见问题与易错点#

A1. 中间件执行顺序不直观#

中间件按注册的倒序执行（后注册的先执行），像洋葱一样包裹。

A2. 依赖注入忘记写 `Depends`#

1
# ❌ 错误：缺少 Depends
2
async def get_news(db: AsyncSession = get_database):
3

4
# ✅ 正确
5
async def get_news(db: AsyncSession = Depends(get_database)):

A3. 静态路由与动态路由冲突#

1
# ⚠️ 注意：静态路由要放在动态路由前面
2
@app.get("/books/search")    # 静态路由（先匹配）
3
async def search(): ...
4

5
@app.get("/books/{id}")      # 动态路由（后匹配）
6
async def get_book(id: int): ...

A4. `file.read()` 是异步的#

上传文件时，await file.read() 不能写成 file.read()，否则会得到协程对象而非文件内容。

📝 学习建议：建议按照本文档顺序，先掌握 FastAPI 基础（路由、参数、响应），再学习依赖注入和中间件，最后学习文件上传。数据库操作请参考 SQLAlchemy 异步配置与 CRUD 操作。

追风赶月莫停留