FastAPI请求与响应基础用法详解

FastAPI作为基于Python的现代Web框架，以其高性能、类型安全和开发效率著称。在API开发中，请求与响应的处理是核心环节，直接影响接口的可用性和可靠性。本文将系统梳理FastAPI中请求参数的获取方式、响应数据的构建方法及常见场景的解决方案，帮助开发者快速掌握关键技能。

一、请求参数的获取与解析

1. 路径参数（Path Parameters）

路径参数是URL中动态定义的部分，通过花括号{}声明，适用于资源标识场景。

示例：获取用户ID

from fastapi import FastAPI
app = FastAPI()
@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

• 关键点：路径参数类型需显式声明（如int），FastAPI会自动完成类型转换和验证。
• 扩展功能：通过Path类可添加额外约束（如最小值、最大值、正则表达式）。

2. 查询参数（Query Parameters）

查询参数是URL中?后的键值对，用于过滤或排序数据。

示例：分页查询

from fastapi import Query
@app.get("/items/")
async def read_items(
    skip: int = 0,
    limit: int = Query(10, le=100),  # 默认值10，最大值100
    sort: str = None
):
    return {"skip": skip, "limit": limit, "sort": sort}

• 默认值：通过=指定默认值，避免客户端未传参时的错误。
• 验证规则：Query类支持gt（大于）、lt（小于）、regex（正则匹配）等约束。

3. 请求体（Request Body）

请求体用于传输结构化数据（如JSON），通常与Pydantic模型结合使用。

示例：创建用户

from pydantic import BaseModel
class User(BaseModel):
    name: str
    age: int
@app.post("/users/")
async def create_user(user: User):
    return {"user_id": 1, "name": user.name, "age": user.age}

• 优势：Pydantic模型自动完成数据验证和序列化，减少手动解析代码。
• 嵌套模型：支持复杂数据结构（如嵌套对象、列表）。

二、响应数据的构建与优化

1. 基础响应类型

FastAPI支持多种响应格式，包括JSON、HTML、文件等。

JSON响应（默认）

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id, "status": "active"}

HTML响应

from fastapi.responses import HTMLResponse
@app.get("/", response_class=HTMLResponse)
async def read_root():
    return "<h1>Welcome to FastAPI</h1>"

2. 响应模型（Response Model）

通过response_model参数可控制返回数据的结构和类型。

示例：过滤敏感字段

from pydantic import BaseModel
class UserOut(BaseModel):
    name: str
    # 不返回age字段
@app.get("/users/{user_id}", response_model=UserOut)
async def read_user(user_id: int):
    user = {"name": "John", "age": 30}  # 假设从数据库获取
    return user  # 实际返回仅包含name

• 用途：隐藏敏感数据、统一接口返回格式。

3. 状态码与自定义响应

通过status_code参数可设置HTTP状态码，或使用Response对象自定义响应。

示例：设置状态码

from fastapi import status
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item():
    return {"message": "Item created"}

自定义响应头

from fastapi import Response
@app.get("/download/")
async def download_file():
    headers = {"X-Custom-Header": "FastAPI"}
    return Response("File content", media_type="text/plain", headers=headers)

三、高级场景与最佳实践

1. 依赖注入与请求上下文

通过Depends可复用逻辑（如认证、数据库连接）。

示例：依赖数据库查询

from fastapi import Depends
def get_db():
    # 模拟数据库连接
    return {"db": "connected"}
@app.get("/items/")
async def read_items(db=Depends(get_db)):
    return {"db_status": db["db"]}

2. 文件上传与处理

FastAPI支持多部分表单数据（如文件上传）。

示例：上传图片

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

3. 性能优化建议

• 异步处理：对I/O密集型操作（如数据库查询）使用async/await。
• 缓存响应：通过CacheControl中间件缓存静态数据。
• 分页设计：查询参数中限制limit最大值，防止内存溢出。

四、常见问题与解决方案

1. 参数类型不匹配

错误：客户端传入字符串"abc"作为user_id，但期望为int。
解决：FastAPI自动返回422 Unprocessable Entity错误，包含详细验证信息。

2. 请求体过大

错误：上传文件超过服务器限制。
解决：在@app.post中添加max_upload_size参数（需结合中间件）。

3. 跨域问题（CORS）

场景：前端调用不同源的API被阻止。
解决：安装fastapi-middleware-cors并配置允许的域名。

五、总结与学习资源

FastAPI的请求与响应机制通过类型注解和Pydantic模型实现了零样板代码的高效开发。掌握以下核心点可快速上手：

1. 路径参数与查询参数的声明方式。
2. Pydantic模型在请求体和响应模型中的应用。
3. 状态码、响应头及自定义响应的灵活控制。

推荐学习路径：

• 官方文档：FastAPI Documentation
• 实战项目：结合数据库（如SQLAlchemy）和认证（如OAuth2）构建完整API。
• 社区案例：GitHub搜索fastapi标签的高星项目。

通过系统练习和项目实践，开发者可在数小时内掌握FastAPI的核心用法，显著提升API开发效率。