FastAPI 直接使用 Request 对象：绕过常规参数声明的底层访问方式

FastAPI 通常通过类型标注自动完成请求数据的提取、校验、转换与 OpenAPI 文档生成，但在某些场景（如获取客户端 IP）必须直接访问 Starlette 的 Request 对象。本文基于 FastAPI 官方文档的 直接使用 Request 章节，结合仓库源码与测试用例，讲解 Request 的注入机制、其与正常声明参数的混合使用方式，以及直接访问时失去校验与文档生成的边界条件。

为什么需要直接使用 Request 对象

在 FastAPI 中，你通常通过声明类型来获取请求的各部分数据，例如：

• 从路径（Path）中获取参数；
• 从请求头（Headers）中获取参数；
• 从 Cookie 中获取参数；
• 等等。

通过这样做，FastAPI 会自动对这些数据进行校验、转换，并自动生成 API 文档（通过 OpenAPI，用于自动生成的 API 交互界面）。

但有些情况下，你需要直接访问 Request 对象本身，而不是其中被声明出来的某个字段。

Request 对象详解：它来自 Starlette

FastAPI 底层本质上是 Starlette，在其之上封装了多层工具。因此当你需要时，可以直接使用 Starlette 的 Request 对象——FastAPI 只是把它直接暴露出来，作为对开发者的便利。

这一点在源码中体现得非常直接：fastapi/requests.py 整个文件只有两行导出，Request 和 HTTPConnection 都原样来自 Starlette：

from starlette.requests import HTTPConnection as HTTPConnection  # noqa: F401
from starlette.requests import Request as Request  # noqa: F401

也就是说，你可以从 fastapi 导入 Request，也可以等价地写 from starlette.requests import Request，两者指向同一个类。

但由此带来一个重要的边界：如果你直接从 Request 对象上取数据（例如读取其 Body），这些数据不会被 FastAPI 校验、转换，也不会被写入 OpenAPI 文档（即不会出现在自动生成的 API 界面中）。而同一路径操作函数里其他正常声明的参数（例如用 Pydantic 模型声明的 Body）仍然会被正常校验、转换和标注。

直接使用 Request 对象：获取客户端地址的完整示例

假设你想在路径操作函数（path operation function）中访问客户端的 IP 地址/主机地址，这就需要直接访问 Request：

from fastapi import FastAPI, Request

app = FastAPI()


@app.get("/items/{item_id}")
def read_root(item_id: str, request: Request):
    client_host = request.client.host
    return {"client_host": client_host, "item_id": item_id}

对应的仓库示例文件见 docs_src/using_request_directly/tutorial001_py310.py。

只需声明一个类型为 Request 的路径操作函数参数，FastAPI 就会知道应当把 Request 实例传入该参数。

提示：注意这个示例中除了 Request 参数之外，还额外声明了一个路径参数 item_id。该路径参数会被照常提取、校验、转换为指定类型，并用 OpenAPI 标注。同理，你可以像往常一样声明任何数量的其他参数，同时额外获得 Request 实例。

测试用例如何验证这一行为

仓库中的测试 tests/test_tutorial/test_using_request_directly/test_tutorial001.py 验证了两点：

1. 请求 /items/foo 返回 {"client_host": "testclient", "item_id": "foo"}——client_host 直接从 Request 对象读取（测试客户端下主机名为 testclient），而 item_id 走正常参数声明路径；
2. 生成的 OpenAPI 文档中，/items/{item_id} 的 parameters 只包含 item_id 这一个路径参数，request 参数不会出现在 OpenAPI 中——这印证了上文"直接从 Request 取的数据不进入文档"的边界。

源码解析：FastAPI 如何识别并注入 Request 参数

从源码结构看，Request 参数的识别发生在依赖分析阶段。fastapi/dependencies/utils.py 中的 add_non_field_param_to_dependency 负责对"非字段类"参数类型做特殊分类：

if lenient_issubclass(type_annotation, Request):
    dependant.request_param_name = param_name
    return True
elif lenient_issubclass(type_annotation, WebSocket):
    dependant.websocket_param_name = param_name
    return True
elif lenient_issubclass(type_annotation, HTTPConnection):
    dependant.http_connection_param_name = param_name
    return True

可以看到，除了 Request，WebSocket、HTTPConnection、Response、BackgroundTasks、SecurityScopes 等类型也走同一套"特殊参数注入"通道（Request 与 HTTPConnection 的兼容处理由 lenient_issubclass 完成，因此字符串化的类型标注也可以工作）。

在解析签名时，fastapi/dependencies/utils.py 会拦截这类特殊类型，避免把它们误当成 Query 参数或 Body 字段：

# Handle non-param type annotations like Request
if depends is None and lenient_issubclass(
    type_annotation,
    (
        Request,
        WebSocket,
        HTTPConnection,
        Response,
        StarletteBackgroundTasks,
        SecurityScopes,
    ),
):
    assert field_info is None, (
        f"Cannot specify FastAPI annotation for type {type_annotation!r}"
    )

真正执行注入的位置在依赖求解时：若 dependant.request_param_name 已设置且当前连接对象是 Request 实例，FastAPI 就把该实例直接绑定到对应的函数参数名上，而不是走"提取 → 校验 → 转换"的常规字段流程。这也是为什么 request.client.host 这类访问不做任何数据校验。

请求处理链的起点则在 fastapi/routing.py 的 APIRoute._solve_dependencies 中——每个请求都会先构造 Request(scope, receive, send) 实例，再交给 solve_dependencies 完成上述参数绑定；路径操作函数本身则以 app(request: Request) -> Response 的形式接收这个实例（见 fastapi/routing.py）。

实践建议与边界总结

方式	校验与转换	OpenAPI 文档	适用场景
声明类型参数（路径/Query/Header/Cookie/Body）	自动完成	自动生成	绝大多数业务参数
直接使用 Request 参数	不校验、不转换	不出现在文档中	获取客户端地址、原始头、原始 Body 等元信息
Request 与声明参数混用	各自独立处理	仅声明参数入文档	示例中的 IP 获取 + 业务参数组合

• 需要客户端 IP、主机名、请求 URL 等"连接层"信息时，request.client.host 是最直接的方式；
• 不要把需要校验的业务数据从 Request 里手动解析，而应优先声明为带类型的参数，以保留 FastAPI 的校验、转换与文档能力；
• 完整的 Request 对象 API（Body、Headers、Cookies 等属性）请参阅 Starlette 官方文档的 Request 章节（FastAPI 文档在 Request 文档说明 一节中即指向该处）；
• 更多语言版本的同一主题可参考 英文版文档，配套示例与测试分别位于 docs_src/using_request_directly/ 与 tests/test_tutorial/test_using_request_directly/ 目录，可作为运行与验证的起点。