Python Web 开发：FastAPI 入门实战 —— HTTP 基础与 RESTful API 设计

1. 🚀 HTTP 协议概述

HTTP（HyperText Transfer Protocol）是现代互联网应用的基础协议，它定义了浏览器与服务器之间进行通信的规则。通过 HTTP 协议，客户端能够向服务器发送请求，服务器则根据请求内容返回响应数据。HTTP 协议的工作模型是请求-响应模式，客户端发出请求，服务器返回响应。

请求方法（Request Methods）

在 HTTP 协议中，请求方法决定了客户端希望对服务器上的资源执行何种操作。常见的请求方法包括：

GET：用于请求获取资源。GET 请求只用于获取数据，不会对服务器上的数据造成任何修改。
```
@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}
```
POST：用于向服务器提交数据，通常用于创建资源。POST 请求会将数据发送到服务器，并让服务器根据这些数据进行处理。
```
@app.post("/items/")
def create_item(item: Item):
    return {"name": item.name, "price": item.price}
```
PUT：用于更新资源。当客户端需要更新某个资源时，使用 PUT 请求来提交新数据。与 POST 请求不同，PUT 请求通常是幂等的，即多次提交相同数据的结果是一样的。
```
@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
    return {"item_id": item_id, "name": item.name, "price": item.price}
```

DELETE：用于删除资源。DELETE 请求通常是幂等的，即删除相同资源多次，结果不会发生变化。

@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"message": f"Item {item_id} deleted"}

HTTP 状态码（Status Codes）

HTTP 状态码是服务器响应的核心部分，它指示了请求处理的结果。常见的状态码包括：

2xx：成功类
- 200 OK：请求成功，服务器返回所请求的资源或确认操作已完成。
- 201 Created：请求成功且服务器创建了新的资源。
3xx：重定向类
- 301 Moved Permanently：请求的资源已永久迁移到新位置。
- 302 Found：请求的资源暂时位于不同的位置。
4xx：客户端错误类
- 400 Bad Request：请求格式有误或缺少必要的参数。
- 404 Not Found：请求的资源不存在。
5xx：服务器错误类
- 500 Internal Server Error：服务器发生了未预料的错误，导致请求无法完成。
- 503 Service Unavailable：服务器暂时不可用，通常是由于服务器超载或正在进行维护。

在 FastAPI 中，你可以自定义 HTTP 状态码：

from fastapi import HTTPException

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id == 42:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id}

HTTP 头部（Headers）

HTTP 请求和响应包含了许多有用的头部信息，如请求的内容类型、响应的格式、缓存策略等。常见的头部包括：

Content-Type：指定请求或响应的内容类型。例如，application/json 表示发送的内容是 JSON 格式。
Authorization：用于身份验证，常见的如 Bearer Token。
User-Agent：指定发起请求的客户端软件（如浏览器或应用）。

在 FastAPI 中，头部可以通过参数注入：

from fastapi import Header

@app.get("/header/")
def read_header(user_agent: str = Header(...)):
    return {"User-Agent": user_agent}

2. 🌐 HTTP 请求与响应的工作原理

HTTP 协议的工作原理基于客户端和服务器之间的请求-响应模型。当客户端向服务器发出请求时，服务器解析请求并返回响应。整个过程分为以下几个步骤：

客户端发起请求

客户端发起 HTTP 请求时，包含以下主要信息：

请求行：包括 HTTP 方法（如 GET、POST）、请求的资源路径和协议版本。例如：GET /items/123 HTTP/1.1。
请求头：包含请求的元数据，如 Content-Type、Authorization 等。
请求体（可选）：在 POST、PUT 等方法中，请求体包含了客户端发送给服务器的数据，如 JSON 格式的对象。

在 FastAPI 中，HTTP 请求通常通过 HTTP 方法装饰器定义，例如 @app.get("/path")。

服务器处理请求

服务器接收到 HTTP 请求后，会根据请求的 URL 路径、方法及参数进行处理。FastAPI 会根据请求的 URL 路径和 HTTP 方法匹配相应的视图函数。当请求包含参数时，FastAPI 会自动将这些参数提取并传递给函数。例如：

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

