Hướng dẫn FARM Stack: Cách xây dựng ứng dụng Full-Stack với FastAPI, React & MongoDB

Trình tạo ứng dụng FastAPI, React, MongoDB (FARM) full-stack là một công cụ mạnh mẽ được thiết kế để tinh gọn quy trình tạo ứng dụng web đạt chuẩn sản xuất. Bằng cách tích hợp FastAPI cho back end, React cho front end và MongoDB làm cơ sở dữ liệu NoSQL có khả năng mở rộng, trình tạo FARM cho phép các lập trình viên Python nhanh chóng dựng khung ứng dụng vững chắc với thiết lập tối thiểu. Công cụ này lý tưởng cho những ai muốn tập trung xây tính năng thay vì cấu hình mã khung.

Bài viết này giới thiệu trình tạo ứng dụng FARM, giải thích các tính năng chính, cung cấp hướng dẫn thiết lập từng bước và minh họa khả năng của nó với một ví dụ thực tế: ứng dụng quản lý công việc. Mục tiêu của chúng tôi là cho thấy cách trình tạo đơn giản hóa phát triển full-stack và trao quyền cho lập trình viên Python tạo ra ứng dụng có khả năng mở rộng, sẵn sàng cho sản xuất.

Nếu bạn cần ôn lại MongoDB, hãy xem khóa học Giới thiệu MongoDB trong Python của DataCamp. 

Trình tạo ứng dụng FastAPI là gì?

Trình tạo FARM tự động hóa việc tạo một ngăn xếp ứng dụng web hoàn chỉnh với các thành phần sau:

• Thiết lập full-stack: Tạo back end FastAPI, front end React và cơ sở dữ liệu MongoDB, được tích hợp liền mạch để phát triển nhanh.
• Xác thực cấu hình sẵn: Bao gồm OAuth2 với JWT, xác thực magic link và quản lý cookie để truy cập người dùng an toàn. OAuth2 với JWT giống như một “thẻ VIP” bảo mật (mã JWT) bạn nhận sau khi đăng nhập để truy cập khu vực riêng tư.
• Tích hợp Docker Compose: Cung cấp các tệp Docker Compose cấu hình sẵn để phát triển và kiểm thử cục bộ dễ dàng.
• Công cụ vận hành: Tích hợp Celery để xử lý tác vụ bất đồng bộ, Traefik để cân bằng tải và GitHub Actions cho CI/CD, đảm bảo môi trường sẵn sàng sản xuất.

Danh sách tính năng đầy đủ có trong repo GitHub.

Lợi ích cho nhà phát triển

Trình tạo FARM mang lại nhiều lợi thế đáng kể:

• Tiết kiệm thời gian: Loại bỏ các tác vụ thiết lập lặp lại, như cấu hình xác thực hoặc kết nối cơ sở dữ liệu, cho phép bạn bắt đầu viết mã ngay.
• Thực hành tốt nhất: Đảm bảo cấu trúc dự án có khả năng mở rộng, an toàn và dễ bảo trì, tuân theo tiêu chuẩn ngành.
• Linh hoạt: Cung cấp nền tảng có thể tùy biến để mở rộng theo nhu cầu dự án cụ thể.

Cách chạy Trình tạo ứng dụng MongoDB FastAPI

Để minh họa khả năng của trình tạo, chúng ta sẽ đi qua việc thiết lập một dự án mẫu. Các hướng dẫn sau giả định bạn đã cài đặt Python 3.8+, Node.js, Docker và Docker Compose.

Hướng dẫn thiết lập từng bước

Để trình diễn khả năng của trình tạo, chúng ta sẽ tạo một dự án mẫu tên là task-manager. Hãy đảm bảo bạn đã cài đặt các thành phần tiên quyết sau:

