参数校验需在业务入口显式进行，严格检查必填字段、类型、范围及嵌套结构，配合结构化错误响应与统一错误码管理，并注意query/form编码、字段名大小写、时间格式等细节。
参数校验失败不是接口“坏了”，而是它在明确告诉你：你给的数据不符合约定。 直接跳过校验或硬塞默认值，往往导致下游逻辑崩溃、数据错乱，甚至安全漏洞。关键是要让校验既严格又可控，且错误信息能准确定位问题源头。
用 raise ValueError 主动拦截非法参数
被动等框架报错（比如 400 Bad Request）太晚，也难定位是哪一字段出问题。应在业务逻辑入口处就做显式判断：
- 检查必填字段是否存在：
if "user_id" not in data:→raise ValueError("缺少 user_id 字段") - 验证类型是否匹配：
if not isinstance(data.get("age"), int):→raise ValueError("age 必须为整数") - 限制数值范围：
if data.get("timeout") 300:→raise ValueError("timeout 应在 1–300 秒之间")
这种写法比依赖 try/except 更轻量，错误堆栈直接指向校验点，调试时一眼看到哪行断的。
避免 JSON 解析后丢失原始结构
前端传来的 JSON 如果含嵌套对象或空数组，Python 解析后可能变成 None 或空字典，导致后续取值报 KeyError 或 AttributeError：
立即学习“Python免费学习笔记（深入）”；
- 不要直接写
data["profile"]["email"]—— 先确认"profile"是 dict 类型且非空 - 用
data.get("profile", {})替代data["profile"]，再链式调用.get("email") - 对嵌套结构做深度校验：比如
if not isinstance(data.get("tags"), list):→raise ValueError("tags 必须为列表")
尤其注意前端可能传字符串 "null" 或空字符串 ""，它们不是 Python 的 None，但语义上等价于缺失。
区分 HTTP 状态码与业务错误码
校验失败统一返回 400 没问题，但仅靠状态码无法告诉前端“是用户名格式错，还是邮箱已被注册”。必须配合结构化错误体：
- 不要只返回
{"error": "参数错误"}—— 缺少上下文 - 推荐格式：
{"code": "4002", "message": "邮箱格式不合法", "field": "email"}，其中4002是预定义的业务码（如 4=参数类，002=邮箱校验失败） - 用
Enum管理所有错误码，避免散落各处的魔数；同时记录日志时带上完整请求体（脱敏后），方便回溯
很多团队卡在这一步：校验逻辑写了，但错误响应没设计好，前端只能弹“未知错误”，最后靠抓包猜问题。
校验位置容易被忽略的三个细节
最常出问题的地方，往往不在主流程里：
-
query string和form data的编码差异：URL 中的中文若未urlencode，Pythonrequest.args可能拿到乱码或截断值 - 大小写敏感字段名：前端传
UserId，后端按user_id取，结果为None—— 建议统一转小写下划线，或在校验层做映射 - 时间字段格式混乱：
"2025-01-01"、"2025/01/01"、"Jan 1, 2025"都可能被传入，别指望datetime.fromisoformat()全兼容，先标准化再解析
参数校验不是越严越好，而是要和接口契约对齐；也不是写一次就完事，每次新增字段、修改规则，都得同步更新校验逻辑和错误码文档。
