API 设计指南：构建用户喜爱的 API

设计不好的 API 是对每个使用它的开发人员的税收。设计良好的 API 感觉很自然，可以无故障地扩展。

REST API 原则

1. 使用名词，不要动词

不好:

```

GET /api/getUsers

POST /api/createUser

DELETE /api/deleteUserById?id=123

```

好:

```

GET /api/users

POST /api/users

DELETE /api/users/123

```

2. HTTP 状态码很重要

不要对所有内容都使用 200：

```

200 OK → 请求成功

201 Created → 创建了资源

204 No Content → 成功，没有响应体

400 Bad Request → 客户端错误

401 Unauthorized → 需要身份验证

403 Forbidden — 已认证但不允许

404 Not Found → 资源不存在

500 Server Error → 我们这边出错了

```

3. 一致的响应格式

每个响应都应遵循相同的结构：

```json

{

"success": true,

"data": { "id": 123, "name": "张三" }

}

```

4. 列表分页

永远不要一次返回数百万条记录：

```

GET /api/users?page=1&limit=50

```

5. 过滤和排序

让客户指定他们想要的数据：

```

GET /api/users?status=active&sort=created_at:desc

```

结论

设计精良的 API 可以扩展且感觉很自然。我们在瑙拉构建优秀的 API。