FastAPI TestClient GET请求传参类型错误原因及最佳实践

在使用FastAPI的TestClient时，遇到了一个类型检查异常：直接在client.get()中传入字典参数时正常运行，将字典赋值给变量后再传入则触发类型不兼容报错。

可行示例 #

from fastapi.testclient import TestClient
from fastapi import status

def my_func(client: TestClient) -> None:
   response = client.get(
       app.url_path_for("v1-my-endpoint"),
       params={"xx": "11", "yy": "22"}
   )
   assert response.status_code == status.HTTP_200_OK

不可行示例 #

from fastapi.testclient import TestClient
from fastapi import status

def my_func(client: TestClient) -> None:
   my_params={"xx": "11", "yy": "22"}
   response = client.get(
       app.url_path_for("v1-my-endpoint"),
       params=my_params
   )
   assert response.status_code == status.HTTP_200_OK

报错信息 #

error: Argument "params" to "get" of "TestClient" has incompatible type "Dict[str, object]"; expected "Union[QueryParams, Mapping[str, Union[Union[str, int, float, bool, None], Sequence[Union[str, int, float, bool, None]]]], List[Tuple[str, Union[str, int, float, bool, None]]], Tuple[Tuple[str, Union[str, int, float, bool, None]], ...], str, bytes, None]"  [arg-type]

原因分析 #

这是Python类型检查器（如mypy）的推断逻辑差异导致的：

• 直接传入字面量字典时，类型检查器能精准推断出字典值的具体类型为str，完全匹配TestClient.get()方法中params参数的类型要求。
• 当把字典赋值给变量my_params时，若无明确类型注解，类型检查器会默认将其推断为Dict[str, object]——它会取所有值的公共父类型作为值类型，而object无法匹配params期望的更具体类型（str/int/float/bool/None或它们的序列），因此触发类型不兼容错误。

推荐传参方式 #

1. 添加明确类型注解
   给变量指定具体类型，让类型检查器正确识别参数类型：

   from fastapi.testclient import TestClient
   from fastapi import status
   
   def my_func(client: TestClient) -> None:
       # 针对纯字符串参数的注解
       my_params: dict[str, str] = {"xx": "11", "yy": "22"}
       # 若参数包含多种类型，可使用Union
       # my_params: dict[str, str | int | float | bool | None] = {"xx": "11", "yy": 22}
       response = client.get(
           app.url_path_for("v1-my-endpoint"),
           params=my_params
       )
       assert response.status_code == status.HTTP_200_OK
   

   也可以直接使用FastAPI依赖的QueryParams类型：

   from starlette.datastructures import QueryParams
   
   my_params: QueryParams = {"xx": "11", "yy": "22"}
   

2. 直接传字面量字典
   如果参数结构简单，直接在client.get()的params参数中传入字面量字典，无需额外变量，这种方式不会触发类型推断问题。

3. 使用元组列表格式
   若需要同一个键对应多个值的灵活传参，可使用元组列表格式，类型检查器也能正确识别：

   my_params = [("xx", "11"), ("yy", "22")]
   response = client.get(app.url_path_for("v1-my-endpoint"), params=my_params)
   

内容的提问来源于stack exchange，提问作者Matheus Schaly