FastAPI入门教程：自定义数据类型

欢迎开始你的Web开发之旅！

如果你已经熟悉Python的基本语法，但从未接触过Web开发，那么FastAPI是你的完美起点。它简洁、快速，而且非常友好。本教程将聚焦于自定义数据类型，让你在短时间内体验到成功的喜悦。

第一步：安装必备工具

首先，确保你的电脑上安装了Python。然后，打开终端或命令行，运行以下命令来安装FastAPI和服务器：

pip install fastapi uvicorn

• FastAPI：一个现代、快速的Web框架，用于构建API。
• Uvicorn：一个轻量级的ASGI服务器，用来运行FastAPI应用。

安装完成后，你就准备好创建第一个应用了！

成功时刻 #1：创建并运行第一个FastAPI应用

创建一个新文件，命名为 main.py，并写入以下代码：

from fastapi import FastAPI

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

@app.get("/")  # 定义一个GET请求的路由，路径为根目录
def read_root():
    return {"message": "Hello, World!"}

保存文件。然后，在终端中运行：

uvicorn main:app --reload

• main:app 告诉Uvicorn从 main.py 文件中加载 app 对象。
• --reload 参数让服务器在代码变化时自动重启，方便调试。

现在，打开浏览器，访问 http://localhost:8000。你应该看到 {"message": "Hello, World!"} 的JSON响应。恭喜！你的第一个Web API已经成功运行了！这就像点亮了一盏灯，瞬间照亮了你的编程世界。

为什么需要自定义数据类型？

在真实世界中，Web应用经常需要处理用户输入的数据，比如注册表单或订单信息。这些数据不是随意的字符串或数字；它们有特定的格式要求。例如，用户名应该是文本，年龄必须是正整数，邮箱地址需要符合特定模式。

FastAPI使用一个叫做Pydantic的库来帮助我们定义这些数据规则，这就是自定义数据类型。

生活化类比：餐厅点餐

想象一下你去餐厅点餐。菜单上列出了每道菜的名称、价格和可选配料。当你告诉服务员你想点什么时，服务员会检查：这道菜在菜单上吗？价格对吗？你选的配料是否可选？这其实就是数据验证的过程。在FastAPI中，自定义数据类型就像是菜单上的菜品描述——它精确地告诉API应该接受什么样的数据，自动帮你过滤掉错误信息，就像服务员确保你的订单正确无误一样。

成功时刻 #2：定义并使用自定义数据类型

现在，让我们来定义一个简单的用户模型。修改 main.py，添加以下代码：

from fastapi import FastAPI
from pydantic import BaseModel  # 导入Pydantic的BaseModel类

app = FastAPI()

# 定义一个用户类，继承自BaseModel
class User(BaseModel):
    name: str      # 用户名，必须是字符串
    age: int       # 年龄，必须是整数
    email: str     # 邮箱，必须是字符串

# 添加一个POST端点来创建用户
@app.post("/user/")
def create_user(user: User):  # FastAPI会自动将请求体转换为User对象
    # user.dict() 将User对象转换为字典，方便返回
    return {"user": user.dict(), "message": "User created successfully!"}

# 保留之前的GET端点
@app.get("/")
def read_root():
    return {"message": "Hello, World!"}

保存文件，服务器会自动重启（因为用了 --reload）。

现在，使用一个API测试工具来尝试这个新端点。如果你没有安装其他工具，可以用浏览器扩展如Postman，或者如果你在终端中，可以用 curl 命令。

使用curl发送POST请求：

curl -X POST "http://localhost:8000/user/" -H "Content-Type: application/json" -d '{"name":"Alice","age":30,"email":"alice@example.com"}'

或者，如果你用Postman，设置方法为POST，URL为 http://localhost:8000/user/，在Body中选择raw和JSON格式，输入同样的JSON内容。

你应该收到这样的响应：

{
  "user": {
    "name": "Alice",
    "age": 30,
    "email": "alice@example.com"
  },
  "message": "User created successfully!"
}

太棒了！FastAPI自动验证了数据：如果发送一个无效的数据，比如 "age": "thirty"（字符串而不是数字），它会返回一个清晰的错误消息。这就像是服务员提醒你年龄必须填数字一样贴心。

成功时刻 #3：扩展应用，处理更多数据类型

让我们再添加一个GET端点来获取用户信息，展示如何结合自定义数据类型和路径参数。

修改 main.py，添加以下代码：

# 模拟一些用户数据存储在内存中
users = {1: {"name": "Bob", "age": 25, "email": "bob@example.com"}}

@app.get("/user/{user_id}")
def get_user(user_id: int):  # user_id来自路径参数，自动转换为整数
    if user_id in users:
        return users[user_id]
    else:
        return {"error": "User not found"}

保存文件。现在，访问 http://localhost:8000/user/1，你会看到Bob的信息。试着访问一个不存在的ID，比如 http://localhost:8000/user/2，它会返回错误。这就像在餐厅查询一个不存在的菜品一样，系统会礼貌地告诉你没有找到。

总结与下一步

通过这个简短教程，你已经：

• 安装了FastAPI并运行了第一个应用——这就像打开了新世界的大门。
• 定义了自定义数据类型——使用Pydantic创建了用户模型，确保数据输入的正确性。
• 处理了POST和GET请求——学会了如何接收和返回数据。

自定义数据类型让你的API更健壮、更易于维护，就像给餐厅菜单添加了清晰的说明一样。你已经迈出了Web开发的重要一步！

下一步建议

• 探索更多Pydantic特性，如添加默认值、验证规则（例如，邮箱格式）。
• 学习FastAPI的其他功能，如依赖注入、认证和文档自动生成。
• 尝试构建一个完整的CRUD（创建、读取、更新、删除）应用。

保持动手实践，你会很快成长为一名自信的Web开发者。Happy coding，继续享受编程的乐趣吧！