Python开发API接口教程：FastAPI快速上手指南

FastAPI成为Python API开发首选框架的原因包括高性能、出色的开发者体验和现代化设计。它基于Starlette和Pydantic，支持异步处理，配合Uvicorn服务器提升吞吐量；通过Python类型提示自动完成数据验证、序列化及交互式文档生成，极大简化开发流程；其Pythonic设计和模块化结构使学习曲线平缓，便于集成数据库和认证机制。使用FastAPI处理请求体时，借助Pydantic定义数据模型实现自动验证与解析，确保数据符合预期并减少错误。接口设计中，路由参数通过URL路径接收资源标识，查询参数提供可选配置增强灵活性，响应模型则规范输出结构并保证一致性。

用Python开发API接口，FastAPI是一个非常现代且高效的选择。它基于Starlette和Pydantic，能自动处理数据验证、序列化，并生成交互式API文档，极大地简化了开发流程。

解决方案

要快速上手FastAPI，你需要先安装它以及一个ASGI服务器，比如Uvicorn。

pip install fastapi uvicorn

接着，创建一个简单的Python文件，比如 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):
    # item_id 会自动转换为整数
    # q 是一个可选的查询参数
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

然后，在命令行中运行你的应用：

uvicorn main:app --reload

现在，打开浏览器访问 http://127.0.0.1:8000，你会看到 {"message": "Hello, FastAPI!"}。访问 http://127.0.0.1:8000/docs，你还能看到自动生成的API文档（Swagger UI），这简直是开发者的福音。

FastAPI为何成为Python API开发的新宠？

说实话，当我第一次接触FastAPI时，它给我的感觉就是“这才是现代Python Web开发该有的样子”。它之所以能迅速崛起，有几个核心原因。首先是性能，它建立在Starlette（一个轻量级ASGI框架）和Pydantic（数据验证库）之上，天然支持异步，配合Uvicorn这种高性能服务器，吞吐量非常可观。这对于需要处理大量并发请求的API来说，简直是福音。

其次，开发者体验好到让人惊喜。你只需要用Python的类型提示（Type Hints）来定义你的请求参数、响应数据模型，FastAPI就能自动为你完成数据验证、序列化、反序列化，并且生成完整的交互式API文档（Swagger UI和ReDoc）。这意味着你写更少的代码，却能获得更强大的功能和更好的可维护性。以前我们可能要手动写很多参数校验的逻辑，现在这些都由Pydantic在幕后默默完成了。

再者，它的设计理念非常Pythonic，学习曲线平缓。如果你熟悉Python的类型提示，几乎可以无缝切换。而且，它非常模块化，你可以根据需要轻松集成各种数据库、认证方式等。我个人觉得，它就像Python Web框架中的一股清流，既保持了Python的简洁和优雅，又提供了现代Web服务所需的一切高级特性。

如何在FastAPI中处理请求体和数据模型？

在开发API时，处理客户端发送过来的数据（请求体）是一个核心任务，特别是对于POST、PUT等请求。FastAPI在这里做得非常出色，它利用Pydantic库来定义数据模型，从而实现强大的数据验证和序列化功能。

想象一下，你需要接收用户的注册信息，比如用户名和密码。你可以这样定义一个Pydantic模型：

from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 定义一个用户模型
class User(BaseModel):
    name: str
    email: str
    password: str
    # age 是一个可选字段，默认值是 None
    age: Optional[int] = None 

# 定义一个POST接口，接收User模型的数据
@app.post("/users/")
async def create_user(user: User):
    # user 参数会自动被FastAPI解析和验证
    # 如果请求体不符合User模型的定义，FastAPI会自动返回422 Unprocessable Entity错误
    print(f"Received user: {user.dict()}") # user.dict() 可以将Pydantic模型转换为字典
    return {"message": "User created successfully", "user_data": user}

当你向 /users/ 发送一个POST请求，请求体是JSON格式，FastAPI会根据 User 模型的定义来验证数据。如果缺少了 name、email 或 password，或者 age 不是整数类型，FastAPI会立即返回一个带有详细错误信息的 422 Unprocessable Entity 响应。这比手动检查每个字段是否存在、类型是否正确要高效得多，也大大减少了出错的可能性。而且，这个模型还会自动出现在API文档中，让前端开发者一目了然地知道需要发送什么样的数据。

FastAPI中的路由参数、查询参数与响应模型实践

接口设计中，灵活地接收各种参数至关重要。FastAPI在这方面提供了非常直观且强大的机制，结合Python的类型提示，让参数的定义和使用变得异常清晰。

路由参数（Path Parameters）

路由参数是URL路径中的一部分，通常用于标识资源。比如 /items/123 中的 123 就是一个路由参数。

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

@app.get("/items/{item_id}")
async def get_item(item_id: int): # item_id 会自动被转换为整数
    return {"item_id": item_id, "description": f"This is item {item_id}"}

这里 item_id: int 不仅定义了参数名，还指定了其类型。如果请求的 item_id 不是一个合法的整数，FastAPI会自动返回错误。

查询参数（Query Parameters）

查询参数则出现在URL的问号后面，例如 /search?keyword=python&limit=10。它们通常是可选的，或者有默认值。

@app.get("/search/")
async def search_items(keyword: str, limit: int = 10, offset: int = 0):
    # keyword 是必选的查询参数
    # limit 和 offset 是可选的，有默认值
    return {
        "results": f"Searching for '{keyword}' with limit {limit} and offset {offset}",
        "data": [f"item {i}" for i in range(offset, offset + limit)]
    }

这里 limit: int = 10 定义了一个名为 limit 的整数类型查询参数，如果客户端不提供，则默认为 10。这让接口的灵活性大大增强。

响应模型（Response Models）

除了输入验证，FastAPI还能通过 response_model 参数来定义接口的输出数据结构。这不仅能自动序列化响应数据，还能在API文档中清晰地展示响应的JSON结构。

from pydantic import BaseModel

# 定义一个响应数据模型
class ItemResponse(BaseModel):
    item_id: int
    name: str
    price: float
    is_offer: Optional[bool] = None

@app.get("/items/{item_id}/details", response_model=ItemResponse)
async def get_item_details(item_id: int):
    # 假设从数据库获取数据
    item_data = {"item_id": item_id, "name": f"Product {item_id}", "price": item_id * 10.5}
    # FastAPI会自动根据ItemResponse模型对item_data进行验证和序列化
    return item_data

即使 get_item_details 函数返回的数据包含了 ItemResponse 模型中没有的字段，FastAPI在响应时也会自动过滤掉这些多余的字段。这保证了API响应的一致性和安全性，也让前端开发者能更放心地依赖文档。这些功能，让接口的输入输出变得异常清晰，几乎不用额外文档就能明白。