开始免费使用
当前位置：首页 > Python > Python FastAPI 快速构建 RESTful API 接口教程

Python FastAPI 快速构建 RESTful API 接口教程

小满
小满
发布时间：2026-10-26| 4人浏览过
原创

FastAPI 是一个专为构建现代 Web API 设计的 Python 异步框架。它结合了 Python 3.8+ 标准类型提示（Type Hints）与 Pydantic 数据验证模型，能够在提供极高性能的同时自动生成 OpenAPI 标准文档。本文将以一个规范的“商品数据管理（Items API）”服务为实践主线，从开发环境准备、基础端点定义、Pydantic 模型校验到实现完整的增删改查（CRUD）操作，带领读者循序渐进掌握在生产中构建 RESTful API 的完整落地路径。

一、RESTful 架构核心概念与 FastAPI 处理流

REST（Representational State Transfer）架构风格通过统一接口规范客户端与服务端交互。在 RESTful 规范中，服务端的所有数据或功能均抽象为“资源”，资源通过唯一的 URI（统一资源标识符）定位，并通过标准的 HTTP 谓词执行具体操作。理解 HTTP 请求方法与状态码的语义化对应关系，是设计高内聚接口的前提。

HTTP 方法 典型 URI 路径 动作语义 标准成功状态码
GET /items 或 /items/{id} 读取单条或列表资源（安全且幂等） 200 OK
POST /items 创建全新资源（非幂等） 201 Created
PUT /items/{id} 完整替换现有资源（幂等） 200 OK
DELETE /items/{id} 删除指定资源（幂等） 200 OK / 204 No Content

FastAPI 依托 Starlette 承接异步 HTTP 网络循环，利用 Pydantic 自动化完成入参校验与实体反序列化。当请求进入应用时，FastAPI 会严格解析路由、提取类型注解、核对有效性，若校验失败直接拦截并抛出标准化 422 Unprocessable Entity 错误，无需在业务逻辑中编写大量冗长的防御性代码。

Python FastAPI 快速构建 RESTful API 接口教程
图 1：FastAPI RESTful 架构交互与数据流向原理图

二、开发准备与项目环境搭建

为了保证依赖环境隔离，推荐使用 Python 内置的 venv 模块创建独立虚拟环境。运行 FastAPI 需要一个支持 ASGI 协议的高性能服务器，通常首选 uvicorn。

1. 创建虚拟环境并安装核心依赖

# 1. 创建项目目录并进入
mkdir fastapi-crud-demo
cd fastapi-crud-demo

# 2. 创建并激活虚拟环境 (macOS/Linux)
python3 -m venv venv
source venv/bin/activate

# Windows PowerShell 执行: .\venv\Scripts\Activate.ps1

# 3. 安装 FastAPI 与 Uvicorn
pip install fastapi "uvicorn[standard]"

注意：安装 "uvicorn[standard]" 会同时安装 uvloop（Linux/macOS 上的高性能异步事件循环）和 httptools，能够显著提升生产吞吐性能。

2. 构建极简原型验证服务

在项目根目录下创建 main.py 文件，写入最基础的 Hello World 端点：

# main.py
from fastapi import FastAPI

app = FastAPI(title="商品管理 API 服务")

@app.get("/")
def read_root():
    return {"message": "FastAPI 服务已正常就绪"}

在终端中通过 Uvicorn 命令启动 ASGI 服务：

uvicorn main:app --reload --host 127.0.0.1 --port 8000

参数说明：main:app 指定了 Python 模块文件 main.py 以及内部实例化的 app 对象；--reload 开启开发模式下的热重载（检测到代码变更时自动重启服务）。

Python FastAPI 快速构建 RESTful API 接口教程
图 2：从零启动 FastAPI 项目的核心操作步骤

三、定义数据结构：Pydantic Schema 模型校验

在设计 RESTful 接口时，入参与出参的解耦非常关键。例如，客户端在创建商品时不需要（也不能）指定系统自增的 id；而在返回商品数据时，服务端则需要包含完整的 id 与计算属性。通过定义多个 Pydantic 模型，可以实现精准的职责隔离。

