FastAPI实战：5分钟搭建你的第一个RESTful API（附完整代码）

最新推荐文章于 2026-07-16 11:19:13 发布

原创

最新推荐文章于 2026-07-16 11:19:13 发布 · 1k 阅读

FastAPI实战：5分钟搭建你的第一个RESTful API（附完整代码）

如果你是一位Python开发者，最近在寻找一个既能快速上手、性能又足够强悍的Web框架来构建API，那么FastAPI很可能就是你一直在找的那个答案。我第一次接触FastAPI是在一个需要快速交付原型的项目中，当时团队对Flask的异步支持不够满意，而Django又显得过于臃肿。FastAPI的出现，几乎完美地解决了我们的痛点——它基于Python的类型提示系统，让代码既清晰又安全，还能自动生成交互式API文档，开发效率直接翻倍。

这篇文章就是为你准备的。无论你是刚接触Web开发的初学者，还是从Flask或Django转过来的老手，我都会带你从零开始，在五分钟内搭建起一个功能完整的RESTful API服务。我们不仅会写代码，还会深入理解FastAPI背后的设计哲学，让你知道为什么它能如此高效。准备好了吗？让我们开始吧。

1. 环境准备与第一个“Hello World”

在开始写代码之前，我们需要确保开发环境已经就绪。FastAPI要求Python 3.7及以上版本，我强烈建议你使用虚拟环境来管理项目依赖，这样可以避免不同项目之间的包版本冲突。

1.1 创建虚拟环境与安装依赖

打开你的终端，执行以下命令来创建一个新的项目目录并设置虚拟环境：

# 创建项目目录
mkdir fastapi-quickstart
cd fastapi-quickstart

# 创建虚拟环境（这里使用venv，你也可以用conda或virtualenv）
python -m venv venv

# 激活虚拟环境
# 在Windows上：
venv\Scripts\activate
# 在macOS/Linux上：
source venv/bin/activate

虚拟环境激活后，你的命令行提示符前应该会出现(venv)字样。接下来安装FastAPI及其依赖：

pip install fastapi uvicorn

这里简单解释一下这两个包的作用：

fastapi：框架本身，提供了构建API的所有核心功能。
uvicorn：一个轻量级的ASGI服务器，用于运行FastAPI应用。ASGI是WSGI的异步版本，能够更好地处理并发请求。

注意：如果你看到有些教程推荐安装fastapi[all]，这确实会安装所有可选依赖，但对于初学者和大多数生产场景，只安装fastapi和uvicorn就足够了。额外的依赖（如python-multipart用于表单处理）可以在需要时再单独安装。

1.2 编写第一个API端点

现在让我们创建第一个FastAPI应用。在项目根目录下创建一个名为main.py的文件，用你喜欢的编辑器打开它，输入以下代码：

from fastapi import FastAPI

# 创建FastAPI应用实例
app = FastAPI()

# 定义一个简单的GET端点
@app.get("/")
async def read_root():
    return {"message": "Hello, FastAPI!"}

# 定义一个带路径参数的GET端点
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query": q}

让我解释一下这段代码做了什么：

导入FastAPI类：这是框架的核心类，每个FastAPI应用都是它的一个实例。
创建应用实例：app = FastAPI()创建了一个新的应用。你可以在这里传递各种配置参数，比如应用标题、描述、版本等，但为了简单起见，我们先使用默认配置。
定义路由处理函数：使用装饰器语法@app.get()来注册路由。这里的"/"表示根路径，"/items/{item_id}"表示一个带路径参数的路由。
类型提示的魔力：注意read_item函数中的item_id: int。这不是普通的注释，而是Python的类型提示。FastAPI会利用这个信息：
- 自动将URL中的item_id转换为整数
- 如果客户端传递了非整数值，自动返回422错误
- 在自动生成的API文档中显示正确的参数类型

1.3 启动服务器并测试

保存文件后，回到终端，运行以下命令启动开发服务器：

uvicorn main:app --reload

这个命令有几个关键部分：

main：指的是main.py文件（Python模块）
app：指的是我们在main.py中创建的app变量
--reload：启用热重载，代码修改后服务器会自动重启

启动成功后，你应该能看到类似这样的输出：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using WatchFiles
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

现在打开浏览器，访问http://127.0.0.1:8000/，你会看到JSON响应：

{"message": "Hello, FastAPI!"}

再试试带参数的端点：http://127.0.0.1:8000/items/42?q=test，你会得到：

{"item_id": 42, "query": "test"}

如果尝试传递非整数的item_id，比如http://127.0.0.1:8000/items/abc，FastAPI会自动返回一个详细的错误响应，告诉你参数类型不匹配。

2. 深入理解FastAPI的核心特性

现在你已经成功运行了第一个FastAPI应用，让我们深入了解一下它的一些核心特性。这些特性是FastAPI区别于其他Python Web框架的关键所在。

2.1 自动生成的交互式API文档

FastAPI最令人印象深刻的功能之一就是自动生成的API文档。启动服务器后，访问以下两个URL：

