在实际开发中，最常见的问题往往不是代码本身的 bug。而是“伪 RESTful”的实现：URI 里塞动词、错误统一返回同一个 JSON、POST 接口被前端超时重试刷出一堆重复订单…，这些看似细小的问题，凑在一起就会导致线上事故。

一、资源建模：URI 里只允许出现名词

”，HTTP 方法描述“做什么”。说起来，任何 URI 中出现动词都代表着偏离了 REST 的设计理念。

Pain Point： 很多团队在落地时忽略了复数与单数的统一。导致 API 文档混乱，嵌套层级过多使路由难以维护；状态变更写成动词调用，使得同一程序中出现两种不一致的写法。

• . 资源用复数。 /goods 表示集合，/goods/{id} 是集合里的一个成员。话说回来，单复数混用是接口文档最廉价的混乱来源。
• . 嵌套最多两层。 /shops/{shop_id}/goods 表达归属关系很自然但超过两层会失控。拆开，用查询参数表达过滤，例如 GET /api/v1/stocks?sku_id=，。
• . 状态变更不是动词问题，而是状态字段问题。 "取消订单" 推荐两种写法： ① 简单场景直接 PATCH /api/v1/orders/{order_id} body 传 {"status":"CANCELLED"} ② 动作复杂时用动作子资源 POST /api/v1/orders/{order_id}/cancellation。保持规律性即可，
• . 同一个程序里使用相同约定才能降低认知成本，避免不同风格混杂导致维护困难。

FastAPI 示例：

# app/main.py
from fastapi import FastAPI
from app.routers import goods,orders
app = FastAPI
app.include_router
app.include_router
# app/routers/goods.py
from fastapi import APIRouter
router = APIRouter
@router.get # GET /api/v1/goods
def list_goods:
...
@router.get # GET /api/v1/goods/{id}
def get_goods:
...
@router.get # 一层嵌套：店铺下的商品
def list_shop_goods:
...

二、语义约束：方法用对、状态码用全、幂等做到位

方法与状态码清晰划分

• . GET 只读；POST 创建，PUT 全量更新；PATCH 局部更新，DELETE 删除。说到重灾区有两个， 
  1. GET 请求带 body 做复杂查询——部分网关和 CDN 会直接丢弃 body。导致请求失效或返回错误数据。
  2. 所有操作都用 POST 包打天下——等于主动放弃 HTTP 层语义，缓存、幂等、监控全得自己造轮子。
• . 状态码要真实表达业务结果： 
  • "201 Created" 并在响应头带上新资源 URI；"<400 Bad Request" 参数错误； "<401 Unauthorized" 未认证； "<403 Forbidden" 已认证但无权限； "<404 Not Found" 资源不存在； "<409 Conflict" 状态冲突； "<429 Too Many Requests" 限流触发； "<500 Internal Server Error" 服务端兜底。 
  客户端按 HTTP 状态码分支比解析自定义枚举更可靠。
• . 避免将业务状态信息全部塞进响应体内部，以免导致客户端逻辑过度耦合。话说回来，

从幂等性来看。电商接口的命门

PATTERN：GET/PUT/DELETE 天然幂等，POST 不是。在下单、支付这类 POST 接口中，如果前端超时重试或使用者手抖连点。没有幂等保护就会产生重复扣库存、重复扣款等严重后果。

通用做法的观点是。客户端生成 X-Idempotency-Key ) 请求头，服务端按 key 去重。以下演示内存存储，生产环境请使用 Redis 或其他持久化方案：

import hashlib
import time
from fastapi import FastAPI,Header,Response
from pydantic import BaseModel
app = FastAPI
_ idem_store = {}
class CreateOrderReq:
user_id: int
sku_id这方面，int
quantity: int
@app.post
def create_order(
说到req，CreateOrderReq,response: Response。idempotency_key: str = Header):
if idempotency_key in _idem_store:
response.status_code = 409 # 重放标识
return _idem_store
# ---- 真正业务逻辑 ----#
order = {
"order_id": hashlib.md5}".encode).hexdigest,"user_id": req.user_id,"sku_id": req.sku_id,"quantity": req.quantity,"status": "CREATED",}
_idem_store = order
return order

*关键细节*： ① key 的粒度建议绑定到「使用者 + 业务动作」避免不同使用者 key 冲突导致误删单据。② 缓存有效期应覆盖客户端最大重试窗口，一般几个小时足够满足大多数业务场景。

三、工程化：版本管理、分页策略与统一错误格式化

版本优先选 URI 而非 Header

• "/api/v1" 直白且好调试，网关路由规则也易于书写。而 Header 版本（如 "Accept: application/vnd.shop.v2+json") 虽然理论上更优雅，却极大增加联调和抓包排查难度。小团队直接使用 URI 版本即可避免过度设计与兼容性挑战。
• Pain Point： 不少项目因 Header 版本实现不完整而出现跨版本共存冲突，对后续迭代造成阻碍。

至于错误格式统一。全程序统一 + request‑id

• Simplify client error handling by adopting a single JSON schema across all endpoints.

• If you prefer RFC‑7807 compliance: