API 接口设计笔记

接口设计最重要的是稳定和清楚。前后端协作时，接口文档写得越模糊，联调时越容易互相猜。

URL 命名

资源用名词，不要用动词堆路径：

GET    /api/projects
GET    /api/projects/:id
POST   /api/projects
PATCH  /api/projects/:id
DELETE /api/projects/:id

动作由 HTTP 方法表达，路径表达资源。

列表查询常见参数：

page=1
pageSize=20
keyword=xxx
category=frontend

复杂筛选条件要提前约定字段名和类型，不要等联调时临时加。

建议统一结构：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

分页可以这样：

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [],
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}

错误信息要能帮助定位问题：

{
  "code": 40001,
  "message": "invalid project title"
}

不要只返回 error 或 failed。

同一个项目里要统一风格：

前端项目常用 camelCase，数据库常用 snake_case。如果需要转换，最好在接口层统一处理。

接口不是后端一个人的东西，而是前后端共同维护的契约。