restful 规范是设计 python api 的关键实践，需用名词复数命名资源、严格匹配 http 方法语义、用状态码真实反映结果、统一响应格式、前置版本控制与结构化错误处理。
设计 Python API 接口时，遵循 RESTful 规范不是可选项，而是提升可维护性、协作效率和系统扩展性的关键实践。核心在于用 HTTP 方法表达操作意图，用 URL 表达资源，用状态码表达结果，而非把所有逻辑塞进 POST。
资源命名：用名词，复数形式，不带动词
URL 应指向“谁”或“什么”，而不是“做什么”。避免 /getUser、/deleteOrder 这类动词化路径。正确做法是统一用复数名词表示资源集合：
- /users —— 用户集合（支持 GET/POST）
- /users/123 —— ID 为 123 的具体用户（支持 GET/PATCH/DELETE）
- /orders —— 订单集合
- /orders/456/items —— 订单 456 下的子资源（嵌套合理即可，避免过深）
不推荐使用下划线或驼峰，全部小写 + 连字符更通用，如 /api/v1/user-profiles 不如 /api/v1/user-profiles（保持一致即可），但 /api/v1/userProfiles 或 /api/v1/user_profiles 易引发客户端解析歧义，建议统一用 - 分隔。
HTTP 方法语义必须严格对应操作类型
每个方法有明确约定，不可混用。后端实现需与之对齐，否则前端无法可靠预测行为：
立即学习“Python免费学习笔记（深入）”；
- GET —— 安全、幂等，只读，用于获取资源或列表（可带查询参数过滤、分页）
-
POST —— 非幂等，用于创建新资源（返回
201 Created+Location头） - PATCH —— 部分更新（如只改邮箱），幂等，推荐 JSON Patch 或简单字段对象
- PUT —— 全量替换（客户端需提供完整资源表示），幂等；实际项目中 PATCH 更常用
-
DELETE —— 删除资源，幂等；成功返回
204 No Content（无响应体）
例如：修改用户昵称不应用 POST /users/123/update-nickname，而应 PATCH /users/123，请求体为 {"nickname": "newname"}。
响应格式统一，状态码真实反映结果
不要所有接口都返回 200 OK 再靠 body 里的 code 字段判断成败。HTTP 状态码是协议层契约：
- 成功创建 →
201 Created（含Location: /users/789） - 成功更新 →
200 OK或204 No Content（无返回体时） - 资源不存在 →
404 Not Found（不是200+{"error": "not found"}） - 参数校验失败 →
400 Bad Request，响应体含具体错误字段（如{"email": ["invalid format"]}） - 未认证 →
401 Unauthorized；无权限 →403 Forbidden
响应体结构建议保持一致，例如顶层包含 data、errors、meta（分页信息），避免有的返回扁平字段，有的嵌套多层。
版本控制与错误处理要前置设计
API 一旦上线，变更就牵一发而动全身。从第一天起就要考虑兼容性：
- 版本放在 URL 路径最前，如
/api/v1/users，比放 Header 或参数更直观、易调试 - 弃用旧版前，加
X-API-Deprecated: true响应头并说明替代路径 - 错误响应统一结构，包含
code（机器可读，如"VALIDATION_ERROR"）、message（简明中文提示）、details（可选，如字段名、原因） - 日志记录关键请求 ID（如
X-Request-ID），便于问题追踪
用 Flask 或 FastAPI 时，可通过中间件或异常处理器自动封装错误响应，避免每个视图重复写 try-except。
