类型检测工具函数需构建可验证、可审计、可嵌入业务流程的参数安全边界，核心是将类型约束转化为运行时防护能力且不破坏接口契约；其职责限于校验结构、拒绝非法值、返回清晰错误上下文，不处理业务逻辑或替代安全机制；应分层封装如 safe_int、safe_email、safe_enum，并与 Pydantic 协同互补；在 FastAPI 的 Depends 或中间件中调用，失败统一返回 422 并附 field-level 错误码；每次检测失败须记录原始输入、函数名、时间、调用方信息，支持告警与 OpenTelemetry 上报。
类型检测工具函数封装不是简单加个 type() 判断，而是要构建可验证、可审计、可嵌入业务流程的参数安全边界。核心在于把类型约束转化为运行时防护能力，同时不破坏原有接口契约。
明确类型检测的职责边界
类型检测函数只负责三件事：校验输入是否符合预设结构、拒绝非法值、返回清晰错误上下文。它不处理业务逻辑，也不替代权限或加密机制。
- 接受字符串但要求是 ISO 8601 格式时间 → 用 datetime.fromisoformat() 尝试解析，捕获 ValueError
- 接收用户 ID 但必须为正整数 → 先用 isinstance(x, int)，再检查 x > 0
- 传入 JSON 字符串需确保可反序列化且含必要字段 → json.loads() 后校验 key 是否存在，不用 try-except 吞掉所有异常
封装成可复用的安全检测函数
避免每个接口都写重复校验逻辑。推荐按“类型+语义”分层封装，例如：
- safe_int(value, min_val=1, max_val=2**31-1)：带范围限制的整型校验，越界返回 None 或抛出 ValueError
- safe_email(value)：用正则 + 长度 + Unicode 支持做基础过滤，不依赖第三方库做完整 RFC 验证
- safe_enum(value, allowed=('pending', 'done', 'failed'))：严格白名单比字符串 in 判断更可靠，支持大小写归一化选项
与 Pydantic 或类型检查器协同工作
静态类型注解（如 Pydantic v2 的 BaseModel）和运行时检测函数应互补而非重叠：
- Pydantic 负责请求体整体结构校验和字段级类型转换
- 自定义检测函数处理 Pydantic 不覆盖的场景：比如某字段是 str，但实际需满足内部系统编码规则（如以 “ORG-” 开头的租户 ID）
- 在 FastAPI 的 Depends 或中间件中调用检测函数，失败时统一返回 422 并附带 field-level 错误码，便于前端定位
嵌入审计与可观测性链路
每次检测失败都应留下可追溯痕迹：
- 记录原始输入、检测函数名、触发时间、调用方 IP 或 trace_id
- 对高频失败参数（如连续 5 次传入非法手机号）自动触发告警，而非仅记日志
- 将检测结果作为 OpenTelemetry 的 span attribute 上报，用于分析各接口的入参健康度
