接口版本控制应显式暴露在url路径中（如/v1/users），避免用查询参数；旧版至少保留6个月；响应结构须固定，字段缺失输出NULL而非省略；get接口必须无副作用、权限校验显式且严格；错误响应需统一格式与状态码语义。
接口版本控制必须显式暴露在 URL 或 Header 里
客户端依赖的是可预测的行为，不是你的代码有没有改。一旦 GET /users 的返回字段悄悄变，前端就可能炸——而且炸得无声无息。
推荐方案：用 URL 路径做主版本标识，比如 /v1/users、/v2/users。Header 方案（如 Accept: application/vnd.myapi.v2+json）适合灰度或内部服务，但对第三方不友好，调试和缓存都容易出错。
- 别用查询参数（
?version=2）——CDN 和浏览器缓存会把/users?version=1和/users?version=2当作同一资源 - 旧版接口至少保留 6 个月，期间只修复安全问题，不加新字段
- 所有新版接口上线前，必须写清楚「哪些旧字段被移除/重命名/类型变更」，并提供迁移对照表
响应结构必须固定，字段缺失用 null 而非省略
python 后端常用 pydantic 或 dataclass 做序列化，但默认行为常踩坑：字段为 None 就不输出。客户端如果按 key 存在与否做逻辑分支，一升级就挂。
例如 UserResponse 模型里 phone: Optional[str] = None，必须强制让它在 JSON 中输出 "phone": null，而不是直接删掉这个 key。
立即学习“Python免费学习笔记（深入）”；
-
pydantic.BaseModel加配置：class Config: exclude_unset = False; exclude_defaults = False; exclude_none = False - 用
orjson序列化时，别依赖默认的default回调去过滤空值 - 测试要点：手动构造带
None值的模型实例，检查 JSON 输出是否含null字段
不要在 GET 接口里偷偷改副作用或放宽权限校验
稳定不只是字段不变，更是语义不变。GET /orders?status=cancelled 看起来是查数据，但如果某次更新让它顺手把状态为 cancelled 的订单标记为 archived，前端刷新页面就可能发现订单“自己消失了”。
更隐蔽的问题是权限松动：v1 版本要求用户只能查自己的订单，v2 为了“方便调试”加了 admin_only=False 默认开关，结果普通用户也能看到别人订单 ID —— 字段没变，但数据边界塌了。
- 所有 GET 接口必须满足 http 语义：无副作用、可缓存、幂等
- 权限逻辑不能藏在视图函数里，要抽成独立的
check_order_access(user, order_id)并在每个版本中显式调用 - 用类型提示约束参数：比如
user_id: Annotated[str, Path(Regex=r'^u_[a-z0-9]{8}$')]，避免字符串拼接导致越权
错误码和错误结构比成功响应更需要契约
成功时字段少点还能凑合，但错误响应一乱，客户端连该重试还是跳转登录页都分不清。常见错误如 400 Bad Request 返回 {"Error": "invalid email"}，而 401 Unauthorized 却返回 {"message": "Token expired"}，前端就得写两套解析逻辑。
统一错误格式不是为了好看，是为了让客户端能靠 status_code + error_code 做精确分支处理。
- 定义最小错误结构：
{"error_code": "INVALID_INPUT", "message": "...", "details": {...}}，所有异常路径都走这个模板 - HTTP 状态码必须严格对应语义：
400是客户端数据错，401是认证失败，403是权限不足，别全扔400 - 用
try/except捕获底层异常（如ValidationError、ValueError）后，必须映射到预定义的error_code，不能直接抛原始异常信息
事情说清了就结束。最常被忽略的其实是错误响应的稳定性——它不像字段变化那么直观，但一旦松动，客户端容错成本会指数级上升。