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

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

date: 2025/2/26

updated: 2025/2/26

author: cmdragon

excerpt:

本文通过开汉堡店的趣味比喻，零基础讲解HTTP协议与RESTful API设计。你将：
用快递盒理解HTTP请求/响应的状态码/Header/Body
通过5个汉堡店API案例掌握RESTful设计精髓
亲手实现带验证的API（代码可直接复制运行）
获得错误调试锦囊（含422等9种常见错误解决方案）

categories:

后端开发
FastAPI

tags:

HTTP协议入门
RESTful设计实战
API开发基础
状态码图解
请求响应结构
FastAPI快速上手
错误调试手册

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

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

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

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

1.1 快递单号：HTTP请求结构

POST /orders HTTP/1.1              寄件动作

Content-Type: application/json     物品清单格式

Authorization: Bearer token123     安全印章

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

1.2 物流追踪：HTTP响应结构

HTTP/1.1 201 Created              签收成功

Location: /orders/1001           新订单位置

X-RateLimit-Remaining: 99        剩余请求次数

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

1.3 快递状态码速查表

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

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

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

GET / 菜单  # 查看菜单

POST / 订单  # 下单

PUT / 订单 / 1001  # 修改订单

DELETE / 订单 / 1001  # 退单

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

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 必填参数验证（防止瞎填单）

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错误？

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

第四章：课后实战工坊 ️

任务1：实现订单系统

# 你的代码在这里！

@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：防御披萨注入攻击

# 危险代码（可被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设计超图解指南 | cmdragon's Blog

往期文章归档：