FastAPI快速入门：从零搭建你的第一个RESTful API

1. 为什么选择FastAPI：一个开发者的真实感受

如果你和我一样，用Python写过Web应用，那你肯定对Flask和Django不陌生。Flask轻巧灵活，Django大而全，但它们都有一个共同点：写API文档和做数据验证的时候，总感觉有点繁琐，得自己折腾不少第三方库。直到我遇到了FastAPI，说实话，第一次用的时候，那种“丝滑”的感觉让我有点惊讶。它就像一个为你量身定做的现代API框架，把很多繁琐的事情都自动化了。最让我印象深刻的是，你只需要用Python的类型提示（就是给函数参数和返回值加上 int、str 这样的类型注解），FastAPI就能自动帮你做请求数据的验证、序列化，甚至生成漂亮的交互式API文档。这不仅仅是省了几行代码，更是把开发体验提升了一个档次。对于初学者或者想快速搭建后端服务的开发者来说，FastAPI的学习曲线非常平缓，你几乎可以立刻上手，把精力集中在业务逻辑上，而不是框架的配置上。所以，无论你是想做个个人项目的小接口，还是为公司搭建一个高性能的微服务，FastAPI都值得你花时间试一试。

2. 万事开头易：5分钟搞定开发环境

在开始写代码之前，我们需要先把“厨房”收拾好。这里我强烈推荐使用Python的虚拟环境，这就像给你的每个项目准备一个独立的工具箱，避免不同项目因为依赖库版本不同而“打架”。我习惯用 venv，它是Python自带的，不用额外安装。打开你的终端（Windows用CMD或PowerShell，Mac/Linux用Terminal），跟着我一步步来。

首先，找一个你喜欢的目录，创建一个项目文件夹，比如叫 fastapi_demo，然后进入这个文件夹。接下来，创建虚拟环境。命令很简单：python -m venv venv。执行后，你会看到文件夹里多了一个叫 venv 的目录，这就是你的独立环境了。创建好之后，需要激活它。在Windows上，命令是 venv\Scripts\activate；在Mac或Linux上，则是 source venv/bin/activate。激活后，你的命令行提示符前面通常会显示 (venv)，这就表示你已经在这个虚拟环境里了，之后所有pip安装的包都会装在这里面，不会影响系统其他Python项目。

环境激活了，现在来安装主角。FastAPI本身是一个框架，它需要一个ASGI服务器来运行，就像Flask需要WSGI服务器一样。这里我们选择Uvicorn，它是一个轻量级且高性能的异步服务器，和FastAPI是绝配。安装命令就一行：pip install fastapi uvicorn[standard]。注意这个 [standard]，它会让Uvicorn安装一些额外的依赖，比如用于高性能HTTP解析的 httptools 和用于事件循环的 uvloop，这样能获得更好的性能。当然，如果你只是想先试试，直接 pip install fastapi uvicorn 也行。安装过程很快，喝口水的功夫就好了。至此，你的开发环境就已经完全准备好了，是不是比想象中简单？

2.1 选个好用的编辑器：VS Code配置小贴士

工欲善其事，必先利其器。一个好的代码编辑器能极大提升效率。我个人非常推荐使用VS Code来开发FastAPI项目，它免费、强大，而且对Python的支持非常好。安装好VS Code后，你需要安装几个关键的扩展。首先肯定是微软官方的 Python 扩展，它提供了代码补全、调试、 linting等核心功能。其次，可以安装 Pylance，它能提供更智能的语言服务支持。你还可以搜索安装 FastAPI Snippets 这类扩展，它能提供一些代码片段，加快编写速度。

用VS Code打开我们刚才创建的 fastapi_demo 项目文件夹。第一次打开，它可能会问你是否信任该工作区的作者，选择“是”即可。然后，我们需要告诉VS Code使用我们刚创建的虚拟环境中的Python解释器。按下 Ctrl+Shift+P（Mac是 Cmd+Shift+P）打开命令面板，输入“Python: Select Interpreter”并选择。你应该能在列表里看到指向 venv 文件夹下的Python路径，选中它。这样，VS Code就会用虚拟环境里的Python和已安装的库来运行和调试你的代码了。你还可以在项目根目录创建一个 .vscode 文件夹，里面放一个 settings.json 文件，进行更多个性化设置，但上面这一步是确保环境正确的关键。

3. 从“Hello World”开始：编写你的第一个API

环境准备好了，编辑器也打开了，现在让我们来点真正的代码。在项目根目录下，创建一个新的Python文件，名字就叫 main.py。这个文件将是我们应用的入口。打开它，输入以下代码：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello World"}

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

让我来拆解一下这几行代码做了什么。第一行，我们从 fastapi 模块导入 FastAPI 类。第二行，我们创建了一个 FastAPI 的实例，并把它赋值给变量 app。这个 app 对象就是你整个Web应用的核心。

