FastAPI请求与响应实战指南：从入门到高效开发

一、FastAPI请求处理核心机制

FastAPI基于Starlette与Pydantic构建的请求处理系统，通过装饰器语法实现路径与方法的精准匹配。其核心优势在于自动类型转换与数据验证，开发者无需手动处理参数解析。

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}

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

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

1.2 请求体处理

FastAPI使用Pydantic模型进行请求体验证，支持JSON、表单数据等多格式解析：

from pydantic import BaseModel
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None
@app.post("/items/")
async def create_item(item: Item):
    return item

表单数据处理需显式声明Form参数：

from fastapi import Form
@app.post("/login/")
async def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username}

二、响应控制进阶技巧

2.1 响应模型定制

通过response_model参数实现响应数据过滤与格式转换：

@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: int):
    return {"name": "Foo", "price": 10.5, "is_offer": True}

嵌套模型处理复杂数据结构：

class User(BaseModel):
    username: str
    full_name: str | None = None
class UserOut(BaseModel):
    username: str
    email: str
@app.put("/users/{user_id}", response_model=UserOut)
async def update_user(user: User):
    # 业务逻辑处理
    return {"username": user.username, "email": "user@example.com"}

2.2 状态码与头部管理

自定义状态码与响应头示例：

from fastapi import Response
@app.post("/items/", status_code=201)
async def create_item(response: Response, item: Item):
    response.headers["X-Custom"] = "FastAPI"
    return item

2.3 流式响应处理

大文件传输场景下的流式响应：

from fastapi.responses import StreamingResponse
async def generate_file():
    for i in range(1000):
        yield f"Data chunk {i}\n"
@app.get("/download/")
async def download_file():
    return StreamingResponse(generate_file())

三、高级请求处理模式

3.1 依赖注入系统

通过Depends实现跨路由共享逻辑：

from fastapi import Depends, Header, HTTPException
async def verify_token(x_token: str = Header(...)):
    if x_token != "fake-token":
        raise HTTPException(status_code=400, detail="Invalid token")
    return x_token
@app.get("/secure/", dependencies=[Depends(verify_token)])
async def secure_endpoint():
    return {"message": "Authenticated"}

3.2 中间件实现

全局请求/响应处理中间件示例：

from fastapi import Request
@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

四、性能优化实践

4.1 异步请求处理

数据库操作等I/O密集型任务应使用异步：

from databases import Database
database = Database("postgresql://user:password@localhost/db")
@app.get("/async-items/")
async def read_async_items():
    query = "SELECT * FROM items"
    results = await database.fetch_all(query)
    return results

4.2 请求缓存策略

高频不变数据缓存实现：

from fastapi import CacheControl
@app.get("/cached-items/")
@CacheControl(max_age=3600)  # 缓存1小时
async def get_cached_items():
    return {"data": "static content"}

五、常见问题解决方案

5.1 参数验证错误处理

自定义异常处理器示例：

from fastapi import Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException
@app.exception_handler(HTTPException)
async def http_exception_handler(request: Request, exc: HTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"message": exc.detail},
    )

5.2 跨域请求处理

CORS中间件配置：

from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

六、最佳实践建议

1. 模型分离原则：将请求/响应模型与数据库模型分离，避免安全风险
2. 路径规范设计：采用RESTful风格，使用名词复数形式（如/items/）
3. 版本控制策略：通过路径前缀实现API版本管理（如/v1/items/）
4. 文档自动化：利用FastAPI自动生成的OpenAPI文档
5. 测试覆盖：使用TestClient编写单元测试：
   ```python
   from fastapi.testclient import TestClient

client = TestClient(app)

def test_read_item():
response = client.get(“/items/1”)
assert response.status_code == 200
assert response.json() == {“item_id”: 1}
```

通过系统掌握上述请求与响应处理机制，开发者能够高效构建出高性能、高可靠性的API服务。FastAPI的自动文档、类型提示和异步支持等特性，可显著提升开发效率与代码质量。建议结合实际项目需求，逐步实践本文介绍的各项技术点。