FastAPI快速上手：请求与响应基础用法全解析

FastAPI作为现代Python Web框架的标杆，凭借其高性能、自动文档生成和类型提示支持等特性，已成为API开发的首选工具。本文将系统梳理FastAPI中请求与响应的核心机制，通过模块化示例帮助开发者快速掌握基础用法。

一、请求参数处理：从路径到查询的完整映射

1.1 路径参数（Path Parameters）

路径参数是API设计中最基础的元素，用于从URL路径中提取变量值。FastAPI通过{param_name}语法定义路径参数，配合类型注解实现自动校验。

from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

此示例中，item_id参数被强制转换为整数类型，若传入非数字值（如/items/foo），FastAPI会自动返回422错误响应。开发者可通过Path类实现更精细的控制：

from fastapi import Path
@app.get("/items/{item_id}")
async def read_item(
    item_id: int = Path(..., gt=0, description="物品唯一标识符")
):
    return {"item_id": item_id}

Path类的参数说明：

• ...：表示必填参数
• gt=0：限制值必须大于0
• description：生成OpenAPI文档时的描述信息

1.2 查询参数（Query Parameters）

查询参数通过URL的?key=value形式传递，适用于可选的过滤条件。FastAPI使用默认参数语法处理查询参数：

@app.get("/items/")
async def read_items(
    skip: int = 0, 
    limit: int = 100,
    sort: str = None
):
    return {"skip": skip, "limit": limit, "sort": sort}

参数特性：

• skip和limit为必选参数（有默认值）
• sort为可选参数（允许None值）
• 类型注解自动完成参数转换

1.3 请求体（Request Body）

当需要接收复杂数据时，请求体是最佳选择。FastAPI通过Pydantic模型实现数据验证和自动文档生成：

from pydantic import BaseModel
class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

关键优势：

• 自动将JSON数据反序列化为Python对象
• 内置数据验证（如price必须为float类型）
• 通过item.dict()快速转换为字典

二、响应处理：从基础返回类型到高级定制

2.1 自动JSON响应

FastAPI默认将返回的字典、Pydantic模型等数据结构序列化为JSON响应：

@app.get("/items/auto")
async def auto_response():
    return {"message": "自动JSON序列化"}

2.2 显式响应模型

通过Response类或JSONResponse可实现更精细的控制：

from fastapi.responses import JSONResponse
@app.get("/items/custom")
async def custom_response():
    return JSONResponse(
        content={"message": "自定义响应"},
        status_code=200,
        headers={"X-Custom": "Header"}
    )

2.3 响应模型（Response Model）

使用Pydantic模型定义响应结构，实现输出数据的标准化：

class OutputItem(BaseModel):
    id: int
    name: str
    price: float
@app.get("/items/{item_id}/output", response_model=OutputItem)
async def get_output_item(item_id: int):
    # 模拟数据库查询
    return {
        "id": item_id,
        "name": "示例商品",
        "price": 99.99
    }

优势说明：

• 确保返回数据符合预定义结构
• 自动过滤未定义的字段
• 生成精确的OpenAPI文档

三、高级请求处理技巧

3.1 依赖注入系统

FastAPI的依赖注入系统可实现请求上下文的共享：

from fastapi import Depends, Header, HTTPException
async def get_token_header(x_token: str = Header(...)):
    if x_token != "fake-super-secret-token":
        raise HTTPException(status_code=400, detail="X-Token header invalid")
    return x_token
@app.get("/items/secure")
async def secure_endpoint(token: str = Depends(get_token_header)):
    return {"token": token}

3.2 文件上传处理

通过UploadFile和Form实现多部分表单处理：

from fastapi import UploadFile, File, Form
@app.post("/upload/")
async def upload_file(
    file: UploadFile = File(...),
    caption: str = Form(...)
):
    contents = await file.read()
    return {
        "filename": file.filename,
        "caption": caption,
        "content_length": len(contents)
    }

四、最佳实践建议

1. 类型提示优先：始终使用类型注解，享受自动文档和验证带来的便利
2. 分层响应模型：为不同场景设计专门的响应模型（如OutputItem、DetailedOutputItem）
3. 合理使用依赖项：将数据库连接、认证逻辑等封装为可复用的依赖项
4. 启用详细错误：通过app = FastAPI(debug=True)获取更详细的错误信息（开发环境）
5. 版本控制策略：在路径中包含版本号（如/v1/items/）便于后续迭代

五、性能优化技巧

1. 异步处理：对I/O密集型操作使用async/await
2. 数据验证缓存：Pydantic模型会自动缓存验证逻辑
3. 响应压缩：通过中间件启用Gzip压缩
4. 连接池管理：数据库连接应使用连接池

结语

FastAPI的请求与响应机制通过类型系统和模块化设计，将API开发的复杂性大幅降低。开发者只需掌握路径参数、查询参数、请求体三大基础元素，配合Pydantic模型和依赖注入系统，即可构建出企业级API服务。建议从简单示例入手，逐步添加认证、缓存等高级功能，最终形成完整的API开发能力体系。