类型标注和 Pydantic：Python 的类型只是标签，Pydantic 让它在边界上生效

record HostGc(
    @NotNull String host,
    @PositiveOrZero int pauses,
    Double maxMs) {}

HostGc h = mapper.readValue(json, HostGc.class);
validator.validate(h);   // 另一个步骤

def parse(raw: dict) -> float:
    return raw["max_ms"] * 2

parse({"max_ms": "244.05"})
# → '244.05244.05'  字符串被“乘”了两次

def double(x: int) -> int:
    return x * 2
double("ab")      # → 'abab'，标注没拦住

class HostGc(BaseModel):
    host: str
    pauses: int = Field(0, ge=0)
    max_ms: float | None = None

h = HostGc(**raw)
h.max_ms * 2      # 488.1，这里一定是 float

• Python 运行时不看类型标注。double("ab") 返回 'abab'，实测。标注只给人、IDE 和 mypy 这类静态检查工具看。
• 外部数据天然是字符串或松散的 JSON：查询串全是字符串，日志代理可能把数字写成字符串。光有标注，什么都拦不住。
• 手写 if not isinstance(...) 校验又长又容易漏，而且错误一个一个报，用户要改好几轮。
• 缺的那一块就是这页的精华：在数据进入系统的边界，按标注一次性转换并校验，之后的代码只和“已经合格的对象”打交道。

class HostGc(TypedDict):
    host: str
    max_ms: float

@dataclass
class HostGc:
    host: str
    max_ms: float | None = None

class HostGc(BaseModel):
    host: str
    max_ms: float | None = None

class HostGc(msgspec.Struct):
    host: str
    max_ms: float | None = None

本页学：类型标注本身是什么、Pydantic 怎么把它变成校验器、宽松模式和严格模式、FastAPI 在入口和出口怎么用它。选择规则：边界用 Pydantic，内部用 dataclass。FastAPI、站 03 的结构化输出、站 07 的 MCP SDK 都建在 Pydantic 上。

from fastapi import FastAPI, Query
from pydantic import BaseModel, ConfigDict, Field

class HostGc(BaseModel):                          # ≈ 一个 DTO
    model_config = ConfigDict(extra="forbid")    # 多出来的字段直接报错
    host: str
    pauses: int = Field(0, ge=0)
    max_ms: float | None = None
    avg_ms: float | None = None
    error: str | None = None

class GcSummary(BaseModel):
    service: str
    minutes: int
    hosts: list[HostGc]

app = FastAPI()

@app.get("/gc/summary", response_model=GcSummary)
async def gc_summary(service: str, minutes: int = Query(10, ge=1, le=60)):
    raw = {"host": "order-01", "pauses": "60", "max_ms": "244.05", "avg_ms": 26.1}  # 日志代理返回的原始字典
    return {                                     # 故意多带一个内部字段
        "service": service, "minutes": minutes,
        "hosts": [HostGc(**raw), HostGc(host="order-04", error="timeout 1s")],
        "agent_token": "s3cr3t",
    }

@app.get("/gc/leak")                             # 没写 response_model
async def gc_leak(service: str):
    return {"service": service, "agent_token": "s3cr3t"}

@app.get("/gc/bad", response_model=GcSummary)
async def gc_bad(service: str):
    return {"service": service, "minutes": "ten", "hosts": []}

import warnings; warnings.filterwarnings("ignore")
from fastapi.testclient import TestClient
from models import app
c = TestClient(app, raise_server_exceptions=False)
for p in ("/gc/summary?service=order&minutes=10", "/gc/summary?service=order&minutes=0",
          "/gc/summary?service=order&minutes=abc", "/gc/summary?minutes=10",
          "/gc/leak?service=order", "/gc/bad?service=order"):
    r = c.get(p); print(p, r.status_code, r.text[:230])

$ uv run try_models.py
/gc/summary?service=order&minutes=10 200 {"service":"order","minutes":10,"hosts":[{"host":"order-01","pauses":60,"max_ms":244.05,"avg_ms":26.1,"error":null},{"host":"order-04","pauses":0,"max_ms":null,"avg_ms":null,"error":"timeout 1s"}]}
/gc/summary?service=order&minutes=0 422 {"detail":[{"type":"greater_than_equal","loc":["query","minutes"],"msg":"Input should be greater than or equal to 1","input":"0","ctx":{"ge":1}}]}
/gc/summary?service=order&minutes=abc 422 {"detail":[{"type":"int_parsing","loc":["query","minutes"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"abc"}]}
/gc/summary?minutes=10 422 {"detail":[{"type":"missing","loc":["query","service"],"msg":"Field required","input":null}]}
/gc/leak?service=order 200 {"service":"order","agent_token":"s3cr3t"}
/gc/bad?service=order 500 Internal Server Error

• 看第一行："pauses": "60" 变成了 60，"244.05" 变成了 244.05；JSON 里没有 agent_token，被 response_model 过滤掉了。
• 看三个 422 的 loc 都以 "query" 开头，告诉调用方是查询串里哪个参数错了；input 是原始字符串 "0"，证明它在转换之前就是字符串。
• 看没写 response_model 的 /gc/leak，内部字段原样漏了出去；/gc/bad 返回值不合格，是 500 而不是 422。

实测 本机 uv 0.13.7、CPython 3.13.18、FastAPI 0.162.2、Pydantic 2.14.3，输出逐字复制。

不是坑的一条：模型里写 errors: list[str] = [] 是安全的，Pydantic 会给每个实例复制一份默认值，a.errors.append("x") 后 b.errors 仍是 [] 实测。这和上一页函数默认参数的坑 5正好相反，别把两个规则记混。

class HostGc(BaseModel):
    max_ms: float | None = None

    @field_validator("max_ms", mode="before")
    @classmethod
    def strip_unit(cls, v):
        if isinstance(v, str) and v.endswith("ms"):
            return v[:-2]           # "244.05ms" → "244.05"
        return v