浅谈 Pydantic v2 的 RootModel 与联合类型——构建多请求结构的统一入口模型

一、为什么需要统一入口模型？

在构建现代 Web 应用、智能体中间件、MCP Server 或 LangGraph Agent 时，我们经常会遇到如下问题：

• 有多种类型的请求：ping、initialize、call_tool 等。
• 每种请求有不同的字段和结构。
• 我们希望通过一个接口（API、WebSocket、SSE、LLM输入）统一接收它们，而不是拆分多个入口。

✅ 解决方案：使用 Pydantic v2 的 RootModel + 联合类型（Union）定义一个统一入口模型。

二、Pydantic v2 的 RootModel 是什么？

在 Pydantic v1 中，模型必须有多个字段。但在 v2 中新增了 RootModel，允许我们定义 只包含一个“根值”字段的模型：

from pydantic import RootModel

class IntList(RootModel[list[int]]):
    pass

data = IntList.model_validate([1, 2, 3])
print(data.root)  # 👉 [1, 2, 3]

它非常适合我们将 “一个整体数据结构” 作为模型传入，比如一段 JSON 消息。

三、结合 Union 实现多类型请求接收

在 Python 3.10+ 中，支持使用 | 表示类型联合（Union）：

PingRequest | InitializeRequest | CallToolRequest

于是我们可以这样定义一个统一入口：

class ClientRequest(
    RootModel[
        PingRequest | InitializeRequest | CallToolRequest
    ]
):
    pass

四、示例：构建一个统一入口模型

from pydantic import BaseModel, RootModel
from typing import Literal

class PingRequest(BaseModel):
    type: Literal["ping"]
    timestamp: int

class InitializeRequest(BaseModel):
    type: Literal["initialize"]
    session_id: str

class ClientRequest(RootModel[
    PingRequest | InitializeRequest
]):
    pass

五、请求动态识别和分发

json_msg = {"type": "ping", "timestamp": 123456}
request = ClientRequest.model_validate(json_msg)
payload = request.root

if isinstance(payload, PingRequest):
    print("收到 ping 请求")
elif isinstance(payload, InitializeRequest):
    print("初始化会话")

model_validate() 会自动选择匹配的模型并实例化它，放入 .root 中。

六、错误处理与验证失败示例

当没有任何模型匹配时，会抛出 ValidationError：

bad_msg = {"type": "unknown"}
ClientRequest.model_validate(bad_msg)
# ❌ 报错：Union 中没有任何模型匹配

七、实际应用场景

八、扩展用法：结合 FastAPI

from fastapi import FastAPI, Body

app = FastAPI()

@app.post("/client")
def handle_request(req: ClientRequest = Body(...)):
    payload = req.root
    return payload.model_dump()

九、总结与最佳实践

• RootModel 非常适合仅封装一个值的情况。
• 联合类型配合 model_validate 实现了自动路由判断。
• .root 提供了访问底层对象的方式，方便调度转发。
• 对于多类型请求场景，是非常优雅且易维护的解决方案。

🔚 写在最后

Pydantic v2 的设计使得我们可以用更简洁的方式组织代码逻辑，特别是在面对多类型数据结构的智能系统中，构建“统一入口”不再是痛点。

这一特性是构建现代 LLM 智能体系统、LangGraph 节点调度、或者 Web 多端统一接口的强力工具。