API 设计 · 让前端别骂你 | 小朵科技工作室 博客

写过 FastAPI / Flask 的都知道，后端 API 设计得好不好，直接影响前端同学的血压。

几个原则：

1. 路径用复数名词，不出现动词

GET /api/comments        → 获取列表
POST /api/comments       → 创建
GET /api/comments/{id}   → 获取单个

2. 用 HTTP 状态码表达结果

200  成功
201  创建成功
400  参数错误
404  资源不存在
500  服务器内部错误

3. 分页要规范

GET /api/comments?page=1&page_size=20

返回：
{
  "total": 1234,
  "page": 1,
  "page_size": 20,
  "data": [...]
}

4. 错误信息要友好

别返回 "Error"，要：

{"detail": "评论 ID 不存在", "code": "COMMENT_NOT_FOUND"}

5. 文档自动生成

FastAPI 自带 Swagger UI，访问 /docs 就是接口文档，前端不用问。

最关键的一条：跟前端约定好，改一次，不要反复改——这是后端信誉的来源。

---

本文由 BBZ · 小朵科技工作室 出品。