• Python 3.11+: Ưu tiên 3.12, kiểm tra bằng python3.12 --version.
• Node.js: Cho front end React.
• Docker Desktop: Cho phát triển đóng gói container.
• MongoDB: Cài đặt cục bộ (ví dụ qua Homebrew với brew install [email protected]) hoặc MongoDB Atlas (dùng chuỗi kết nối như mongodb+srv://:@cluster0.mongodb.net/?retryWrites=true&w=majority).
• Cookiecutter: Để tạo mẫu dự án.
• Hatch: Để quản lý phụ thuộc.
• MongoDB Compass (tùy chọn): Để trực quan hóa cơ sở dữ liệu.

Trước khi tiếp tục, hãy tạo môi trường ảo với /usr/local/bin/python3.12 -m venv task-manager-venv và kích hoạt bằng source task-manager-venv/bin/activate.

1. Cài đặt thư viện cookiecutter: pip install cookiecutter
2. Tạo dự án: Sử dụng trình tạo FARM để tạo dự án:

cookiecutter https://github.com/mongodb-labs/full-stack-fastapi-mongodb --no-input project_name="task-manager"
cd task-managerĐược hỗ trợ bởi

3. Cài đặt MongoDB cục bộ hoặc dùng MongoDB Atlas:

brew tap mongodb/brew
brew install [email protected]
brew services start [email protected]Được hỗ trợ bởi

Với Atlas, hãy đăng ký, tạo một cluster miễn phí và lấy chuỗi kết nối (ví dụ: mongodb+srv://:@cluster0.mongodb.net/?retryWrites=true&w=majority) để dùng trong tệp .env của bạn.

4. Cấu hình biến môi trường: 

Sao chép và chỉnh sửa tệp .env:

cp .env.example .env
nano .envĐược hỗ trợ bởi

Cập nhật với MongoDB URI, tên cơ sở dữ liệu và các khóa bí mật của bạn:

MONGODB_URI=mongodb://localhost:27017
MONGO_DATABASE=task_manager
SECRET_KEY=your-secret-key
FIRST_SUPERUSER=[email protected]
FIRST_SUPERUSER_PASSWORD=changethisĐược hỗ trợ bởi

5. Build và chạy với Docker Compose:

Đảm bảo Docker Desktop đang chạy, sau đó:

docker compose build --no-cacheĐược hỗ trợ bởi

1. docker compose up -d
2. Truy cập ứng dụng:
• Front end: http://localhost:3000
• Back end: http://localhost/api/v1
• Swagger UI: http://localhost/docs (tài liệu API tương tác)
• ReDoc: http://localhost/redoc
• Flower: http://localhost:5555 (giám sát Celery)
• Traefik UI: http://localhost:8090 (bảng điều khiển định tuyến)
3. Đăng nhập với [email protected] (mật khẩu: changethis).
4. Kiểm thử xác thực: Dùng Swagger UI (/docs) để thử các endpoint /auth/login hoặc /auth/magic-link.
5. Thiết lập CI/CD: Đẩy mã lên GitHub để kích hoạt các workflow GitHub Actions đi kèm.

Khám phá cấu trúc dự án Full-Stack được tạo

Khi bạn dùng trình tạo FARM, nó dựng dự án task-manager với mọi thứ được sắp xếp gọn gàng. Hãy hình dung như một ngôi nhà làm sẵn, mỗi phòng có một nhiệm vụ:

• backend/: Đây là “nhà bếp” nơi back end FastAPI hoạt động. Có các thư mục như app/ (cho mã API) và conf/ (cho thiết lập) để xử lý tác vụ và dữ liệu.

• frontend/: Đây là “phòng khách” nơi người dùng xem trang web của bạn, vận hành bởi Next.js/React. Thư mục app/ chứa các trang (ví dụ: about, TaskList) với các tệp như layout.tsx (khung trang) và page.tsx (nội dung). Thư mục public/ lưu những thứ như biểu tượng trang web.

• Tệp khác: Bạn sẽ thấy docker-compose.yml (để chạy mọi thứ với Docker), .env (thiết lập bí mật) và .github/workflows/ (cho kiểm thử tự động khi bạn chia sẻ mã).

Thiết lập này sẵn sàng để mở rộng và trình tạo bổ sung nhiều công cụ hay giúp việc phát triển dễ dàng hơn!

Bạn có thể làm gì với các tính năng của trình tạo

Trình tạo FARM đi kèm các công cụ tích hợp tuyệt vời giúp bạn tạo nhiều loại dự án. Dưới đây là cái nhìn đơn giản về chúng và cách chúng hỗ trợ bạn:

Tích hợp Docker Compose: Tối ưu cho phát triển cục bộ

• Làm gì: Docker Compose như một nút “thần kỳ” thiết lập và chạy toàn bộ dự án của bạn (back end, front end, cơ sở dữ liệu) chỉ với một lệnh. Nó dùng container để tách bạch mọi thứ và dễ thử nghiệm trên máy của bạn.
• Hỗ trợ thế nào: Bạn có thể khởi động ứng dụng task-manager bằng cách gõ docker compose up -d và dừng với docker compose down. Rất phù hợp để thử ý tưởng mà không làm rối máy tính. Kiểm tra trạng thái bằng docker compose ps—nếu mọi thứ “Up”, bạn sẵn sàng rồi!

Ví dụ: Sau khi thiết lập dự án, chỉ cần chạy:

cd task-manager
docker compose up -dĐược hỗ trợ bởi

Mở http://localhost:3000 để xem front end của bạn, và bạn đã chạy mọi thứ cục bộ!

Hệ thống xác thực tích hợp

• Làm gì: Thêm hệ thống đăng nhập với tài khoản người dùng, bao gồm superuser mặc định (như [email protected] với mật khẩu changethis). Sử dụng OAuth2 với token JWT (mã đăng nhập an toàn) và magic link (liên kết email để đăng nhập).
• Hỗ trợ thế nào: Bạn có thể cho phép người dùng đăng ký, đăng nhập hoặc dùng magic link để vào ứng dụng. Thử tại http://localhost/docs trong Swagger UI—tìm /api/v1/login/oauth để thử đăng nhập. Rất phù hợp cho ứng dụng chỉ một số người được xem, như danh sách việc riêng tư.

Ví dụ: Đăng nhập với người dùng mặc định:

1. Vào http://localhost/docs.
2. Tìm /api/v1/login/oauth, nhập [email protected] và mật khẩu, rồi bấm “Execute.” Bạn sẽ nhận được token JWT để dùng cho các trang riêng tư!

API quản lý công việc

Demo cho Oauth API

Kết quả trả về cho Oauth API

Các tính năng back end FastAPI

Hãy xem kỹ hơn các tính năng chính của back end dùng FastAPI và cách nó đơn giản hóa thao tác cơ sở dữ liệu, thiết kế API và khả năng mở rộng.

• MongoDB Motor: Động cơ giao tiếp với cơ sở dữ liệu MongoDB cực nhanh, ngay cả khi xử lý nhiều yêu cầu cùng lúc.
• MongoDB ODMantic: Hãy coi như một trợ lý giúp lưu và tìm dữ liệu trong MongoDB dễ hơn, giống như sắp xếp công việc vào các hộp gọn gàng.
• Hỗ trợ CRUD phổ biến: CRUD là viết tắt của create, read, update, delete. Tính năng này cung cấp sẵn công cụ để thêm, xem, sửa hoặc xóa dữ liệu (như công việc) mà không phải bắt đầu từ đầu.
• Theo chuẩn: Tuân theo các tiêu chuẩn như OpenAPI và JSON Schema, giúp API của bạn rõ ràng và tương thích với công cụ hay ứng dụng khác.
• Hỗ trợ thế nào: Bạn có thể nhanh chóng dựng back end để lưu trữ công việc. Trình tạo đã thiết lập sẵn, bạn chỉ cần thêm ý tưởng của mình, như các tính năng mới cho công việc, dựa trên mã có sẵn.

Ví dụ: Thêm bộ xem công việc nhanh trong 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)Được hỗ trợ bởi

Kiểm thử tại http://localhost/api/v1/tasks sau khi rebuild với docker compose up --build.

Front end Next.js/React

Front end React là nơi người dùng tương tác với ứng dụng của bạn. Hãy khám phá cấu trúc và các công cụ đi kèm để giúp bạn xây dựng trang mượt mà, phản hồi tốt.

• Ủy quyền bằng middleware: Hoạt động như người gác cổng, kiểm tra người dùng đã đăng nhập trước khi xem một số trang (ví dụ: chỉ người đã đăng nhập mới thấy /TaskList).
• Xác thực biểu mẫu với React Hook Form: Đảm bảo các biểu mẫu (như biểu mẫu thêm công việc) có thông tin hợp lệ trước khi lưu, tránh để trống lọt vào.
• Quản lý trạng thái với Redux: Theo dõi các trạng thái, như công việc nào đang được chọn, giúp ứng dụng mượt và nhanh ngay cả với nhiều dữ liệu.
• CSS và template với TailwindCSS, HeroIcons và HeadlessUI: Như các bộ công cụ thiết kế làm sẵn. TailwindCSS tạo kiểu cho trang, HeroIcons thêm biểu tượng đẹp, còn HeadlessUI cung cấp nút bấm và menu hoạt động tốt.
• Hỗ trợ thế nào: Bạn có thể xây trang công việc đẹp mắt với biểu mẫu tiện lợi và truy cập an toàn. Trình tạo đã thiết lập sẵn giao diện, bạn tập trung vào thêm công việc hoặc tính năng khác.

Ví dụ: Thêm biểu mẫu công việc đơn giản trong 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>
  );
}Được hỗ trợ bởi