接下来是关键部分：定义路由和路径操作函数。@app.get("/") 是一个装饰器，它告诉FastAPI：下面的函数 read_root 负责处理发送到根路径“/”的HTTP GET请求。函数 read_root 定义为一个 async 异步函数（FastAPI完美支持异步，即使你先写成普通函数也没问题），它直接返回一个Python字典。FastAPI会自动把这个字典转换成JSON格式，作为HTTP响应返回给客户端。所以，访问根路径，你就会得到一个JSON响应：{"message": "Hello World"}。

第二个路由 @app.get("/items/{item_id}") 稍微复杂一点。它定义了一个路径参数 {item_id}。这意味着URL中 /items/ 后面的部分会被捕获并传递给函数。注意函数参数 item_id: int，这里使用了类型提示 int。FastAPI看到这个，会自动把从URL路径中获取的字符串转换成整数，如果用户传了一个不能转换成整数的值（比如/items/foo），FastAPI会自动返回一个清晰的错误响应，告诉你类型验证失败。参数 q: str = None 是一个查询参数，它是可选的（因为有默认值 None）。用户可以通过像 /items/42?q=searchterm 这样的URL来传递它。函数最后返回一个包含这两个值的字典。看，数据验证和解析，框架都默默帮你做好了。

4. 让服务跑起来：两种启动方式详解

代码写好了，怎么让它变成在网络上可以访问的服务呢？这就要靠我们之前安装的Uvicorn服务器了。这里我给你介绍两种最常用的启动方式，你可以根据场景选择。

第一种，也是最直接的方式：命令行启动。 确保你的终端当前目录在 main.py 所在的文件夹，并且虚拟环境已经激活。然后输入命令：uvicorn main:app --reload。我来解释一下这个命令：main 指的是我们的Python模块文件名（不含 .py 后缀），app 指的是在 main.py 文件中创建的 FastAPI 实例对象的变量名。--reload 参数是开发时的神器，它让服务器监听代码文件的变化，一旦你保存了修改，服务器会自动重启，让你立刻看到效果。运行后，终端会输出类似下面的信息：

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

这说明服务已经在本地 8000 端口启动了。你可以打开浏览器，访问 http://127.0.0.1:8000，就能看到 {"message":"Hello World"} 的JSON输出。访问 http://127.0.0.1:8000/items/123?q=test，则会看到 {"item_id":123,"q":"test"}。

第二种，在代码内部启动。 有时候，你可能想在Python脚本里直接控制服务器的启动，比如方便用IDE的调试功能。你可以在 main.py 文件底部添加如下代码：

if __name__ == "__main__":
    import uvicorn
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

然后，你就可以像运行普通Python脚本一样，在终端执行 python main.py，或者直接在VS Code里按F5（配置好调试后）来启动服务。uvicorn.run 函数的参数和命令行参数是类似的，host 和 port 可以指定监听的地址和端口，reload=True 同样启用热重载。我个人在开发初期喜欢用命令行方式，简单明了；在后期复杂调试时，则会用代码内启动配合IDE的断点功能。

4.1 调试技巧：如何快速定位问题

在开发过程中，遇到bug是常事。FastAPI和Uvicorn提供了一些便利的调试手段。首先，确保你在开发时始终使用 --reload 参数，这样改代码不用手动重启。其次，如果启动时报错，比如 ModuleNotFoundError: No module named 'main'，这通常是因为当前终端的工作目录不对，或者 uvicorn 命令中模块和实例名写错了，请仔细检查文件名和变量名是否匹配。

更深入的调试可以使用VS Code的调试功能。在VS Code中，点击左侧活动栏的“运行和调试”图标（或按 Ctrl+Shift+D），然后点击“创建一个 launch.json 文件”，选择“Python”，再选择“FastAPI”。这会在 .vscode 文件夹下生成一个调试配置文件。你可以在里面设置断点，然后按F5启动调试。当你的代码执行到断点处时，程序会暂停，你可以查看所有变量的当前值，一步步执行代码，这对于理解程序流程和查找复杂逻辑错误非常有帮助。另外，FastAPI在遇到请求验证错误时，返回的错误信息非常详细，会明确指出是哪个字段、出了什么问题，这本身就是一个强大的调试工具。

5. 自动生成的宝藏：交互式API文档

写完接口，最头疼的事情之一就是写API文档，还得维护它和代码同步。FastAPI把这个痛点彻底解决了，而且做得非常优雅。它基于OpenAPI标准，自动为你的应用生成交互式API文档。你不需要写任何额外的文档代码。

