FastAPI零基础完整实战

目录

• • 前言
  • [1 环境安装](#1 环境安装)
  • [2 第一个 FastAPI 项目](#2 第一个 FastAPI 项目)
  • • [2.1 方式 1：命令行启动](#2.1 方式 1：命令行启动)
    • [2.2 方式 2：代码内直接启动 uvicorn](#2.2 方式 2：代码内直接启动 uvicorn)
    • [2.3 访问自动交互式文档](#2.3 访问自动交互式文档)
  • [3 同步 def 与异步 async def 路由区别](#3 同步 def 与异步 async def 路由区别)
  • [4 三大参数详解](#4 三大参数详解)
  • • [4.1 路径参数（URL 路径中变量）](#4.1 路径参数（URL 路径中变量）)
    • [4.2 查询参数（URL? 后键值对）](#4.2 查询参数（URL? 后键值对）)
    • [4.3 请求体（POST/PUT 传 JSON，Pydantic 模型）](#4.3 请求体（POST/PUT 传 JSON，Pydantic 模型）)
  • [5大型项目模块化：APIRouter 路由拆分](#5大型项目模块化：APIRouter 路由拆分)
  • • [5.1 项目结构](#5.1 项目结构)
    • [5.2 子路由 routers/user.py](#5.2 子路由 routers/user.py)
    • [5.3 主文件挂载路由 main.py](#5.3 主文件挂载路由 main.py)
  • [6 本章总结](#6 本章总结)

---

前言

FastAPI 基于 Starlette+Pydantic，自带自动 Swagger 文档、类型校验、依赖注入，是 Python 高性能 API 首选。本章从零搭建项目，覆盖路由、路径参数、查询参数、请求体、模块化路由拆分。

1 环境安装

# 框架 + 异步服务器
pip install fastapi uvicorn

2 第一个 FastAPI 项目

2.1 方式 1：命令行启动

main.py

from fastapi import FastAPI
app = FastAPI()

@app.get("/")
def root():
    return {"msg": "Hello FastAPI"}

@app.get("/items/{item_id}")
def get_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "query": q}

终端运行：

# main=文件名 app=FastAPI实例 --reload开发热更新
uvicorn main:app --reload

2.2 方式 2：代码内直接启动 uvicorn

import uvicorn
from fastapi import FastAPI
app = FastAPI()

@app.get("/")
async def root():
    return {"msg": "async接口"}

if __name__ == "__main__":
    uvicorn.run(
        app="main:app",
        host="0.0.0.0", # 允许局域网访问
        port=8000,
        reload=True # 生产环境删除
    )

2.3 访问自动交互式文档

FastAPI Swagger文档页面

1. 接口预览文档：http://127.0.0.1:8000/docs（Swagger UI）
2. 极简 JSON 文档：http://127.0.0.1:8000/redoc

3 同步 def 与异步 async def 路由区别

1. async def：原生协程，内部可使用await异步 IO（异步数据库 /aiohttp），事件循环直接调度，性能最优
2. def同步函数：FastAPI 自动放入线程池执行，不阻塞事件循环，但大量耗时同步操作会耗尽线程池

最佳实践：数据库、网络 IO 优先 async def；纯计算逻辑使用普通 def

4 三大参数详解

4.1 路径参数（URL 路径中变量）

# item_id强制int类型，传字符串自动返回422校验错误
@app.get("/items/{item_id}")
async def get_item(item_id: int):
    return {"id": item_id}

文档路径参数类型校验

参数顺序坑 ：固定路由/users/me必须写在/users/{user_id}前面，否则me会被识别为 user_id 参数

4.2 查询参数（URL? 后键值对）

# start默认0 limit默认10 short布尔可选
@app.get("/items/")
async def list_items(start:int=0, limit:int=10, short:bool=False):
    return {"slice": [start, start+limit], "short": short}

• 不传参数使用默认值；不写默认值则为必传参数
• bool 类型自动转换：true/1/on/yes都会识别为 True

4.3 请求体（POST/PUT 传 JSON，Pydantic 模型）

POST请求体文档示例

from pydantic import BaseModel

# 定义请求体校验模型
class Item(BaseModel):
    name: str
    price: float
    desc: str | None = None # 可选字段

@app.post("/items/")
async def create_item(item: Item):
    # item自动转为字典返回，自动校验字段类型
    return item

5大型项目模块化：APIRouter 路由拆分

5.1 项目结构

myproject/
├── main.py        # 主应用
└── routers/
    ├── user.py    # 用户模块路由
    └── item.py    # 商品模块路由

5.2 子路由 routers/user.py

from fastapi import APIRouter
# prefix统一路由前缀 tags文档分组
router = APIRouter(prefix="/users", tags=["用户管理"])

@router.get("/")
def get_users():
    return {"users": []}

@router.get("/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

5.3 主文件挂载路由 main.py

from fastapi import FastAPI
from routers import user, item

app = FastAPI(title="路由拆分演示")
# 把子路由注册到主应用
app.include_router(user.router)
app.include_router(item.router)

@app.get("/")
def root():
    return {"msg":"首页"}

路由拆分后文档分组效果

运行后文档自动按tags分组，接口地址自动拼接prefix

6 本章总结

1. FastAPI 内置自动接口文档，无需手写 API 文档
2. 三类参数：路径参数、查询参数、Pydantic 请求体，自动类型校验
3. 区分同步 / 异步路由，IO 密集优先 async def
4. APIRouter 实现路由模块化，解决单文件路由臃肿问题