FARM 技术栈指南：如何使用 FastAPI、React 和 MongoDB 构建全栈应用

全栈 FastAPI、React、MongoDB（FARM） 应用生成器是一款功能强大的工具，旨在简化生产级 Web 应用的创建。通过将后端的 FastAPI、前端的 React 与可扩展的 NoSQL 数据库 MongoDB 集成在一起，FARM 生成器让 Python 开发者几乎零配置即可快速搭建健壮的应用骨架。对于希望专注于构建功能而非样板代码配置的开发者而言，这是理想之选。

本文将介绍 FARM 应用生成器，解读其关键特性，提供逐步的安装与配置说明，并通过一个真实案例（任务管理应用）演示其能力。我们的目标是展示该生成器如何简化全栈开发，并助力 Python 开发者构建可扩展、可用于生产的应用。

如果您需要回顾 MongoDB，欢迎查看 DataCamp 的《Python 中的 MongoDB 入门》课程。

什么是 FastAPI 应用生成器？

FARM 生成器会自动创建一个完整的 Web 应用栈，包含以下组件：

• 全栈配置：生成一个FastAPI 后端、一个 React 前端，以及一个MongoDB 数据库，三者无缝集成，加速开发。
• 预配置的身份验证：内置 OAuth2 与 JWT、魔法链接登录，以及 Cookie 管理，保障用户访问安全。可以将 OAuth2 与 JWT 理解为登录后获得的安全“VIP 通行证”（JWT 代码），用于访问受限区域。
• Docker Compose 集成：提供预配置的Docker Compose 文件，便于本地开发与测试。
• 运维工具：集成 Celery（异步任务处理）、Traefik（负载均衡），以及 GitHub Actions（CI/CD），为生产环境做好准备。

完整特性参见GitHub 仓库。

对开发者的好处

FARM 生成器具备显著优势：

• 节省时间：免去重复性配置工作（如身份验证、数据库连接），让开发者即刻进入编码环节。
• 最佳实践：提供可扩展、安全、易维护的项目结构，符合业界标准。
• 灵活性：提供可定制的基础架构，便于根据具体项目需求进行扩展。

如何运行 MongoDB FastAPI 应用生成器

为展示该生成器的能力，我们将演示一个示例项目的搭建。以下说明假设您已安装 Python 3.8+、Node.js、Docker 与 Docker Compose。

分步安装与配置

为演示生成器的能力，我们将创建一个名为 task-manager 的示例项目。请确保已安装以下先决条件：

• Python 3.11+：建议 3.12，可使用 python3.12 --version 验证。
• Node.js：用于 React 前端。
• Docker Desktop：用于容器化开发。
• MongoDB：本地安装（例如通过 Homebrew：brew install [email protected]），或使用 MongoDB Atlas（在 .env 文件中使用形如 mongodb+srv://:@cluster0.mongodb.net/?retryWrites=true&w=majority 的连接 URI）。
• Cookiecutter：用于生成项目模板。
• Hatch：用于依赖管理。
• MongoDB Compass（可选）：用于数据库可视化。

继续之前，请使用 /usr/local/bin/python3.12 -m venv task-manager-venv 创建虚拟环境，并用 source task-manager-venv/bin/activate 激活。

1. 安装 cookiecutter 库： pip install cookiecutter
2. 生成项目：使用 FARM 生成器创建项目：

cookiecutter https://github.com/mongodb-labs/full-stack-fastapi-mongodb --no-input project_name="task-manager"
cd task-manager技术支持

3. 本地安装 MongoDB 或使用 MongoDB Atlas：

brew tap mongodb/brew
brew install [email protected]
brew services start [email protected]技术支持

对于 Atlas，注册账号，创建免费集群，并获取连接字符串（例如 mongodb+srv://:@cluster0.mongodb.net/?retryWrites=true&w=majority），用于 .env 文件。

4. 配置环境变量：

复制并编辑 .env 文件：

cp .env.example .env
nano .env技术支持

将其更新为您的 MongoDB URI、数据库名和密钥：

