RESTful API 不是复杂理论，而是一套让接口更清晰、更容易维护的设计习惯。本文用 Python 后端项目的例子讲清资源、URL、HTTP 方法、状态码、分页、筛选和统一返回格式。

【一、为什么要学 RESTful API】

后端项目里最容易乱的地方就是接口。

如果没有规范，接口可能会写成这样：

/getUser

/createNewUser

/delete_user_by_id

/queryAllUserData

/doLogin

短期能跑，长期会很难维护。前端不知道接口语义，测试不知道怎么覆盖，新人接手也很痛苦。

RESTful API 的目的就是让接口围绕“资源”设计，而不是围绕“动作”乱起名。

【二、什么是资源】

资源就是系统里的业务对象，比如：

- 用户：`users`

- 文章：`articles`

- 商品：`products`

- 订单：`orders`

- 知识库：`knowledge-bases`

- 文档：`documents`

RESTful 推荐 URL 使用名词，而不是动词。

推荐：/users/1

不推荐：/getUserById?id=1

因为 HTTP 方法已经表达了动作，URL 只需要表达资源。

【三、HTTP 方法和 URL 怎么配合】

以用户资源为例：

| 操作 | 方法 | URL | 含义 |

|---|---|---|---|

| 查询用户列表 | GET | `/users` | 查询多个用户 |

| 查询单个用户 | GET | `/users/1` | 查询 id=1 的用户 |

| 创建用户 | POST | `/users` | 新增用户 |

| 全量更新用户 | PUT | `/users/1` | 覆盖用户数据 |

| 部分更新用户 | PATCH | `/users/1` | 修改部分字段 |

| 删除用户 | DELETE | `/users/1` | 删除用户 |

这就是 RESTful 最常用的设计方式。

【四、嵌套资源怎么设计】

如果一个资源属于另一个资源，可以使用嵌套路径。

比如某个知识库下的文档：

GET  /knowledge-bases/10/documents

POST /knowledge-bases/10/documents

GET  /knowledge-bases/10/documents/3

意思很清楚：操作的是 id=10 的知识库下面的文档。

但嵌套不要太深。一般最多两到三层，太深说明接口设计可能过度复杂。

【五、查询、分页、排序怎么写】

查询参数适合放在 URL 的 query string 里。

GET /articles?keyword=python&page=1&page_size=20

GET /orders?status=paid&sort=-created_at

常见参数：

- `page`：第几页

- `page_size`：每页多少条

- `keyword`：关键词搜索

- `status`：按状态筛选

- `sort`：排序字段

返回时最好带上分页信息：

```json

{

  "items": [],

  "total": 125,

  "page": 1,

  "page_size": 20

}

```

【六、状态码怎么设计】

RESTful API 不要求你背所有状态码，但常用的要用对。

| 状态码 | 场景 |

|---|---|

| 200 | 查询或普通操作成功 |

| 201 | 创建资源成功 |

| 204 | 删除成功且不返回内容 |

| 400 | 参数错误 |

| 401 | 未登录或 token 无效 |

| 403 | 没有权限 |

| 404 | 资源不存在 |

| 409 | 数据冲突，比如邮箱已注册 |

| 422 | 参数格式校验失败 |

| 500 | 服务端异常 |

新手常见问题是：所有请求都返回 200，然后在 JSON 里写 `success=false`。这样不是完全不能用，但会削弱 HTTP 状态码本身的语义。

【七、统一返回格式怎么设计】

项目里最好统一响应结构，否则前端处理会很麻烦。

一种常见格式：

```json

{

  "code": 0,

  "message": "success",

  "data": {}

}

```

分页接口

```json

{

  "code": 0,

  "message": "success",

  "data": {

    "items": [],

    "total": 100,

    "page": 1,

    "page_size": 20

  }

}

```

错误响

```json

{

  "code": 1001,

  "message": "用户名或密码错误",

  "data": null

}

```

注意：状态码和业务 code 可以同时存在。状态码表达 HTTP 层面的成功失败，业务 code 表达更细的业务错误。

【八、FastAPI 示例】

```python

from fastapi import FastAPI, HTTPException

from pydantic import BaseModel

app = FastAPI()

class UserCreate(BaseModel):

    username: str

    email: str

fake_users = {}

@app.post("/users", status_code=201)

def create_user(user: UserCreate):

    user_id = len(fake_users) + 1

    fake_users[user_id] = user.model_dump()

    return {"id": user_id, **fake_users[user_id]}

@app.get("/users/{user_id}")

def get_user(user_id: int):

    if user_id not in fake_users:

        raise HTTPException(status_code=404, detail="用户不存在")

    return fake_users[user_id]

```

这个例子体现了：

- POST `/users` 创建用户。

- GET `/users/{user_id}` 查询用户。

- 不存在时返回 404。

- 请求体用 Pydantic 校验。

【九、常见坑】

- URL 里混入动词：`/getUser`、`/deleteUser`。

- 单复数混乱：有的写 `/user`，有的写 `/users`。

- 查询接口使用 POST，导致语义混乱。

- 错误码没有统一规则，前端只能靠猜。

- 分页没有总数，前端无法做分页器。

- 删除接口真的物理删除，但业务上需要保留审计记录。

【十、面试高频问题】

【1. RESTful API 的核心思想是什么？】

核心思想是把系统中的对象抽象成资源，用 URL 表示资源，用 HTTP 方法表示对资源的操作。这样接口语义清晰，便于前后端协作和维护。

【2. PUT 和 PATCH 有什么区别？】

PUT 通常表示全量更新，即客户端提交完整资源；PATCH 表示部分更新，只提交要修改的字段。比如用户有 username、email、avatar，PATCH 可以只改 avatar。

【3. 为什么要做统一响应格式？】

统一响应格式可以降低前端处理成本，也方便统一错误处理、日志记录和接口文档生成。否则不同接口返回结构不同，前端每接一个接口都要写特殊逻辑。