from typing import Optional
from pydantic import BaseModel, Field

# 基础模型：提取所有商品拥有的公共字段
class ItemBase(BaseModel):
    name: str = Field(..., min_length=2, max_length=50, description="商品名称，长度 2-50 字符")
    price: float = Field(..., gt=0, description="商品单价，必须大于 0")
    description: Optional[str] = Field(None, max_length=200, description="商品详细描述，选填")
    is_active: bool = Field(True, description="商品是否处于上架销售状态")

# 创建请求模型：入参不包含自增 id
class ItemCreate(ItemBase):
    pass

# 更新请求模型：所有字段均为选填，便于局部增量更新
class ItemUpdate(BaseModel):
    name: Optional[str] = Field(None, min_length=2, max_length=50)
    price: Optional[float] = Field(None, gt=0)
    description: Optional[str] = Field(None, max_length=200)
    is_active: Optional[bool] = None

# 响应模型：包含服务端生成的唯一主键 id
class ItemResponse(ItemBase):
    id: int

    class Config:
        # 支持 ORM 模型对象自动映射序列化
        from_attributes = True

四、完整实战：编写标准 CRUD 接口

为了直观演示完整的接口实现，这里使用 Python 内存字典 items_db 作为数据仓储。本示例完整实现了 RESTful 规范所要求的列表查询、分页过滤、详情读取、新增写入、更新与删除操作。

# main.py 完整实现代码
from typing import List, Optional
from fastapi import FastAPI, HTTPException, status, Query
from pydantic import BaseModel, Field

app = FastAPI(
    title="在线商品库存 RESTful API",
    description="基于 FastAPI 实现的标准 CRUD 接口实例",
    version="1.0.0"
)

# 内存模拟数据库
items_db = {
    1: {"id": 1, "name": "降噪机械键盘", "price": 499.0, "description": "Type-C 接口, 静音红轴", "is_active": True},
    2: {"id": 2, "name": "人体工学无线鼠标", "price": 269.0, "description": "双模连接, 超长续航", "is_active": True}
}

# --- 数据验证模型 ---
class ItemBase(BaseModel):
    name: str = Field(..., min_length=2, max_length=50)
    price: float = Field(..., gt=0)
    description: Optional[str] = Field(None, max_length=200)
    is_active: bool = True

class ItemCreate(ItemBase):
    pass

class ItemUpdate(BaseModel):
    name: Optional[str] = Field(None, min_length=2, max_length=50)
    price: Optional[float] = Field(None, gt=0)
    description: Optional[str] = Field(None, max_length=200)
    is_active: Optional[bool] = None

class ItemResponse(ItemBase):
    id: int

# --- API 端点定义 ---

# 1. 查询列表 (带分页与关键词过滤)
@app.get("/items", response_model=List[ItemResponse], summary="获取商品列表")
def get_items(
    skip: int = Query(0, ge=0, description="分页跳过的记录数"),
    limit: int = Query(10, gt=0, le=50, description="单页最大拉取量"),
    keyword: Optional[str] = Query(None, description="按商品名称模糊检索")
):
    results = list(items_db.values())
    if keyword:
        results = [item for item in results if keyword.lower() in item["name"].lower()]
    return results[skip : skip + limit]

# 2. 获取单条详情
@app.get("/items/{item_id}", response_model=ItemResponse, summary="获取指定商品详情")
def get_item(item_id: int):
    if item_id not in items_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"商品编号 ID {item_id} 不存在"
        )
    return items_db[item_id]

# 3. 创建全新资源
@app.post("/items", response_model=ItemResponse, status_code=status.HTTP_201_CREATED, summary="新增商品")
def create_item(item_in: ItemCreate):
    new_id = max(items_db.keys(), default=0) + 1
    new_item = {"id": new_id, **item_in.model_dump()}
    items_db[new_id] = new_item
    return new_item

# 4. 更新现有资源 (局部更新)
@app.put("/items/{item_id}", response_model=ItemResponse, summary="修改指定商品")
def update_item(item_id: int, item_in: ItemUpdate):
    if item_id not in items_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"商品编号 ID {item_id} 不存在"
        )
    current_data = items_db[item_id]
    # 只更新客户端传过来的非 None 字段
    update_data = item_in.model_dump(exclude_unset=True)
    current_data.update(update_data)
    items_db[item_id] = current_data
    return current_data