启动你的服务后，打开浏览器，访问 http://127.0.0.1:8000/docs。你会看到一个非常漂亮的、类似Swagger UI的页面。页面上列出了你定义的所有路由（我们目前有 / 和 /items/{item_id}）。每个路由都可以展开，看到它接受的参数、可能的响应。最神奇的是，你可以直接在页面上进行接口测试！点击一个路由的“Try it out”按钮，你可以填写路径参数（比如item_id填123）和查询参数（比如q填hello），然后点击“Execute”，页面就会向后端发送真实的HTTP请求，并把响应结果显示在下面。这不仅仅是文档，更是一个内置的API测试客户端，在开发联调时简直太方便了。

如果你更喜欢另一种风格的文档，FastAPI还提供了ReDoc格式的文档，访问 http://127.0.0.1:8000/redoc 即可。这个页面更侧重于阅读，排版清晰。我个人的习惯是，在开发时用 /docs 页面进行测试和调试，在给前端或其他协作者分享时，提供 /redoc 链接，因为它看起来更简洁专业。这个自动生成文档的功能，会随着你代码的修改（比如添加新的路由、修改参数）而实时更新，永远保持最新状态，这彻底避免了文档滞后于代码的问题。

6. 更进一步：处理POST请求和请求体

到目前为止，我们只处理了GET请求。Web API当然少不了创建数据的POST请求。FastAPI处理POST请求和请求体同样简单直观。让我们来添加一个创建新“物品”的接口。修改你的 main.py，首先需要从 pydantic 导入 BaseModel 来定义数据模型，然后在文件里添加以下代码：

from pydantic import BaseModel
from fastapi import FastAPI

app = FastAPI()

# 定义数据模型
class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

# 原有的GET路由...
# @app.get("/") ...
# @app.get("/items/{item_id}") ...

# 新增的POST路由
@app.post("/items/")
async def create_item(item: Item):
    # 这里通常会把item存入数据库
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

我们来分析一下新代码。我们定义了一个 Item 类，它继承自 BaseModel。在类里面，我们用类型提示声明了几个字段：name 是字符串且必须提供，description 是可选的字符串（默认None），price 是必须的浮点数，tax 是可选的浮点数。这个 Item 类就是一个Pydantic模型，它负责定义请求体的数据结构，并自动进行数据验证和解析。

在新路由 @app.post("/items/") 中，路径操作函数 create_item 有一个参数 item，其类型被标注为我们刚定义的 Item 模型。FastAPI会自动从HTTP请求的body中读取JSON数据，将其转换成 Item 实例，并进行验证。如果客户端发送的JSON缺少必需的 name 字段，或者 price 字段给了个字符串，FastAPI都会自动返回422错误，并详细指出错误所在。在函数内部，我们可以通过 item.dict() 将模型实例转换成普通的字典进行操作。这里模拟了一个计算含税价格的逻辑，然后将结果返回。

现在，重启你的服务（如果用了--reload则自动完成），打开 http://127.0.0.1:8000/docs 页面。你会看到多出来一个 POST /items/ 的接口。点击“Try it out”，在请求体JSON编辑框里输入类似 {"name": "Foo", "price": 50.5} 的内容，然后执行。你会看到服务器成功接收并返回了数据，如果尝试发送非法数据（比如 {"price": "expensive"}），则会立刻看到验证错误信息。通过这个例子，你就能体会到FastAPI“声明式”编程的威力：你只需要声明数据应该长什么样，剩下的脏活累活框架全包了。

6.1 结合路径参数和请求体

在实际应用中，经常需要同时使用路径参数和请求体，比如更新指定ID的物品。这也很简单，只需要在函数参数中同时声明它们即可：

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.dict()}

这个 update_item 函数同时接收路径参数 item_id 和请求体模型 item。FastAPI会正确地区分它们，分别从URL路径和请求体中获取数据。你可以在 /docs 中测试这个PUT接口，感受一下这种组合使用的便捷性。

7. 项目结构初探：从小Demo到可维护应用

当我们只写一个 main.py 文件时，所有代码堆在一起没问题。但随着功能增加，路由、数据模型、工具函数越来越多，把所有东西都塞进一个文件会变得难以维护。是时候考虑一个更清晰的项目结构了。这并不是FastAPI强制要求的，但是一种良好的工程实践。一个典型的、适合中小型FastAPI项目的结构可能如下所示：

fastapi_project/
├── app/
│   ├── __init__.py
│   ├── main.py          # 应用创建和主路由聚合点
│   ├── api/             # 存放所有路由端点
│   │   ├── __init__.py
│   │   ├── items.py     # 物品相关路由
│   │   └── users.py     # 用户相关路由
│   ├── models/          # SQLAlchemy等ORM模型（如果用到数据库）
│   │   ├── __init__.py
│   │   └── item.py
│   ├── schemas/         # Pydantic模型（请求/响应模型）
│   │   ├── __init__.py
│   │   └── item.py
│   └── core/            # 核心配置、依赖项等
│       ├── __init__.py
│       └── config.py
├── tests/               # 测试文件
│   ├── __init__.py
│   └── test_api.py
├── requirements.txt     # 项目依赖列表
└── .env                 # 环境变量（不要提交到git）

