logo cmdragon's Blog

从零构建你的第一个RESTful API：HTTP协议与API设计超图解指南 🌐

avatar
cmdragon 渡劫
  2025-02-26 00:00:00   2025-02-26 00:00:00   1.7k 字  6 分钟
image image

扫描二维码关注或者微信搜一搜：编程智域 前端至全栈交流与成长

🍔 本文通过开汉堡店的趣味比喻，零基础讲解HTTP协议与RESTful API设计。你将：

  • 用快递盒理解HTTP请求/响应的状态码/Header/Body
  • 通过5个汉堡店API案例掌握RESTful设计精髓
  • 亲手实现带验证的API（代码可直接复制运行）
  • 获得错误调试锦囊（含422等9种常见错误解决方案）

第一章：3分钟理解HTTP协议（快递员视角）

1.1 快递单号：HTTP请求结构

1
2
3
4
5
POST /orders HTTP/1.1             📦 寄件动作
Content-Type: application/json    📝 物品清单格式
Authorization: Bearer token123    🔑 安全印章

{"item": "芝士汉堡", "quantity": 2}  📦 包裹内容

1.2 物流追踪：HTTP响应结构

1
2
3
4
5
HTTP/1.1 201 Created             ✅ 签收成功
Location: /orders/1001          📍 新订单位置
X-RateLimit-Remaining: 99       ⏳ 剩余请求次数

{"id": 1001, "status": "烹饪中"}   📦 返回的包裹

1.3 快递状态码速查表

状态码比喻常见场景
200包裹完好送达成功获取资源
404收件地址不存在请求路径错误
422包裹内容不符合要求参数校验失败

第二章：RESTful设计就像开餐厅 🍽️

2.1 餐厅四大基础服务（对应HTTP方法）

1
2
3
4
GET / 菜单  # 查看菜单
POST / 订单  # 下单
PUT / 订单 / 1001  # 修改订单
DELETE / 订单 / 1001  # 退单

2.2 第一个RESTful API：汉堡店系统

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from fastapi import FastAPI

app = FastAPI()
fake_menu = [
    {"id": 1, "name": "经典汉堡", "price": 30},
    {"id": 2, "name": "辣味汉堡", "price": 35}
]


# 获取全部汉堡
@app.get("/hamburgers")
async def get_hamburgers():
    return fake_menu


# 创建新汉堡
@app.post("/hamburgers")
async def create_hamburger(name: str, price: float):
    new_item = {"id": len(fake_menu) + 1, "name": name, "price": price}
    fake_menu.append(new_item)
    return {"message": "汉堡已加入菜单", "data": new_item}

第三章：API安全与验证 🔐

3.1 必填参数验证（防止瞎填单）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from pydantic import BaseModel


class Hamburger(BaseModel):
    name: str  # 必须填写名称
    price: float  # 必须填写价格
    spicy: bool = False  # 可选参数


@app.post("/v2/hamburgers")
async def safe_create(hb: Hamburger):
    if hb.price < 0:
        raise HTTPException(422, "价格不能为负数")
    # 保存到数据库...

3.2 常见错误诊疗室
问题：为什么返回422错误？

  1. 检查是否忘记写price字段
  2. 查看价格是否是负数
  3. 确认请求头包含Content-Type: application/json

第四章：课后实战工坊 🛠️

任务1：实现订单系统

1
2
3
4
5
6
7
8
9
10
11
# 你的代码在这里！
@app.get("/orders/{order_id}")
async def get_order(order_id: int):
    # 实现根据ID查订单
    pass


@app.post("/orders")
async def create_order(items: list):
    # 实现创建订单
    pass

任务2：防御披萨注入攻击

1
2
3
4
5
# 危险代码（可被SQL注入）
def get_user(input):
    cursor.execute(f"SELECT * FROM users WHERE name = '{input}'")

# 你的任务：改写为安全代码（使用参数化查询）

结语

通过这份指南，你已掌握HTTP协议的核心机制与RESTful API设计精髓。现在打开VS Code，用python -m uvicorn main:app --reload
启动你的第一个API吧！遇到问题随时回来看错误锦囊，编程就像做汉堡，多练习才能成为大厨 👨🍳

余下文章内容请点击跳转至 个人博客页面 或者 扫码关注或者微信搜一搜：编程智域 前端至全栈交流与成长，阅读完整的文章：

往期文章归档：

从零构建你的第一个RESTful API：HTTP协议与API设计超图解指南 🌐
posts/e5078a4d6fad/
作者
cmdragon
发布于
2025-02-26 00:00
许可
  1. 1. 第一章：3分钟理解HTTP协议（快递员视角）
  2. 2. 第二章：RESTful设计就像开餐厅 🍽️
  3. 3. 第三章：API安全与验证 🔐
  4. 4. 第四章：课后实战工坊 🛠️
  • 结语
  • 往期文章归档：
    1. 1. 第一章：3分钟理解HTTP协议（快递员视角）
    2. 2. 第二章：RESTful设计就像开餐厅 🍽️
    3. 3. 第三章：API安全与验证 🔐
    4. 4. 第四章：课后实战工坊 🛠️
  • 结语
  • 往期文章归档：