【Python】Web框架 FastAPI 详解

1、入门

FastAPI 基于 HTTP 标准方法定义接口，是Python中最火的Web框架

入门用法（Hello World）参见博客：【Python】Web框架

FastAPI 内部是 Starlette 和 Pydantic ，外加类型提示

Starlette：Web 异步网络框架（管请求、路由、HTTP 流程）
Pydantic：数据校验、类型解析库（管参数、JSON 校验、数据转换）

bash 复制代码

Uvicorn(ASGI服务器)
    ↓
Starlette（网络层：请求分发、路由、中间件、websocket）
    ↓
FastAPI（胶水层）：接收请求后，调用Pydantic校验所有参数
    ↓
Pydantic（数据层：校验路径参数、查询参数、POST请求体）

2、基本请求方式

FastAPI 使用 Python 语法糖 @；

比如下面的示例：先用 app.get 装饰器工厂，返回装饰器函数；

然后使用@装饰下面的函数

1）GET 查询数据

python 复制代码

from fastapi import FastAPI
app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"id": item_id}

2）POST 提交数据

python 复制代码

@app.post("/items")
def create_item(name: str):
    return {"msg": "创建成功", "name": name}

3）PUT 更新全部数据

python 复制代码

@app.put("/items/{item_id}")
def update_item(item_id: int):
    return {"msg": "全量更新"}

4）PATCH 更新部分数据

python 复制代码

@app.patch("/items/{item_id}")
def patch_item(item_id: int):
    return {"msg": "局部更新"}

5）DELETE 删除数据

python 复制代码

@app.delete("/items/{item_id}")
def del_item(item_id: int):
    return {"msg": "删除成功"}

3、静态资源

StaticFiles 是 Starlette（FastAPI 底层 Web 框架）内置组件，专门用来：

托管静态资源文件，让浏览器可以通过 HTTP 地址访问服务器本地磁盘上的静态文件。

python 复制代码

from fastapi import FastAPI
from starlette.staticfiles import StaticFiles

app = FastAPI()
app.mount("/static", StaticFiles(directory="static"), name="static")
app.mount("/images", StaticFiles(directory="images"), name="images")

4、异步操作：async def

4.1 协程函数

在 fastapi 的语法糖@下面，使用 async def 定义协程函数的作用：

复制代码

内部有 await 异步操作，直接在事件循环(event loop) 中运行

FastAPI 整个服务跑在一个事件循环上；

在等待HTTP返回时前，事件循环可以去服务别的请求，并发能力强

python 复制代码

from fastapi import FastAPI
app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    await asyncio.sleep(1)
    return {"id": item_id}

如果不使用 async 协程函数；

普通函数，会同步阻塞调用，卡死整个事件循环

4.2 常用示例

python 复制代码

import httpx
from fastapi import APIRouter
router = APIRouter()

@router.get("/weather")
async def get_weather():
    async with httpx.AsyncClient() as client:
        resp = await client.get("https://api.weather.com/today")
    return resp.json()

4.3 反面示例

在 async def 里不能写阻塞代码，比如sleep()、requests.get(url)；

可以使用 await run_in_threadpool() 封装起来，交给线程池；

或者直接使用普通函数def，FastAPI 会自动丢进线程池；

python 复制代码

import time, requests

@router.get("/bad")
async def bad():
    time.sleep(3)
    data = requests.get(url)
    return data

5、全局异常处理

FastAPI 接口一旦抛异常；默认返回:

复制代码

{ "detail": "Internal Server Error" }

如果前端要求返回指定格式，将无法解析；

使用下面的代码，可以将返回格式改成：

复制代码

{ "code": 5001, "msg": "具体错误信息", "data": {} }

python 复制代码

    class ServerError(APIException):
        code = 5001
        msg = '接口错误'
    
    @app.exception_handler(Exception)
    async def udf_exception_handler(request, e):
        if isinstance(e , APIException):
            error = e
        else: 
            if hasattr(app , "logger"):
                app.logger.exception(e)
            error = ServerError(msg = str(e))
        if hasattr(app , "logger"):
            app.logger.error(f"API ERROR [{error.code}] : {error.msg}")
        return error.jsonfy

@app.exception_handler(Exception) 是全局异常兜底机制；

统一拦截把所有异常，转换成指定的格式，返回给前端；

也可以把错误记到日志里；

6、常用参数

6.1 示例

python 复制代码

@app.post(laoer", include_in_schema=False summary="创建文件夹" , tags=[f"系统配置"])

控制接口在 Swagger 文档

tags(标签) 给接口分组：把接口归到某个分组下，Swagger 文档里就会按 tag 折叠展示
summary(摘要)一句话说明接口用途，显示在 Swagger 文档每个接口那一行的简短标题
include_in_schema(是否纳入文档)隐藏接口，默认为True，即接口出现在 Swagger 文档里

6.2 文档展示相关参数

参数	类型	作用
description	str	更详细的说明
response_description	str	对响应的说明，默认是 "Successful Response"
deprecated	bool	标记接口已废弃，Swagger 里会显示删除线和 ⚠️ 警告
responses	dict	自定义额外状态码的说明和模型,如 {404: {"model": ErrorModel, "description": "未找到"}}
openapi_extra	dict	往 OpenAPI schema 里塞自定义字段
operation_id	str	给接口一个唯一 ID(常用于代码生成)
name	str	路由的内部名字(URL 模板反向生成时用)

例如：

python 复制代码

@app.get(
    f"{API_PREFIX}/export",
    summary="获取导出作业列表",
    description="返回所有导出任务及其状态,支持按时间排序",
    tags=["任务管理"],
    deprecated=False,
    responses={500: {"description": "服务器内部错误"}},
)

6.3 响应模型的参数

参数	作用
response_model	指定返回数据的 Pydantic 模型，自动过滤多余字段
response_model_exclude / response_model_include	只保留某些字段
response_model_by_alias	是否使用模型字段的别名
response_model_exclude_unset	不返回没赋值的字段
response_model_exclude_none	不返回值为 None 的字段
response_class	自定义响应类，如 JSONResponse、HTMLResponse、PlainTextResponse
status_code	成功时返回的 HTTP 状态码，默认 200，如 status_code=201

7、BaseModel

python 复制代码

from pydantic import BaseModel

BaseModel 是 Pydantic 库提供的基础模型父类；

自定义的数据类只要继承它，就自动拥有：

数据类型校验
类型转换
默认值
嵌套结构
JSON 序列化
错误提示

FastAPI 所有请求体、响应体数据解析，底层全靠它实现

例如下面的示例，自动将json格式转换成Python对象（Item）

python 复制代码

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    age: int

@app.post("/items")
def create_item(item: Item):
    return item

主要作用：

自动解析请求体：从 JSON 反序列化为 Python 对象
自动数据校验：类型不对或字段缺失直接返回 422
自动生成文档：OpenAPI Schema 直接从类型推导
自动序列化响应：返回对象自动转 JSON 格式