调用第三方API是后端开发的家常便饭。拿到响应之后，通常我们随手data['result']['user_info']['nickname']就往下写。问题在于，如果API返回的字段名改了、嵌套结构变了、或者某个字段偶尔不返回，代码就会在运行时炸掉。而且这类错误往往要等到请求走通了才会暴露，测试覆盖不全的话直接进生产环境。
Python的类型系统在过去几个版本里有了实质性的增强。TypedDict让你能精确描述字典的结构，Protocol让你能定义接口而不依赖继承。配合mypy做静态检查，可以在写代码阶段就发现字段名拼写错误、类型不匹配和缺少必要字段等问题。这篇文章通过构建一个完整的API响应处理模块，把这套组合拳的用法和实际价值讲清楚。
一、问题场景：处理一个用户中心的API响应
假设对接一个用户中心服务，返回的用户信息结构大致如下：
{
"code": 0,
"message": "success",
"data": {
"user_id": 1024,
"basic_info": {
"nickname": "张三",
"avatar_url": "https://cdn.example.com/avatars/1024.jpg",
"phone": "13800138000"
},
"account_status": "active",
"created_at": "2024-01-15T10:30:00Z",
"tags": ["vip", "verified"]
}
}需求是从这个嵌套结构里提取用户的昵称、头像、手机号和标签列表，然后组装成业务系统自己的格式。传统的dict写法：
def extract_user_info(response: dict) -> dict:
data = response.get('data', {})
basic = data.get('basic_info', {})
return {
'nickname': basic.get('nickname', '未知用户'),
'avatar': basic.get('avatar_url', ''),
'phone': basic.get('phone', ''),
'tags': data.get('tags', []),
}这段代码能跑，但有三个隐患：一是response的结构没有约束，随便传一个dict进来都不会报错；二是字段名拼错了（比如avatar_url写成了avata_url）静态检查发现不了；三是返回值也是裸dict，下游调用方不知道里面有什么字段。下面用TypedDict和Protocol一步步改进。
二、用TypedDict定义API响应的结构
TypedDict允许你精确描述一个字典应该包含哪些键，每个键对应什么类型。从最内层开始定义：
from typing import TypedDict, Literal
class BasicInfo(TypedDict):
nickname: str
avatar_url: str
phone: str
class UserData(TypedDict):
user_id: int
basic_info: BasicInfo
account_status: Literal['active', 'inactive', 'banned']
created_at: str
tags: list[str]
class ApiResponse(TypedDict):
code: int
message: str
data: UserData现在提取函数的参数签名可以精确到具体的结构：
def extract_user_info(response: ApiResponse) -> dict:
data = response['data']
basic = data['basic_info']
return {
'nickname': basic['nickname'],
'avatar': basic['avatar_url'],
'phone': basic['phone'],
'tags': data['tags'],
}这里的变化是改用response['data']而不是response.get('data')。因为TypedDict声明了data字段必须存在，所以不需要防御性读取。如果你不小心写成了basic['avata_url']（少了一个r），mypy会直接报错：TypedDict "BasicInfo" has no key 'avata_url'。这个检查发生在你保存代码的那一刻，不需要等到运行时。
三、处理可选字段和缺失值
实际情况里，有些字段可能不总是存在。比如用户可能没设置手机号，phone字段可能返回空字符串或者干脆不返回。TypedDict支持total=False来标记所有字段可选，也可以单独标记：
from typing import NotRequired
class BasicInfo(TypedDict):
nickname: str
avatar_url: str
phone: NotRequired[str] # 可能不存在这样一来，basic['phone']在使用时必须处理None的情况。更好的做法是在提取函数里做实际处理：
def safe_get_basic_info(basic: BasicInfo) -> dict:
phone = basic.get('phone', '') # 有默认值的读取
return {
'nickname': basic.get('nickname', '未知用户'),
'avatar': basic.get('avatar_url', ''),
'phone': phone if phone else '',
}注意这里用.get()是安全的，因为TypedDict只描述结构，运行时它还是普通的dict。静态检查会保证你传递的参数符合BasicInfo类型，从而杜绝了绝大多数字段缺失导致的KeyError。
四、用Protocol定义可插入的响应处理器
项目里通常不会只对接一个API。不同的API响应格式不同，但处理流程相似：拿到原始响应、提取关键字段、转换成内部格式。我们可以用Protocol定义一个接口，让每个API的处理器都遵循同一个契约。
from typing import Protocol, Any
class ApiResponseHandler(Protocol):
"""定义响应处理器的协议"""
def can_handle(self, raw: dict) -> bool:
"""判断这个处理器能否处理给定的原始响应"""
...
def parse(self, raw: dict) -> dict:
"""将原始响应转换为内部格式"""
...
def validate(self, raw: dict) -> bool:
"""校验响应是否完整"""
...Protocol是Python类型系统中的结构化子类型。任何一个类只要实现了上面三个方法，它就是ApiResponseHandler类型，不需要显式继承。这比抽象基类更灵活。
实现一个用户服务的处理器：
class UserProfileHandler:
def can_handle(self, raw: dict) -> bool:
return raw.get('code') == 0 and 'data' in raw
def validate(self, raw: dict) -> bool:
try:
data = raw['data']
return all(k in data for k in ('user_id', 'basic_info'))
except (KeyError, TypeError):
return False
def parse(self, raw: dict) -> dict:
data = raw['data']
basic = data.get('basic_info', {})
return {
'uid': data['user_id'],
'name': basic.get('nickname', '未知用户'),
'avatar': basic.get('avatar_url', ''),
'phone': basic.get('phone', ''),
'status': data.get('account_status', 'unknown'),
'tags': data.get('tags', []),
}再实现一个产品服务的处理器：
class ProductInfoHandler:
def can_handle(self, raw: dict) -> bool:
return 'item_list' in raw
def validate(self, raw: dict) -> bool:
return isinstance(raw.get('item_list'), list)
def parse(self, raw: dict) -> dict:
items = raw.get('item_list', [])
return {
'products': [
{
'id': item.get('item_id'),
'title': item.get('title', ''),
'price': float(item.get('price', 0)),
}
for item in items
]
}核心的分发逻辑：
class ResponseDispatcher:
def __init__(self):
self.handlers: list[ApiResponseHandler] = []
def register(self, handler: ApiResponseHandler) -> None:
self.handlers.append(handler)
def dispatch(self, raw: dict) -> dict:
for handler in self.handlers:
if handler.can_handle(raw):
if not handler.validate(raw):
raise ValueError(f"响应校验失败: {handler.__class__.__name__}")
return handler.parse(raw)
raise NotImplementedError("没有找到合适的处理器")用list[ApiResponseHandler]作为类型注解，mypy会检查你传入的每个handler是否符合协议。如果某个处理器漏掉了validate方法，静态检查就能发现，不用等到运行时。
五、集成到实际项目中的完整示例
把上面的组件串起来，写一个完整的请求流程：
import requests
from typing import Any
class ApiClient:
def __init__(self, base_url: str, dispatcher: ResponseDispatcher):
self.base_url = base_url
self.dispatcher = dispatcher
def call(self, endpoint: str, params: dict[str, Any] | None = None) -> dict:
url = f"{self.base_url}{endpoint}"
resp = requests.get(url, params=params or {}, timeout=10)
resp.raise_for_status()
raw = resp.json()
return self.dispatcher.dispatch(raw)
# 组装
dispatcher = ResponseDispatcher()
dispatcher.register(UserProfileHandler())
dispatcher.register(ProductInfoHandler())
client = ApiClient("https://api.example.com", dispatcher)
# 调用
try:
user_info = client.call("/v1/user/profile", {"user_id": 1024})
print(user_info) # {'uid': 1024, 'name': '张三', ...}
except ValueError as e:
print(f"数据处理失败: {e}")
except requests.RequestException as e:
print(f"请求失败: {e}")整个链路的好处在于：每个组件的输入输出都有类型约束，字段路径的拼写错误会被mypy在开发阶段抓到，新增一个API只需要实现一个新Handler并注册，不需要改动已有代码。
六、让mypy检查生效
写好了类型注解，还需要让它们真正发挥作用。在项目根目录新建mypy.ini或pyproject.toml：
[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
warn_unused_ignores = true然后运行mypy your_module.py。如果代码里有用basic['avata_url']这种拼写错误，或者传了类型不匹配的参数，mypy会直接报错并指出具体位置。
把mypy集成到CI/CD流程里，每次提交代码都自动运行，就能确保类型安全持续有效。刚开始可能会觉得报错多多，但修完一轮之后代码的健壮性会明显上升。
七、TypedDict和Protocol的适用边界
这两个工具不是银弹。什么时候该用？
- 用TypedDict：当你处理的是纯数据载体（主要是JSON序列化后的字典），不需要方法，只想描述数据结构。API响应、配置文件、数据库查询结果都是典型场景。
- 用Protocol：当你需要定义一组方法约定，且希望用结构化子类型（而不是显式继承）来约束。处理器、适配器、策略模式都很适合。
- 继续用dataclass：如果你需要可变状态、默认值逻辑、或者和ORM集成，
dataclass仍然是更合适的选择。TypedDict本质是dict，dataclass是真正的类。
在我的实践中，TypedDict主要用于API边界处的数据描述，进入内部业务逻辑后往往转换成更丰富的领域对象。这个边界分层很清晰，不会混淆。
八、总结
Python的类型系统已经从一个简单的注解工具变成了能在编译期发现大量错误的实用体系。对于经常和外部数据打交道的后端代码来说，TypedDict给出了一种轻量的“结构化字典”描述方式，Protocol让依赖反转不再需要显式继承。两者结合，可以在不对现有代码架构做大改动的情况下，显著提升代码的可靠性。
如果你手头的项目里有很多dict['some_key']这样的访问，不妨从最核心的数据流开始，用TypedDict定义格式，然后用mypy跑一遍。那些之前藏在运行时里的字段名拼写错误和结构假设错误，会在几分钟内全部浮出水面。
