HTTP JSON REST API 大白话 - 闯关模式

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

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

1. API 是什么

API 可以理解成办事窗口。

前端说：

我要查询用户 1 的信息。

后端说：

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

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

HTTP API 请求响应流程

一个 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
}

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

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

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

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

不要这样写：

/getUser
/addUser
/deleteUser

更推荐：

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

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

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

Header 是请求的附加信息。

常见 Header：

登录常见写法：

Authorization: Bearer eyJxxx

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

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

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

参数意思：

返回建议：

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

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

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

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

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