HTTP JSON REST API

一句话：API 就是前端和后端约好的办事窗口，HTTP 负责传话，JSON 负责装数据，REST 负责让接口命名更有规律。

本篇学完你会什么：能看懂一个接口为什么叫 GET /users/1，知道请求、响应、状态码、Header、Body 分别是什么。

1. API 是什么

API 可以理解成办事窗口。

前端说：

我要查询用户 1 的信息。

后端说：

{
  "id": 1,
  "username": "tom"
}

API 的重点不是“网址”，而是前后端约定：

去哪里请求
用什么方法请求
传什么参数
返回什么数据
错了怎么提示

HTTP API 请求响应流程

2. HTTP 请求长什么样

一个 HTTP 请求通常有四块：

方法 + 路径
Header
Body

例子：

POST /api/v1/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer xxx

{
  "username": "tom",
  "age": 18
}

对应后端要回答：

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 1,
  "username": "tom",
  "age": 18
}

3. JSON 是什么

JSON 是前后端最常用的数据格式。

{
  "id": 1,
  "title": "第一篇文章",
  "tags": ["python", "api"],
  "published": true
}

大白话：JSON 就是双方都看得懂的数据盒子。

4. REST API 怎么命名

REST 的核心是：路径表示资源，方法表示动作。

需求	方法和路径
查询用户列表	`GET /users`
查询单个用户	`GET /users/{id}`
新增用户	`POST /users`
修改用户	`PUT /users/{id}`
删除用户	`DELETE /users/{id}`

不要这样写：

/getUser
/addUser
/deleteUser

更推荐：

GET /users/1
POST /users
DELETE /users/1

5. 状态码怎么用

状态码是后端给前端的结果灯。

状态码	意思	场景
200	成功	查询、修改成功
201	已创建	新增成功
400	请求逻辑错了	比如开始时间晚于结束时间
401	未登录	没有 token
403	没权限	不是管理员
404	找不到	用户不存在
409	冲突	用户名已存在
422	请求格式或字段校验失败	Pydantic 校验不通过
500	服务错误	后端代码异常

在 FastAPI 里，字段类型不对、必填字段没传，通常是 422。
400 更适合表示“格式虽然能看懂，但业务规则不接受”，比如库存不足、日期范围不合理。

6. Header、Cookie、Token

Header 是请求的附加信息。

常见 Header：

Header	用途
`Content-Type`	告诉后端 body 是什么格式
`Authorization`	携带登录 token
`Accept-Language`	语言
`X-Request-Id`	请求追踪 id

登录常见写法：

Authorization: Bearer eyJxxx

大白话：Token 就像临时通行证，前端每次带上，后端就知道你是谁。

7. 分页、筛选、排序

列表接口不要一次返回所有数据。

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

参数意思：

参数	意思
`page`	第几页
`page_size`	每页几条
`keyword`	搜索关键词
`sort`	排序字段

返回建议：

{
  "items": [],
  "total": 100,
  "page": 1,
  "page_size": 20
}

8. 幂等是什么

幂等就是：同一个操作执行多次，结果应该一样。

方法	是否通常幂等	解释
GET	是	查多少次都只是查
PUT	是	修改成同一个结果
DELETE	是	删除后再删还是不存在
POST	通常不是	多次提交可能新增多条

支付、提交订单、发短信这些接口，要特别注意重复提交。

9. 常见错误

问题	原因	解决
POST 收不到参数	没传 JSON body	检查 `Content-Type`
前端说跨域	CORS 没配置	后端加 CORS 中间件
401	没登录或 token 过期	重新登录
403	登录了但没权限	检查角色
列表很慢	没分页或没索引	加分页和数据库索引

10. 设计接口检查清单

[ ] 路径是不是资源名
[ ] 方法是不是合适
[ ] 请求参数有没有校验
[ ] 响应格式是否稳定
[ ] 错误状态码是否准确
[ ] 列表是否分页
[ ] 需要登录的接口是否鉴权
[ ] 是否考虑重复提交
[ ] 是否能在 /docs 里看懂

总结表

名词	大白话
HTTP	前后端传话的规则
API	后端提供的办事窗口
JSON	数据盒子
REST	让接口路径更有规律的风格
Header	请求附加信息
Body	请求正文
状态码	请求结果灯
Token	登录通行证
幂等	重复请求结果不乱

下一篇建议：大白话讲解——FastAPI 入门到进阶。

阅读中

本关怎么过