此时，item_id 就是从 URL 路径中提取的参数。

服务器返回响应

服务器根据处理结果构建一个 HTTP 响应，包含响应行、响应头和响应体。响应体通常是请求数据的结果，格式可能是 JSON、HTML、纯文本等。

在 FastAPI 中，响应数据通常是 JSON 格式：

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

当客户端接收到响应时，它将解析响应头和响应体，并根据需要进行处理。

3. 🛠️ RESTful API 设计理念

REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，用于设计可扩展和可维护的 API。RESTful API 是遵循 REST 架构风格设计的 API，它利用 HTTP 方法来定义操作，并通过 URL 进行资源标识。

资源的定义

在 RESTful API 中，一切内容都被视为资源。资源可以是数据实体，如用户、商品、订单等，也可以是服务或操作。每个资源都应该具有唯一的标识符，通常是 URL 路径。

例如，在一个电商平台中，可以定义以下资源：

用户资源：/users/{user_id}
商品资源：/products/{product_id}

资源的操作

RESTful API 通过 HTTP 方法对资源进行操作。常见的操作包括：

GET：用于查询资源。通过 GET 请求可以获取某个资源的详细信息，或者获取资源的列表。
POST：用于创建资源。通过 POST 请求，可以将新资源提交到服务器，并创建新的数据实体。
PUT：用于更新资源。通过 PUT 请求，可以修改现有资源的数据。
DELETE：用于删除资源。通过 DELETE 请求，可以删除某个资源。

RESTful URL 设计原则

RESTful API 的 URL 设计应该遵循以下原则：

使用名词表示资源，而不是动词。比如，/items 表示所有的商品资源，而不是 /getItems。
使用层级结构来表示资源之间的关系。例如，/users/{user_id}/orders 表示某个用户的订单。

@app.get("/users/{user_id}/orders")
def get_orders(user_id: int):
    return {"user_id": user_id, "orders": orders}

4. 🗂️ JSON 格式数据的传输与解析

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，易于人类阅读和编写，同时也易于机器解析和生成。它在 Web 开发中广泛应用，尤其是在客户端与服务器之间的数据传输中。

JSON 数据格式

JSON 数据格式由键值对组成，键是字符串，值可以是字符串、数字、布尔值、数组、对象或 null。例如：

{
  "name": "John Doe",
  "age": 30,
  "is_student": false,
  "courses": ["Math", "Science"]
}

在 FastAPI 中，客户端和服务器通过 JSON 格式进行数据交互。FastAPI 会自动处理 JSON 的解析和生成，客户端只需要发送符合 JSON 格式的数据即可。

FastAPI 中的 JSON 解析

FastAPI 使用 Pydantic 模型来验证和解析 JSON 数据。在请求

体中，FastAPI 会自动将 JSON 数据转换为 Python 对象，并根据定义的 Pydantic 模型进行验证。例如：

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
def create_item(item: Item):
    return {"name": item.name, "price": item.price}

在客户端发送一个 JSON 请求时：

{
  "name": "Laptop",
  "price": 1000.0
}

FastAPI 会自动解析这个 JSON 请求并将其转换为 Item 对象。

JSON 响应

FastAPI 在返回响应时也会使用 JSON 格式。默认情况下，FastAPI 会将返回的数据自动转换为 JSON 格式：

@app.get("/items/{item_id}")
def get_item(item_id: int):
    return {"item_id": item_id, "name": "Laptop", "price": 1000.0}

客户端接收到的响应将会是：

{
  "item_id": 1,
  "name": "Laptop",
  "price": 1000.0
}

以上内容涵盖了 HTTP 协议基础、请求与响应的工作原理、RESTful API 设计理念以及 JSON 格式的数据传输与解析，为 FastAPI 入门打下了坚实的基础。通过这些知识，可以更好地理解 FastAPI 的工作机制，进而高效地构建 Web 应用。