使用 Poetry + VS Code 创建你的第一个 FastAPI 工程

本篇博客同样隶属于勇闯前后端系列的Python博客系列

笔者之前就写过了Flask的配置工程，在那篇博客中笔者就提到了除了Flask之外，另一个好用的后端框架就是FastAPI了，这里也补充一下FastAPI的工程创建。

好在步骤实际上并不复杂：

1. 创建目录 → cd 进去
2. poetry init 初始化项目
3. poetry add fastapi uvicorn[standard] 安装依赖
4. （可选）poetry shell 激活虚拟环境
5. 编写 main.py，创建 FastAPI 实例
6. poetry run uvicorn main:app --reload 启动服务
7. 浏览器访问 / 和 /docs

1. 🧱 准备环境

笔者喜欢的是WSL，这里，关于WSL如何安装笔者不计划重复了，自行搜索引擎。

检查 Python 版本（建议 3.10+）

python3 --version

确认 Poetry 已安装

poetry --version

如果未安装，可以用官方安装脚本，当然，笔者优先建议你好好看一看教程，poetry还是很好用的

Introduction | Documentation | Poetry - Python dependency management and packaging made easy

curl -sSL https://install.python-poetry.org | python3 -

---

2️⃣ 创建项目目录

打开终端，创建一个新的项目文件夹并进入：

mkdir ~/projects/fastapi-demo
cd ~/projects/fastapi-demo

这里我们将所有项目文件都放在 fastapi-demo 目录下。

---

3️⃣ 使用 Poetry 初始化项目

用 Poetry 初始化一个新的 Python 项目：

poetry init --no-interaction

• --no-interaction 表示使用默认选项创建 pyproject.toml，避免手动输入。
• 执行后，你会在目录下看到 pyproject.toml 文件，这是 Poetry 管理项目依赖和配置的核心文件。

---

4️⃣ 添加依赖：FastAPI + Uvicorn

安装 FastAPI 框架和 Uvicorn ASGI 服务器：

poetry add fastapi uvicorn[standard]

• uvicorn[standard] 包含常用的扩展库，例如 websockets。
• 执行完成后，pyproject.toml 中会记录这两个库。

参考资料：FastAPI 官方教程

---

5️⃣ 激活虚拟环境（可选）

为了保证依赖隔离，建议激活项目虚拟环境：

poetry shell

• 进入虚拟环境后，执行 python、pip 等命令都会在该环境中生效。

• 如果不想进入 shell，可以使用 poetry run 运行命令，例如：

  poetry run uvicorn main:app --reload
  

参考资料：Poetry 官方文档

---

6️⃣ 创建 FastAPI 应用

在项目根目录下创建 main.py 文件，内容如下：

from fastapi import FastAPI

app = FastAPI()

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

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

• 根路由 / 返回一个简单 JSON 数据。
• /items/{item_id} 支持路径参数和可选查询参数。
• 这也是 FastAPI 官方教程中的第一个示例。

---

7️⃣ 运行 FastAPI 服务

在终端中执行：

poetry run uvicorn main:app --reload

参数说明：

• main:app：从 main.py 中导入名为 app 的 FastAPI 实例。
• --reload：开发模式，修改代码自动重载。

启动成功后：

• 打开浏览器访问 http://127.0.0.1:8000 → 看到 {"message": "Hello, World!"}
• 打开 http://127.0.0.1:8000/docs → 自动生成的 Swagger UI 文档

---

8️⃣ WSL 下注意事项

• 确保 WSL 可以监听 127.0.0.1:8000 或 0.0.0.0:8000。
• Windows 浏览器访问时，使用 http://localhost:8000。
• Poetry 虚拟环境路径可能在 ~/.cache/pypoetry/virtualenvs/，可用 poetry env info 查看。
• 如果用 VSCode Remote‑WSL 开发，可直接在终端执行命令，调试体验更好。

---

📚 参考资料

1. FastAPI 官方教程
2. Poetry 官方文档
3. 在 WSL 下使用 Python + FastAPI