Python使用FastAPI从零开始构建你的第一个Web API

2026-03-24 08:22:50 作者：小庄-Python办公

在现代Web开发中,构建高效、可靠且易于维护的API是核心技能之一,本文专为零基础的初学者设计,我们将以系统且专业的步骤,带你从零开始编写并运行你的第一个FastAPI应用,有需要的小伙伴可以了解下

引言

在现代Web开发中，构建高效、可靠且易于维护的API是核心技能之一。如果你正在寻找一个现代化的Python Web框架，FastAPI 绝对是不容错过的选择。

顾名思义，FastAPI以**“快”**著称。它不仅运行速度极快（性能可与NodeJS和Go媲美），而且开发速度极快。得益于Python的类型提示（Type Hints），FastAPI能够自动校验数据并生成交互式API文档，极大地提升了开发体验。

本文专为零基础的初学者设计，我们将以系统且专业的步骤，带你从零开始编写并运行你的第一个FastAPI应用。

前置准备

在开始编写代码之前，请确保你的开发环境满足以下要求：

Python环境：FastAPI需要 Python 3.7 或更高版本。可以通过在终端输入 python --version 来检查你的版本。

基础知识：了解Python的基本语法（如函数、字典、类的基本概念）。

安装依赖库：我们需要安装两个核心库：fastapi（框架本身）和 uvicorn（用于运行FastAPI的轻量级Web服务器）。

打开你的终端（Terminal或CMD），运行以下命令：

pip install fastapi
pip install "uvicorn[standard]"

逐步指南：构建你的第一个API

第一步：编写最基础的代码

创建一个新的Python文件，命名为 main.py。使用你喜欢的代码编辑器（如VS Code、PyCharm），输入以下基础代码：

from fastapi import FastAPI

# 创建FastAPI实例
app = FastAPI()

# 定义一个路由和处理函数
@app.get("/")
def read_root():
    return {"message": "欢迎来到FastAPI的世界！"}

原理解析：

app = FastAPI()：这是你的API应用的核心对象。
@app.get("/")：这是一个装饰器。它告诉FastAPI，当用户通过 GET 方法访问根路径 "/`" 时，应该执行下面的函数。
return {"message": ...}：FastAPI会自动将Python字典转换为JSON格式返回给客户端。

第二步：启动你的应用

FastAPI本身不包含Web服务器，我们需要使用前面安装的Uvicorn来运行它。

在包含 main.py 的目录下，打开终端并运行：

uvicorn main:app --reload

命令解析：

main：你的Python文件名（不包含 .py）。
app：你在代码中创建的FastAPI实例变量名。
--reload：热更新模式。只要你修改了代码并保存，服务器就会自动重启，非常适合开发阶段使用。

终端会输出类似 Uvicorn running on http://127.0.0.1:8000 的信息。打开浏览器访问该地址，你将看到：
{"message": "欢迎来到FastAPI的世界！"}

第三步：体验自动生成的交互式文档

这是FastAPI最强大的功能之一！你不需要手写任何API文档。在浏览器中访问：http://127.0.0.1:8000/docs

你将看到一个由Swagger UI自动生成的、美观且可交互的API文档页面。你甚至可以直接在这个页面上点击 “Try it out” 来测试你的API。

(提示：访问 http://127.0.0.1:8000/redoc 可以看到另一种风格的文档)

第四步：接收路径参数与查询参数

让我们为API添加更多的功能。修改 main.py，添加以下代码：

# 路径参数示例
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query_string": q}

原理解析：

路径参数：{item_id} 会捕捉URL中的对应部分。因为我们声明了 item_id: int，FastAPI会自动将URL中的字符串转换为整数。如果用户输入 /items/abc，FastAPI会自动返回一个友好的错误提示，而不是让程序崩溃。
查询参数：函数参数 q 没有在路径中定义，它自动成为查询参数。例如访问 /items/5?q=apple，item_id 为 5，q 为 “apple”。

第五步：处理POST请求与数据校验

当客户端需要向服务器发送数据（如注册用户）时，通常使用 POST 请求。FastAPI与 Pydantic 库深度集成，让数据验证变得极为简单。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 定义数据模型
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None # 可选参数，默认为None

@app.post("/items/")
def create_item(item: Item):
    # 此时 item 已经是被校验过的 Item 对象
    return {"item_name": item.name, "item_price": item.price, "status": "创建成功"}

在这个例子中，如果客户端发送的JSON中 price 不是数字，FastAPI会自动拒绝该请求并返回具体的错误信息。你无需编写复杂的 if/else 验证逻辑。

常见避坑指南

对于初学者，在使用FastAPI时容易遇到以下几个常见问题：

忘记启动Uvicorn：初学者常习惯直接用 python main.py 运行，这在FastAPI中不会启动服务（除非你在代码末尾写了 uvicorn.run(...)）。请始终习惯使用 uvicorn main:app --reload 启动。
忽略类型提示（Type Hints）：FastAPI的强大在于类型提示。如果你写了 def read_item(item_id): 而不是 def read_item(item_id: int):，你将失去自动数据转换和文档生成的优势。
路由顺序冲突：FastAPI是按顺序匹配路由的。如果你先定义了 @app.get("/users/{user_id}")，再定义 @app.get("/users/me")，当访问 /users/me 时，FastAPI会认为 “me” 是一个 user_id。解决办法：将固定路径定义在动态路径之前。

学习资源与结语

恭喜你！你已经成功编写并运行了你的第一个FastAPI应用，掌握了路由定义、参数接收和数据校验的核心概念。FastAPI凭借其出色的开发体验和卓越的性能，正在成为Python后端开发的新标准。

这只是一个开始，FastAPI还支持依赖注入、后台任务、WebSocket等高级功能。为了进一步提升，建议你参考以下资源：

FastAPI 官方文档：https://fastapi.tiangolo.com/ （极力推荐！这是业界公认写得最好的技术文档之一，且包含中文版）。
Pydantic 官方文档：了解更多关于数据验证的进阶用法。

继续构建、不断尝试，祝你在Python Web开发的旅程中取得成功！

到此这篇关于Python使用FastAPI从零开始构建你的第一个Web API的文章就介绍到这了,更多相关Python FastAPI使用内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！