怎么使用FastAPI快速搭建第一个Python RESTful API服务

搭建一个高效的 Python RESTful API 服务，最直接的路径是借助 FastAPI 框架与 Uvicorn 异步服务器：通过几行轻量代码声明应用实例与路由函数，依托 Python 原生类型提示自动完成数据校验，并通过内置的 OpenAPI 规范直接生成可交互的在线接口调试文档。

一、环境准备与依赖安装

在开始编码前，推荐为项目创建独立的 Python 虚拟环境，以避免第三方库版本冲突。FastAPI 本身是一个纯粹的 Web 框架，网络协议解析与异步连接处理则需要搭配高性能的 ASGI 服务器（如 Uvicorn）。

1. 创建项目目录与虚拟环境

打开终端，执行以下命令完成环境初始化：

# 创建并进入项目目录
mkdir fastapi-demo && cd fastapi-demo

# 创建独立虚拟环境
python3 -m venv venv

# 激活虚拟环境 (macOS/Linux)
source venv/bin/activate
# Windows 环境请执行: .\venv\Scripts\activate

2. 安装 FastAPI 与 Uvicorn

在激活的虚拟环境中，使用 pip 安装核心依赖：

pip install fastapi uvicorn

其中，fastapi 提供了路由声明、数据验证和文档生成能力；uvicorn 作为基于 uvloop 和 httptools 构建的高性能异步服务器，负责接收客户端请求并转发给 FastAPI 应用。

二、编写最小可运行的 FastAPI 应用

在项目目录下创建名为 main.py 的文件，写入以下基础代码：

from fastapi import FastAPI

# 创建应用实例
app = FastAPI(title="我的第一个 FastAPI 服务")

# 声明根路由
@app.get("/")
def read_root():
    return {"message": "欢迎使用 FastAPI RESTful 服务", "status": "running"}

启动与运行验证

在终端中运行以下命令启动服务：

uvicorn main:app --reload

参数说明：

• main：指代保存代码的 Python 文件名 main.py。
• app：指代在该文件中通过 app = FastAPI() 创建的对象。
• --reload：开启代码热重载，仅用于本地开发阶段。保存文件修改时，服务器会自动重载。

终端显示日志后，使用浏览器或 curl 访问 http://127.0.0.1:8000/，将收到对应的 JSON 响应：

{"message": "欢迎使用 FastAPI RESTful 服务", "status": "running"}

三、实现标准的 RESTful CRUD 接口

RESTful 架构风格的核心在于围绕“资源”进行建模，通过标准 HTTP 方法表达对资源的操作。下面以一个“待办事项（Todo）”管理服务为例，展示涵盖创建（POST）、查询（GET）、更新（PUT）与删除（DELETE）的完整接口实现。

完整 CRUD 服务代码实现

将 main.py 扩充为以下完整代码：

from typing import List, Optional
from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel

app = FastAPI(
    title="待办事项 RESTful API 服务",
    description="基于 FastAPI 实现的标准 CRUD 接口示例"
)

# 1. 定义数据模型
class TodoItem(BaseModel):
    id: Optional[int] = None
    title: str
    description: Optional[str] = ""
    completed: bool = False

# 内存模拟数据源
todos_db: List[TodoItem] = []
id_counter = 1

# 2. 查询列表（GET /todos）
@app.get("/todos", response_model=List[TodoItem], summary="获取待办列表")
def get_todos(completed: Optional[bool] = None):
    if completed is not None:
        return [item for item in todos_db if item.completed == completed]
    return todos_db

# 3. 查询单条（GET /todos/{todo_id}）
@app.get("/todos/{todo_id}", response_model=TodoItem, summary="获取单个待办详情")
def get_todo(todo_id: int):
    for item in todos_db:
        if item.id == todo_id:
            return item
    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="未找到指定的待办事项")

# 4. 创建资源（POST /todos）
@app.post("/todos", response_model=TodoItem, status_code=status.HTTP_201_CREATED, summary="创建新待办")
def create_todo(item: TodoItem):
    global id_counter
    item.id = id_counter
    id_counter += 1
    todos_db.append(item)
    return item

# 5. 更新资源（PUT /todos/{todo_id}）
@app.put("/todos/{todo_id}", response_model=TodoItem, summary="更新指定待办")
def update_todo(todo_id: int, updated_item: TodoItem):
    for index, item in enumerate(todos_db):
        if item.id == todo_id:
            updated_item.id = todo_id
            todos_db[index] = updated_item
            return updated_item
    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="未找到待更新的事项")

# 6. 删除资源（DELETE /todos/{todo_id}）
@app.delete("/todos/{todo_id}", status_code=status.HTTP_204_NO_CONTENT, summary="删除指定待办")
def delete_todo(todo_id: int):
    for index, item in enumerate(todos_db):
        if item.id == todo_id:
            todos_db.pop(index)
            return None
    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="未找到待删除的事项")

四、交互式 API 文档验证与接口测试

FastAPI 内置了符合 OpenAPI 规范的自动化文档生成系统。服务启动后，无需安装 Postman 或编写测试脚本，即可在浏览器中完成全套接口测试。

1. 访问 Swagger UI 在线文档

在浏览器打开 http://127.0.0.1:8000/docs。界面中罗列了全部声明的端点：

1. 点击 POST /todos 展开面板，点击右上角 Try it out。
2. 在 Request body 编辑框中填入数据：

   {
     "title": "编写 FastAPI 接口文档",
     "description": "整理快速搭建指南与测试步骤",
     "completed": false
   }

3. 点击 Execute 按钮发送请求，下方将立即展示 HTTP 201 响应码与包含分配 ID 的响应体。

2. 验证类型安全与自动拦截

如果在 POST /todos 中故意将 completed 设置为非法字符串，或者缺少必填的 title 字段，FastAPI 将直接拒绝进入业务函数，返回 HTTP 422 状态码（Unprocessable Entity），并在响应体中准确指示哪一个字段格式不合规。这种基于模式的防御性设计极大提升了服务的鲁棒性。

五、关键注意事项与开发建议

在日常开发与服务交付过程中，遵循以下约定可保证服务质量与可维护性：

• 路径参数与查询参数的区分：在路由装饰器 URL 中以花括号声明的（如 /todos/{todo_id}）为路径参数；而在函数签名中存在但未在路径中声明的参数（如 get_todos(completed: Optional[bool] = None)）自动被识别为 URL 查询参数（Query Parameter）。
• 生产环境禁用热重载：在生产部署中，应去除 --reload 参数，并搭配多工作进程启动（例如 uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4），以充分利用多核 CPU 资源。
• 响应模型过滤：通过 response_model 显式指定返回模式，FastAPI 会自动剔除模型之外的私有数据，防止数据库密码、内部令牌等敏感字段意外泄露。