如何为Python中嵌套JSON格式的API响应做标准类型标注？

针对复杂嵌套JSON响应的类型标注需求，以下是几种实用方案，均能让mypy或IDE正确识别数据类型：

1. 嵌套TypedDict（原生支持，无需额外库） #

TypedDict虽需拆分嵌套结构，但可通过合理组织减少冗余，完全兼容mypy。适合直接使用原始字典、不想做数据转换的场景：

from typing import TypedDict, List

# 定义嵌套子结构
class DType(TypedDict):
    e: str
    f: int

# 定义顶层响应结构
class APIResponse(TypedDict):
    a: int
    b: str
    c: List[int]
    d: DType
    g: bool

# 使用示例
def process_response(data: APIResponse) -> None:
    # mypy/IDE会识别data["d"]["e"]为str类型
    print(data["d"]["e"].upper())

data = requests.get("https://my.api/garbage").json()
process_response(data)  # mypy会检查传入字典是否符合结构

若嵌套层级极深，可配合TypeAlias复用重复结构：

from typing import TypeAlias

NestedDict: TypeAlias = dict[str, str | int]
class DeepAPIResponse(TypedDict):
    level1: NestedDict
    level2: dict[str, NestedDict]

2. Pydantic模型（推荐：类型检查+数据验证+便捷访问） #

Pydantic对嵌套结构支持极佳，自动完成字典到模型的转换，还能做数据校验，同时支持.访问属性，完美满足data.d.e的类型识别需求：

from pydantic import BaseModel
from typing import List

# 定义嵌套模型
class DModel(BaseModel):
    e: str
    f: int

class APIModel(BaseModel):
    a: int
    b: str
    c: List[int]
    d: DModel
    g: bool

# 使用示例
data = requests.get("https://my.api/garbage").json()
# 将字典转换为Pydantic模型
response = APIModel(**data)

def process_response(response: APIModel) -> None:
    # mypy/IDE会识别response.d.e为str类型
    print(response.d.e.upper())

process_response(response)

Pydantic支持extra="allow"兼容API返回的额外字段，无需严格声明所有键。

3. Dataclasses + Dacite（轻量级类型转换） #

若偏好标准库的dataclasses，可配合dacite库实现字典到dataclass的自动转换，同样支持嵌套结构：

from dataclasses import dataclass
from typing import List
from dacite import from_dict

@dataclass
class DData:
    e: str
    f: int

@dataclass
class APIResponse:
    a: int
    b: str
    c: List[int]
    d: DData
    g: bool

# 使用示例
data = requests.get("https://my.api/garbage").json()
response = from_dict(data_class=APIResponse, data=data)

def process_response(response: APIResponse) -> None:
    print(response.d.e.upper())  # 类型识别正常

方案选择建议 #

• 仅需类型标注、不做数据转换：优先用嵌套TypedDict，无额外依赖。
• 需要数据验证、便捷属性访问：优先用Pydantic，生态完善，功能全面。
• 依赖标准库dataclasses：搭配dacite实现简化转换。

内容的提问来源于stack exchange，提问作者Some Guy