前言

在 Python Web 开发中，FastAPI 凭借高性能、类型安全和自动文档的优势，成为前后端分离项目的热门选择。本教程将从环境搭建到接口调试，一步步带你上手 FastAPI，同时解答虚拟环境、项目运行和文档访问的核心问题。

一、环境准备：在 PyCharm 中创建 FastAPI 项目

1.1 为什么要创建虚拟环境

依赖隔离：每个项目的依赖包互不影响，彻底解决版本冲突。
环境干净：不会污染系统全局 Python，误操作也不会导致其他项目崩溃。
版本兼容：同一设备上，不同项目可使用不同 Python 版本，无需修改系统默认配置。

因此，创建虚拟环境是 FastAPI 开发的第一步，也是规范 Python 项目的基础。

1.2 PyCharm 中创建项目并配置虚拟环境

1. 打开 PyCharm，点击 New Project。
2. 项目类型选择：
专业版：直接选择 FastAPI 模板，PyCharm 会自动生成基础文件结构。
社区版：选择 Pure Python，后续手动配置依赖。
3. 配置项目路径，勾选 Create a virtual environment using venv，选择项目对应的 Python 解释器。
4. 点击 Create，PyCharm 会自动创建项目目录并激活虚拟环境。

说明：即使通过 PyCharm 模板创建了 FastAPI 项目，也建议手动执行以下依赖安装和验证步骤，确保项目环境配置正确，避免后续运行报错。

# 安装 FastAPI 核心包 + 标准依赖（含 Uvicorn 服务器）
pip install "fastapi[standard]"

# 验证 FastAPI 版本
python -c "import fastapi; print(fastapi.__version__)"
# 验证 Uvicorn 服务器
uvicorn --version

二、FastAPI 入门程序：从编写到运行

2.1 编写你的第一个 FastAPI 接口

在项目根目录创建 main.py，写入基础接口代码：

# 导入服务器
import uvicorn

# 导入FastAPI

from fastapi import FastAPI

app = FastAPI()

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

@app.get("/hello/{name}")
async def hello(name: str):
    return {"message": f"Hello {name}"}

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

2.2 怎么运行 FastAPI 项目

FastAPI 是基于 ASGI 协议的 Web 框架，需要搭配 Uvicorn 服务器运行，以下是两种常用方式：

方式 1：PyCharm 图形化运行
1.点击 PyCharm 右上角的 Edit Configurations。

2.点击左上角 + 号，选择 FastAPI（或 Uvicorn）

3.配置如下：
Name：FastAPI Demo（自定义名称）
Module：uvicorn
Parameters：main:app --reload（main 是文件名，app 是 FastAPI 实例名，–reload 开启热重载）
Python interpreter：选择项目的虚拟环境解释器

4.点击 OK 保存配置，点击运行按钮启动服务。

方式 2：终端命令运行

直接在 PyCharm 内置终端执行：

# 方式1：FastAPI 内置 CLI 命令（自动开启热重载）
fastapi dev main.py

# 方式2：Uvicorn 原生命令
uvicorn main:app --reload

运行成功验证
终端会输出以下信息，说明服务已正常启动：

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

三、自动生成的交互式文档：接口调试零成本

FastAPI 最亮眼的特性之一，就是根据代码自动生成交互式 API 文档，无需手动编写任何文档代码，就能直接在线调试接口。

访问 FastAPI 交互式文档：
启动服务后，FastAPI 会自动生成交互式文档，直接在浏览器访问以下地址即可：

访问地址：http://127.0.0.1:8000/docs

核心功能：
1.可视化展示所有接口的路径、请求方法、参数类型和响应格式。
2.在线调试：点击接口右侧的 Try it out 按钮，输入参数后点击 Execute，即可直接发送请求并查看实时响应结果。
3.自动校验：根据代码中的类型提示，自动校验参数，输入非法值会直接提示错误。