MONGODB_URI=mongodb://localhost:27017
MONGO_DATABASE=task_manager
SECRET_KEY=your-secret-key
FIRST_SUPERUSER=[email protected]
FIRST_SUPERUSER_PASSWORD=changethis技术支持

5. 使用 Docker Compose 构建并运行：

确保 Docker Desktop 已启动，然后执行：

docker compose build --no-cache技术支持

1. docker compose up -d
2. 访问应用：
• 前端：http://localhost:3000
• 后端：http://localhost/api/v1
• Swagger UI：http://localhost/docs（交互式 API 文档）
• ReDoc：http://localhost/redoc
• Flower：http://localhost:5555（Celery 监控）
• Traefik UI：http://localhost:8090（路由看板）
3. 登录：使用 [email protected]（密码：changethis）。
4. 测试身份验证：在 Swagger UI（/docs）中测试 /auth/login 或 /auth/magic-link 端点。
5. 设置 CI/CD：推送至 GitHub，触发已包含的 GitHub Actions 工作流。

探索生成的全栈项目结构

使用 FARM 生成器时，它会搭建一个结构清晰的 task-manager 项目。可以把它想象成一座预制的房子，每个“房间”各司其职：

• backend/：这是 FastAPI 后端运作的“厨房”。其中包含 app/（API 代码）和 conf/（配置）等文件夹，用于处理任务与数据。

• frontend/：这是用户看到您网站的“客厅”，由 Next.js/React 驱动。app/ 文件夹包含页面（如 about、TaskList），其中有 layout.tsx（页面框架）与 page.tsx（页面内容）。public/ 文件夹存放网站图标等资源。

• 其他文件：您会看到 docker-compose.yml（用 Docker 启动全部服务）、.env（敏感配置），以及 .github/workflows/（当您分享代码时进行自动化测试）。

该套件可随项目成长而扩展，生成器还附带多种实用工具，助您更高效地开发！

生成器功能能帮您做什么

FARM 生成器内置了众多实用工具，助您打造各种类型的项目。下面以通俗方式介绍它们的作用及价值：

Docker Compose 集成：为本地开发而优优化

• 作用：Docker Compose 就像一键开关，可用一条命令启动并运行整个项目（后端、前端与数据库）。它使用容器进行隔离，便于在本机进行测试。
• 好处：您可以通过 docker compose up -d 启动 task-manager 应用，用 docker compose down 停止。非常适合在不污染系统环境的情况下尝试想法。使用 docker compose ps 查看运行状态——若显示 “Up”，就绪！

示例：完成项目设置后，运行：

cd task-manager
docker compose up -d技术支持

打开 http://localhost:3000 查看前端，整个应用已在本地运行！

内置身份验证系统

• 作用：提供带用户账户的登录系统，包含默认超级用户（如 [email protected]，密码 changethis）。使用 OAuth2 与 JWT 令牌（安全登录码）以及魔法链接（邮件登录链接）。
• 好处：您可以让用户注册、登录，或通过魔法链接访问应用。在 http://localhost/docs 的 Swagger UI 中试用——找到 /api/v1/login/oauth 进行登录测试。非常适用于仅限特定用户访问的场景，如私密任务清单。

示例：使用默认用户登录：

1. 访问 http://localhost/docs。
2. 找到 /api/v1/login/oauth，输入 [email protected] 和 changethis，点击“Execute”。您将获得用于访问私有页面的 JWT 令牌！

任务管理器 API

OAuth API 演示

OAuth API 返回

FastAPI 后端特性

下面具体看看由 FastAPI 驱动的后端关键特性，以及它如何简化数据库操作、API 设计与可扩展性。

• MongoDB Motor：与 MongoDB 高速通信的引擎，即便在大量并发请求下也能高效运行。
• MongoDB ODMantic：可视作数据操作助手，便于在 MongoDB 中保存与检索数据，就像把任务整理进分类盒子。
• 通用 CRUD 支持：CRUD 即创建、读取、更新、删除。该功能提供现成工具，无需从零开始即可对数据（如任务）进行增删改查。
• 基于标准：遵循 OpenAPI 与 JSON Schema 等规范，使 API 清晰易懂并便于与其他工具或应用对接。
• 好处：您可以快速构建用于存储任务的后端。生成器已完成搭建，您只需在其基础上添加自己的想法（如新任务特性）。

