FastAPI请求与响应全解析：从入门到实战

一、FastAPI请求处理的核心机制

FastAPI基于Starlette和Pydantic构建，其请求处理流程包含三个核心环节：路径解析、参数验证和业务逻辑执行。当客户端发起请求时，ASGI服务器将请求对象传递给FastAPI路由系统，系统通过装饰器注册的路径匹配规则定位到对应的处理函数。

1.1 路径参数处理

路径参数通过花括号{}在路由路径中定义，支持类型注解自动转换。例如：

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参数会自动从字符串转换为整数。FastAPI内置参数验证，当传入非数字值时会返回422错误。

1.2 查询参数处理

查询参数通过函数参数直接声明，支持可选参数和默认值：

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

调用/items/?skip=5&limit=20时，参数会自动绑定。Pydantic模型可用于复杂查询参数验证：

from pydantic import BaseModel
class QueryParams(BaseModel):
    skip: int = 0
    limit: int = 10
@app.get("/advanced-items/")
async def read_advanced_items(params: QueryParams):
    return params.dict()

1.3 请求体处理

FastAPI使用Pydantic模型进行请求体验证，支持JSON、表单数据和文件上传：

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

此示例展示了模型验证、字段可选处理和计算属性添加。

二、响应构建的进阶技巧

FastAPI提供多种响应构建方式，包括自动JSON响应、自定义响应和流式响应。

2.1 自动JSON响应

默认情况下，FastAPI将函数返回值序列化为JSON。通过response_model参数可控制输出结构：

from fastapi import FastAPI
from pydantic import BaseModel
class OutputItem(BaseModel):
    name: str
    price: float
app = FastAPI()
@app.get("/items/{item_id}", response_model=OutputItem)
async def read_item(item_id: int):
    return {"name": "Foo", "price": 42.0}

即使返回字典包含额外字段，响应也会按OutputItem模型过滤。

2.2 自定义响应

使用Response对象可完全控制响应：

from fastapi import Response
@app.get("/custom-response/")
async def custom_response():
    return Response(
        content="Custom plain text response",
        media_type="text/plain"
    )

支持设置状态码、头部和Cookie：

from fastapi import FastAPI, Response
app = FastAPI()
@app.get("/cookie/")
async def set_cookie():
    response = Response("Cookie set")
    response.set_cookie(key="user_id", value="12345")
    return response

2.3 流式响应

对于大文件或实时数据，可使用生成器实现流式传输：

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import time
app = FastAPI()
def generate_data():
    for i in range(10):
        yield f"Data chunk {i}\n"
        time.sleep(0.5)
@app.get("/stream/")
async def stream_data():
    return StreamingResponse(generate_data(), media_type="text/plain")

三、请求与响应中间件

中间件可在请求处理前后插入自定义逻辑：

from fastapi import FastAPI, Request
app = FastAPI()
@app.middleware("http")
async def log_requests(request: Request, call_next):
    print(f"Request path: {request.url.path}")
    response = await call_next(request)
    print(f"Response status: {response.status_code}")
    return response

此中间件会记录所有HTTP请求的路径和响应状态码。

四、最佳实践与性能优化

1. 参数验证：始终使用Pydantic模型进行请求体验证，避免手动验证代码
2. 响应模型：为不同客户端定义不同的响应模型，使用response_model_include和response_model_exclude控制字段
3. 异步处理：对I/O密集型操作使用async/await，计算密集型操作可考虑线程池
4. 依赖注入：使用Depends系统管理数据库连接等共享资源

5. 文档增强：通过OpenAPI注解丰富API文档，如：

   @app.get("/items/{item_id}")
   async def read_item(
    item_id: int,
    q: str | None = None  # 查询字符串参数
   ) -> dict:
    """
    获取项目详情
    - **item_id**: 项目唯一标识符
    - **q**: 可选搜索查询
    """
    return {"item_id": item_id, "q": q}

五、常见问题解决方案

1. CORS问题：通过CORSMiddleware解决跨域请求
   ```python
   from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
CORSMiddleware,
allow_origins=[““],
allow_credentials=True,
allow_methods=[““],
allow_headers=[“*”],
)

2. **大文件上传**：配置最大上传大小
```python
from fastapi import FastAPI, UploadFile, File
app = FastAPI()
@app.post("/upload/")
async def upload_file(file: UploadFile = File(...)):
    # 处理文件上传
    return {"filename": file.filename}

在生产环境中需设置max_upload_size参数。

1. 性能监控：集成Prometheus中间件
   ```python
   from prometheus_fastapi_instrumentator import Instrumentator

Instrumentator().instrument(app).expose(app)
```

通过系统掌握FastAPI的请求处理与响应构建机制，开发者能够高效构建高性能API服务。本文介绍的路径参数、查询参数、请求体验证、响应模型和中间件等核心概念，构成了FastAPI开发的基础知识体系。结合实际项目需求，灵活运用这些技术点，可显著提升开发效率和API质量。