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 环境安装

bash 复制代码
# 框架 + 异步服务器
pip install fastapi uvicorn

2 第一个 FastAPI 项目

2.1 方式 1:命令行启动

main.py

python 复制代码
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}

终端运行:

bash 复制代码
# main=文件名 app=FastAPI实例 --reload开发热更新
uvicorn main:app --reload

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

python 复制代码
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 路径中变量)

python 复制代码
# 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? 后键值对)

python 复制代码
# 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请求体文档示例

python 复制代码
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 项目结构

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

5.2 子路由 routers/user.py

python 复制代码
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

python 复制代码
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 实现路由模块化,解决单文件路由臃肿问题
相关推荐
火山引擎和TA的超级拍档们3 小时前
产品情报局 11 | AI 数据湖 LAS:打造大模型时代多模态数据底座
前端·后端
JavaGuide4 小时前
Gemini 真的变强了,写代码做视频的能力接近 Claude Opus5.5 了!
前端·ai编程
niceyayale4 小时前
WebRTC 延迟怎么调试:从 ICE 到 jitter buffer 的六个观测点
前端
aleimu4 小时前
Windows 11 右键打开 Cmder 2.0:从找不到菜单到默认使用 Cmder
前端·人工智能·后端
tryCbest4 小时前
Vue系列——第 20 篇:Vue Router 4——路由管理完全指南(上)
前端·javascript·vue.js
feixing_fx4 小时前
原始类型与引用类型:赋值时到底复制了什么
开发语言·前端·javascript·前端框架
一条破秋裤4 小时前
【1115】【多线程】【笔记】
前端·chrome·笔记
黑十4 小时前
FDE 怎么快速搭一个可演示页面?最小前端方案
java·大数据·前端·数据库·人工智能
Funlang4 小时前
在 Windows 95 上写前端
前端·javascript·windows
cidy_985 小时前
python第7课. 输入与输出
前端