FastAPI 中间件实战：请求日志、耗时统计、IP 黑名单一站式搞定

FastAPI 中间件深度解析：从原理到实战应用

简单来说，中间件充当了HTTP请求处理流程中的统一拦截层。所有进入应用的请求和返回的响应都会经过这里，开发者可以在此集中实现日志记录、性能监控、安全拦截、数据预处理等通用逻辑，极大提升代码的复用性与可维护性。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

FastAPI的中间件机制继承自Starlette框架，其语法设计极为简洁直观：

@app.middleware("http")
async def my_middleware(request: Request, call_next):
    # 请求进来时做的事
    response = await call_next(request)
    # 请求出去时做的事
    return response

核心逻辑仅需数行代码。call_next是关键函数，它负责将当前请求传递给后续的中间件或最终的路由处理函数。

实战一：构建全局请求日志中间件

记录每一次API调用的详细信息是后端服务可观测性的基础。通过中间件，我们可以轻松捕获请求方、访问端点、响应状态及处理耗时等关键数据。

import time
from fastapi import Request
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.middleware("http")
async def log_requests(request: Request, call_next):
    start_time = time.time()

    # 记录请求信息
    logger.info(f"→ {request.method} {request.url.path}")

    response = await call_next(request)

    # 计算耗时
    process_time = time.time() - start_time

    # 记录响应信息
    logger.info(f"← {response.status_code} | {process_time:.3f}s")

    return response

部署后，所有请求轨迹将清晰呈现于日志中。当接口出现异常时，可快速通过状态码（如500）定位问题；若响应缓慢，处理耗时数据则能直接指明性能瓶颈所在。

实战二：精细化接口性能监控中间件

基础的耗时统计可以进一步优化，例如为慢请求设定阈值告警，并将性能数据注入响应头，便于全链路分析。

@app.middleware("http")
async def timing_middleware(request: Request, call_next):
    start = time.perf_counter()
    response = await call_next(request)
    elapsed = time.perf_counter() - start

    # 超过 1 秒标红
    if elapsed > 1.0:
        logger.warning(f"⚠️ 慢请求: {request.url.path} 耗时 {elapsed:.3f}s")
    else:
        logger.info(f"✓ {request.url.path} 耗时 {elapsed:.3f}s")

    # 把耗时加到响应头里，方便前端调试
    response.headers["X-Process-Time"] = str(elapsed)
    return response

此处选用perf_counter()函数，它能提供比time()更高精度的时间测量。同时，将耗时写入X-Process-Time响应头，方便前端开发者或监控系统直接获取接口性能指标。

实战三：实现IP黑名单安全拦截中间件

应对恶意IP地址的扫描或攻击，最直接的方式是在入口层进行拦截。中间件是实现此安全策略的理想位置。

# 黑名单列表，实际项目中可以放在配置文件或 Redis
BLACKLIST = {"192.168.1.100", "10.0.0.50"}

@app.middleware("http")
async def blacklist_middleware(request: Request, call_next):
    client_ip = request.client.host

    if client_ip in BLACKLIST:
        logger.warning(f"? 拦截黑名单IP: {client_ip}")
        return JSONResponse(
            status_code=403,
            content={"detail": "Access denied"}
        )

    return await call_next(request)

请注意，生产环境中切勿将IP列表硬编码在代码中。推荐将黑名单数据存储在Redis或配置中心，支持动态热更新。当遭遇攻击时，只需更新外部存储即可实时生效，无需重启应用服务。

实战四：多功能合一的高效中间件

将日志、监控、安全等功能整合进一个中间件，可以最大化代码效率，实现统一管理。

import time
from fastapi import Request
from fastapi.responses import JSONResponse
import logging

logger = logging.getLogger(__name__)
BLACKLIST = set()  # 从配置文件读取

@app.middleware("http")
async def unified_middleware(request: Request, call_next):
    # 1. IP 黑名单检查
    client_ip = request.client.host
    if client_ip in BLACKLIST:
        return JSONResponse(status_code=403, content={"detail": "Forbidden"})

    # 2. 开始计时
    start = time.perf_counter()

    # 3. 记录请求
    logger.info(f"[{client_ip}] → {request.method} {request.url.path}")

    # 4. 执行请求
    try:
        response = await call_next(request)
    except Exception as e:
        logger.error(f"? 异常: {e}")
        raise

    # 5. 计算耗时
    elapsed = time.perf_counter() - start

    # 6. 记录响应
    logger.info(f"[{client_ip}] ← {response.status_code} | {elapsed:.3f}s")

    # 7. 添加响应头
    response.headers["X-Process-Time"] = f"{elapsed:.3f}"

    return response

这个整合版中间件一次性集成了IP拦截、请求日志、异常捕获、性能统计和响应头注入五大核心功能。通过单一入口管理所有横切关注点，显著提升开发与运维效率。

进阶：理解多个中间件的执行顺序与堆叠

FastAPI允许注册多个中间件，它们按照“后进先出”（LIFO）的栈式顺序执行，形成洋葱模型般的包裹结构。

# 先注册 A
app.add_middleware(MiddlewareA)
# 再注册 B
app.add_middleware(MiddlewareB)
# 执行顺序：B → A → 路由 → A → B

清晰理解此顺序对中间件设计至关重要。通常，应将IP黑名单、基础认证等安全拦截型中间件注册在最外层，确保恶意请求在最早阶段被阻断，避免不必要的资源消耗。

总结：中间件在FastAPI架构中的核心价值

中间件是FastAPI框架中一个功能强大却常被忽视的组件。虽然部分功能可通过装饰器实现，但中间件的核心优势在于其全局性和统一性，无需在每个路由函数上重复添加装饰器代码。

更重要的是，中间件拥有对完整Request和Response对象的完全访问权限，其能力范围远超普通装饰器。无论是全局日志记录、API性能监控、请求速率限制、用户身份验证，还是跨域资源共享（CORS）处理，都可以通过中间件以优雅、解耦的方式实现。

因此，在规划API开发时，建议首先识别哪些逻辑是所有或大部分请求共有的。将这些公共横切关注点抽象为中间件，不仅能立即使代码结构更加清晰整洁，还能在未来问题排查、功能扩展时带来极大的便利。

编写高质量代码的目标不仅是实现功能，更是构建易于维护、便于监控的健壮系统。一个精心设计的中间件层，正是构筑此类高可用、可观测后端服务的第一道，也是最关键的一道防线。