17370845950

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 方法语义必须严格对应操作类型

每个方法有明确约定，不可混用。后端实现需与之对齐，否则前端无法可靠预测行为：

• 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。