如何将我们之前的代码迁移到这个结构呢？首先，在项目根目录创建 app 文件夹和里面的子文件夹。然后，把 main.py 移动到 app/ 目录下，并对其内容进行拆分。新的 app/main.py 可能只负责创建 FastAPI 实例并导入其他路由：

from fastapi import FastAPI
from app.api import items, users  # 导入路由模块

app = FastAPI(title="我的FastAPI项目")

# 包含（include）路由
app.include_router(items.router, prefix="/api/v1/items", tags=["items"])
app.include_router(users.router, prefix="/api/v1/users", tags=["users"])

接着，在 app/api/items.py 中，我们放置所有与物品相关的路由逻辑：

from fastapi import APIRouter, HTTPException
from app.schemas.item import ItemCreate, ItemResponse  # 导入Pydantic模型
# 假设有一个数据库操作层
# from app.crud import item as item_crud

router = APIRouter()

@router.get("/{item_id}", response_model=ItemResponse)
async def read_item(item_id: int):
    # item = await item_crud.get(item_id)
    # if not item:
    #     raise HTTPException(status_code=404, detail="Item not found")
    # return item
    return {"id": item_id, "name": "示例物品"}  # 模拟返回

@router.post("/", response_model=ItemResponse)
async def create_item(item_in: ItemCreate):
    # 创建逻辑
    return {"id": 1, **item_in.dict()}

注意这里我们使用了 APIRouter。它就像是一个“子应用”或“路由的集合”，允许你将相关的路由分组管理。然后在主 app 中用 include_router 将其挂载进来，并可以统一添加前缀（如/api/v1/items）和标签（用于文档分类）。Pydantic模型则定义在 app/schemas/item.py 中，清晰地分离了数据验证逻辑。这样的结构虽然一开始看起来有点复杂，但当你的API扩展到几十个端点时，它的可维护性优势就非常明显了，每个文件职责单一，查找和修改代码都很方便。

8. 部署准备：从开发到生产的第一步

在本地开发调试没问题后，你可能会想把它部署到服务器上，让其他人也能访问。从开发模式切换到生产环境，有一些注意事项。首先，务必移除 --reload 参数。热重载在生产环境是不安全且不必要的。生产环境我们追求的是稳定和性能。

最简单的生产启动命令是：uvicorn app.main:app --host 0.0.0.0 --port 80。这里 host 设置为 0.0.0.0 表示监听所有网络接口，这样服务器外部的请求才能访问到。端口 80 是HTTP默认端口。但直接用Uvicorn单进程运行，虽然性能不错，但可能不够健壮（比如一个 worker 进程崩溃，整个服务就停了）。对于要求更高的生产环境，常见的做法是使用 Gunicorn 作为进程管理器，配合 Uvicorn 的 worker 类。Gunicorn可以管理多个worker进程，提高并发能力和稳定性。安装Gunicorn：pip install gunicorn。然后使用如下命令启动：

gunicorn -w 4 -k uvicorn.workers.UvicornWorker app.main:app --bind 0.0.0.0:8000

这个命令中，-w 4 指定启动4个worker进程，-k uvicorn.workers.UvicornWorker 指定使用Uvicorn的worker来运行FastAPI应用。worker数量通常设置为CPU核心数的1-2倍。Gunicorn会负责负载均衡和进程管理。

使用Docker容器化部署是现在更主流和推荐的方式，它能保证环境一致性。在项目根目录创建一个 Dockerfile：

FROM python:3.9-slim

WORKDIR /app

# 复制依赖文件并安装
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY ./app ./app

# 运行命令
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]

然后构建镜像：docker build -t my-fastapi-app .，运行容器：docker run -d -p 80:80 --name my-api my-fastapi-app。这样你的应用就在一个隔离的容器中运行了。你还可以使用 docker-compose.yml 来更方便地定义和管理多容器服务（比如同时包含数据库和Redis）。

最后，别忘了安全相关配置。在生产环境，你应该通过环境变量来设置敏感信息（如数据库密码、API密钥），而不是硬编码在代码里。可以使用 python-dotenv 库在代码中读取 .env 文件，但在生产环境，更常见的做法是直接在容器或服务器环境中设置这些变量。此外，考虑在FastAPI应用前放置一个反向代理（如Nginx），它可以处理静态文件、SSL/TLS加密（HTTPS）、负载均衡和缓冲，让你的应用更安全、高效。