Swagger UI文档：http://127.0.0.1:8000/docs
ReDoc文档：http://127.0.0.1:8000/redoc

Swagger UI提供了一个交互式界面，你可以直接在浏览器中测试API端点。点击"Try it out"按钮，输入参数，然后点击"Execute"，就能看到实际的请求和响应。这对于前端开发者和测试人员来说简直是福音——他们不再需要依赖后端的口头描述或静态文档。

ReDoc则提供了更简洁、更适合阅读的文档格式。两种文档都是基于OpenAPI标准自动生成的，这意味着你写的类型提示和函数文档字符串（docstring）都会直接反映在文档中。

让我展示一下如何通过添加文档字符串来增强API文档：

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    """
    根据ID获取项目详情
    
    - **item_id**: 项目的唯一标识符，必须是整数
    - **q**: 可选的查询字符串，用于过滤结果
    
    返回一个包含项目ID和查询字符串的JSON对象
    """
    return {"item_id": item_id, "query": q}

添加文档字符串后，刷新/docs页面，你会看到更详细的端点描述。这种"代码即文档"的方式大大减少了维护文档的工作量。

2.2 请求体与Pydantic模型

在真实的API开发中，我们经常需要处理复杂的请求数据。FastAPI通过集成Pydantic库，让数据验证和序列化变得异常简单。Pydantic是一个基于Python类型提示的数据验证库，它能够自动验证输入数据的类型和约束。

让我们创建一个处理POST请求的端点，用于创建新的项目：

from fastapi import FastAPI
from pydantic import BaseModel, Field
from typing import Optional
from datetime import datetime

app = FastAPI()

# 定义数据模型
class ItemCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=100, description="项目名称")
    description: Optional[str] = Field(None, max_length=500, description="项目描述")
    price: float = Field(..., gt=0, description="价格，必须大于0")
    tax: Optional[float] = Field(None, ge=0, le=1, description="税率，0到1之间")
    tags: list[str] = Field(default_factory=list, description="标签列表")
    
    # 模型配置
    class Config:
        schema_extra = {
            "example": {
                "name": "Awesome Item",
                "description": "A very awesome item",
                "price": 35.99,
                "tax": 0.2,
                "tags": ["electronics", "gadget"]
            }
        }

class ItemResponse(ItemCreate):
    id: int
    created_at: datetime
    updated_at: datetime

# 模拟数据库
items_db = {}
item_id_counter = 1

@app.post("/items/", response_model=ItemResponse, status_code=201)
async def create_item(item: ItemCreate):
    """
    创建新项目
    
    接收一个JSON请求体，包含项目的详细信息。
    返回创建的项目数据，包括系统生成的ID和时间戳。
    """
    global item_id_counter
    
    # 在实际应用中，这里会将数据保存到数据库
    new_item = ItemResponse(
        id=item_id_counter,
        name=item.name,
        description=item.description,
        price=item.price,
        tax=item.tax,
        tags=item.tags,
        created_at=datetime.now(),
        updated_at=datetime.now()
    )
    
    items_db[item_id_counter] = new_item.dict()
    item_id_counter += 1
    
    return new_item

这段代码展示了几个重要概念：

Pydantic模型定义：ItemCreate类定义了创建项目时需要的数据结构。每个字段都有类型提示和验证规则：
- Field(...)表示必填字段
- min_length和max_length限制字符串长度
- gt（大于）、ge（大于等于）等约束数值范围
- default_factory=list提供默认值工厂函数
请求体自动验证：当客户端发送POST请求到/items/时，FastAPI会自动：
- 解析JSON请求体
- 根据ItemCreate模型验证数据
- 如果验证失败，返回详细的错误信息
- 如果验证通过，将数据转换为ItemCreate实例
响应模型：response_model=ItemResponse告诉FastAPI，这个端点应该返回ItemResponse类型的数据。FastAPI会自动：
- 过滤掉响应中不在ItemResponse中定义的字段
- 将Python对象转换为JSON
- 在API文档中显示正确的响应结构
状态码：status_code=201表示资源创建成功，这是RESTful API的最佳实践。

现在你可以在Swagger UI中测试这个端点。点击/items/的POST方法，使用"Example Value"填充请求体，然后点击"Execute"。你会看到服务器返回201状态码和创建的项目数据。

2.3 路径参数、查询参数和请求体的组合使用

在实际开发中，我们经常需要同时使用多种参数类型。FastAPI能够智能地区分它们：

参数类型	声明位置	示例	用途
路径参数	URL路径中	`/items/{item_id}`	标识特定资源
查询参数	URL问号后	`?skip=0&limit=10`	过滤、分页、排序
请求体	POST/PUT请求体	JSON对象	创建或更新资源

下面是一个综合示例：

from fastapi import Query, Path
from typing import List

@app.get("/items/")
async def list_items(
    skip: int = Query(0, ge=0, description="跳过的记录数"),
    limit: int = Query(10, ge=1, le=100, description="每页记录数"),
    tags: List[str] = Query(None, description="按标签过滤")

标签