Truy cập http://localhost:3000/TaskList để thêm công việc.

Mở rộng trình quản lý công việc của bạn

Trình tạo cung cấp cho bạn điểm khởi đầu vững chắc cho một trình quản lý công việc. Ví dụ, bạn có thể:

• Thêm nút đánh dấu hoàn thành bằng cách dùng công cụ CRUD.
• Dùng xác thực để giữ danh sách công việc ở chế độ riêng tư.
• Tạo kiểu với TailwindCSS để trông thật bắt mắt.
• Thiết lập Celery để gửi nhắc việc qua email.

Những ý tưởng khác để khám phá

Với các tính năng này, bạn có thể xây nhiều hơn một trình quản lý công việc:

• Blog hoặc website: Lưu bài viết trong MongoDB, dùng FastAPI để hiển thị và thiết kế trang đẹp với Next.js.
• Cửa hàng trực tuyến: Lưu sản phẩm trong MongoDB, xử lý đơn hàng bằng Celery và tạo trang mua sắm với Next.js.
• Cập nhật trực tiếp: Hiển thị thông tin theo thời gian thực (như tỷ số trận đấu) bằng MongoDB, tính năng live của FastAPI và bảng điều khiển Next.js.

Kết luận

Trình tạo ứng dụng FARM tinh gọn phát triển full-stack bằng cách cung cấp một ngăn xếp cấu hình sẵn, sẵn sàng sản xuất, tích hợp FastAPI, React và MongoDB. Việc tự động hóa các tác vụ thiết lập, tuân thủ thực hành tốt nhất và kiến trúc linh hoạt khiến nó trở thành công cụ vô giá cho lập trình viên Python. Dù bạn đang xây trình quản lý công việc hay ứng dụng web phức tạp, trình tạo FARM tăng tốc phát triển và đảm bảo khả năng mở rộng. Hãy thử ngay hôm nay bằng cách làm theo hướng dẫn thiết lập và khám phá toàn bộ tài liệu trên kho GitHub để khai mở tiềm năng của nó!

Nếu bạn muốn tìm hiểu thêm, hãy xem các tài nguyên hữu ích sau:

• Kho chính thức: Khám phá mã nguồn, đọc tài liệu đầy đủ, xem cập nhật hoặc đóng góp.
• Tài liệu FastAPI: Tìm hiểu thêm về các tính năng của FastAPI và cách nó vận hành back end.
• Khóa học Giới thiệu FastAPI: Xây dựng API vững chắc, đạt chuẩn sản xuất với FastAPI, thành thạo thao tác HTTP, xác thực và thực thi bất đồng bộ để tạo pipeline dữ liệu và ML hiệu quả.