示例：在 backend/app/api/tasks.py 中快速添加任务查看器：

from fastapi import APIRouter, Depends
from odmantic import AIOEngine, Model
from motor.motor_asyncio import AsyncIOMotorClient
router = APIRouter(prefix="/tasks", tags=["tasks"])
class Task(Model):
    title: str
async def get_db():
    client = AsyncIOMotorClient("mongodb://localhost:27017")
    return AIOEngine(client, database="task_manager")
@router.get("/")  # View all tasks
async def get_tasks(db: AIOEngine = Depends(get_db)):
    return await db.find(Task)技术支持

使用 docker compose up --build 重新构建后，在 http://localhost/api/v1/tasks 进行测试。

Next.js/React 前端

React 前端是用户与应用交互的地方。下面看看其结构与内置工具，如何帮助您构建精致且响应迅速的页面。

• 中间件授权：扮演“门卫”，在用户访问特定页面前检查是否已登录（例如，仅登录用户可访问 /TaskList）。
• React Hook Form 表单校验：确保表单（如新增任务表单）在保存前填写正确，避免空任务混入。
• Redux 状态管理：跟踪应用状态（如当前选中的任务），即使数据量大也能保证流畅体验。
• TailwindCSS、HeroIcons、HeadlessUI 的样式与模板：这些是预制的设计工具。TailwindCSS 用于页面样式，HeroIcons 提供精美图标，HeadlessUI 提供易用的按钮与菜单组件。
• 好处：您可以轻松构建美观的任务页面，配备便捷表单与安全访问控制。生成器已完成设计搭建，您可专注于新增任务或扩展功能。

示例：在 frontend/app/TaskList/page.tsx 中添加一个简单任务表单：

import { useState } from 'react';
export default function TaskList() {
  const [task, setTask] = useState({ title: '' });
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    fetch('http://localhost/api/v1/tasks', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(task),
    });
    setTask({ title: '' });
  };
  return (
    <div className="container mx-auto p-4">
      <h1 className="text-2xl font-bold">Add Task</h1>
      <form onSubmit={handleSubmit}>
        <input
          className="border p-2"
          value={task.title}
          onChange={e => setTask({ title: e.target.value })}
          placeholder="Task name"
        />
        <button className="bg-blue-500 text-white p-2" type="submit">Add</button>
      </form>
    </div>
  );
}技术支持

访问 http://localhost:3000/TaskList 添加任务。

扩展您的任务管理器

该生成器为任务管理器提供了扎实起点。例如，您可以：

• 使用 CRUD 工具增加“标记完成”的按钮。
• 利用身份验证保持任务列表私密。
• 用 TailwindCSS 美化界面。
• 配置 Celery 通过邮件发送任务提醒。

可探索的其他创意

借助这些功能，您不仅能构建任务管理器：

• 博客或网站：用 MongoDB 存储文章，FastAPI 提供接口，Next.js 打造酷炫站点。
• 在线商店：用 MongoDB 保存商品数据，Celery 处理订单，Next.js 搭建店铺页面。
• 实时更新：借助 MongoDB、FastAPI 的实时能力与 Next.js 仪表板展示实时信息（如比赛比分）。

结语

FARM 应用生成器通过提供预配置、可用于生产的 FastAPI、React 与 MongoDB 集成栈，极大简化了全栈开发。其自动化的安装与配置、对最佳实践的遵循，以及灵活的架构，使之成为 Python 开发者的得力工具。无论您是在构建任务管理器还是复杂 Web 应用，FARM 生成器都能加速开发并确保可扩展性。按照上述步骤试用，并在 GitHub 仓库查看完整文档，释放其全部潜能！

想要深入学习，欢迎查看以下资源：

• 官方仓库： 浏览源代码、阅读完整文档、了解更新或参与贡献。
• FastAPI 文档： 进一步了解 FastAPI 的特性以及其如何驱动后端。
• FastAPI 入门课程：使用 FastAPI 构建稳健的生产级 API，掌握 HTTP 操作、校验与异步执行，打造高效的数据与机器学习流水线。