# 5. 删除资源
@app.delete("/items/{item_id}", status_code=status.HTTP_200_OK, summary="删除指定商品")
def delete_item(item_id: int):
    if item_id not in items_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"商品编号 ID {item_id} 不存在"
        )
    deleted_item = items_db.pop(item_id)
    return {"message": "商品删除成功", "deleted_id": deleted_item["id"]}
Python FastAPI 快速构建 RESTful API 接口教程
图 3：基于标准 HTTP 谓词的商品 CRUD 接口拓扑与路由映射

五、测试与交互式文档调试

FastAPI 最受开发者欢迎的特性之一是开箱即用的交互式 API 文档。只要服务启动，访问以下路径即可直接在浏览器进行可视化调试：

  • Swagger UI 页面：http://127.0.0.1:8000/docs。提供直观的 “Try it out” 在线调试窗口，支持直接输入请求体与参数测试并即时查看 HTTP 响应报文。
  • ReDoc 页面：http://127.0.0.1:8000/redoc。提供更适合作为技术规约阅读的三栏式文档布局，便于前后端团队协作。

我们可以使用 curl 命令行工具验证接口的数据校验防护能力。例如，发送一个违反校验规则的请求（商品价格为负数）：

# 客户端发起价格非法 (price = -20) 的 POST 请求
curl -X 'POST' \
  'http://127.0.0.1:8000/items' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "便携音箱",
    "price": -20.0
  }'

FastAPI 会自动拦截非法入参，直接返回结构化的 422 报错，明确定位错误字段与原因，而不会执行到后端的实际写入逻辑：

{
  "detail": [
    {
      "type": "greater_than",
      "loc": ["body", "price"],
      "msg": "Input should be greater than 0",
      "input": -20.0,
      "ctx": {"gt": 0.0}
    }
  ]
}

六、FastAPI 接口开发避坑指南与总结

在日常开发与上线交付阶段，有几项关键规则需要特别关注：

  • 慎用普通的同步阻塞函数：在 FastAPI 中，使用 async def 定义的路由若调用了普通阻塞型 I/O 操作（如 time.sleep() 或同步数据库驱动），会直接阻塞整个单线程事件循环。对于耗时且没有异步驱动的外部任务，应该声明为普通的 def 函数，FastAPI 会自动将其放入专用线程池中运行。
  • 明确指定 response_model：始终为路由指定输出模型。这样做不仅能阻止内部敏感数据（如用户密码散列值、内部追踪标记）意外泄露给客户端，还能确保 Swagger 文档能够准确渲染响应结构体。
  • 统一异常抛出机制：业务中出现资源未找到或鉴权失败时，必须统一抛出 HTTPException 并指定标准状态码，避免直接在路由中 return {"status": "error"} 导致客户端无法通过标准 HTTP 状态感知失败。
Python FastAPI 快速构建 RESTful API 接口教程
图 4：FastAPI 核心构建规范与关键设计要点总结

通过本文的循序渐进讲解，我们完整体验了基于 FastAPI 与 Pydantic 构建符合 RESTful 架构规范 API 的标准过程。从清晰的数据契约定义到自解释的状态码与错误拦截，FastAPI 不仅极大地精简了样板代码，还显著提升了服务端开发的安全性和可维护性。

相关文章

相关标签: Python FastAPI

免责声明：本文内容仅供参考，不代表本站观点。转载或引用请注明出处。

作者最新文章

全部文章

Python 相关产品和应用

全部下载
PythonSelenium
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

Python机器学习
scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Python代码质量
Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Python代码质量
Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

Pythonpytest
pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

PythonFastAPI
FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架，支持类型提示和自动接口文档。

PythonFlask
Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

PythonDjango
Django

Django

6.1.2 · Windows

成熟的 Python Web 框架，适合构建内容站点和业务系统。

PythonIDE
Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

PythonSciPy
SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。