Next.js FastAPI 模板使用教程

1. 项目介绍

Next.js FastAPI 模板是一个集成了 Next.js 和 FastAPI 的全栈开发模板。它结合了 Python 的后端能力和 TypeScript 的前端技术，并通过 Zod 提供了强大的类型验证。该模板为开发者提供了一个性能优良、类型安全且开发体验卓越的生产就绪架构。

2. 项目快速启动

以下是快速启动 Next.js FastAPI 模板的步骤：

安装必要工具

1. uv：用于管理后端 Python 依赖。

   • 安装 uv：按照官方安装指南进行安装。

2. Node.js, npm 和 pnpm：用于运行前端。

   • 安装 Node.js：按照Node.js 安装指南进行安装。
   • 安装 pnpm：运行 npm install -g pnpm。

3. Docker：用于容器化环境。

   • 安装 Docker：根据操作系统按照对应的安装指南进行安装。

4. Docker Compose：用于容器编排。

   • 安装 Docker Compose：参考安装指南。

设置环境变量

• 后端 (fastapi_backend/.env)：

  • 将 .env.example 文件复制为 .env，并用实际值更新变量。
  • 使用以下命令生成新的密钥：python3 -c "import secrets; print(secrets.token_hex(32))"。

• 前端 (nextjs-frontend/.env.local)：

  • 将 .env.example 文件复制为 .env，这些值通常不需要更改。

运行数据库

使用 Docker 运行数据库，避免本地安装问题：

• 构建并启动数据库容器：docker compose build db 和 docker compose up -d db。
• 应用数据库迁移：make docker-migrate-db。

构建项目

• 不使用 Docker：

  • 后端：进入 fastapi_backend 目录，运行 uv sync。
  • 前端：进入 nextjs-frontend 目录，运行 pnpm install。

• 使用 Docker：

  • 构建后端和前端容器：make docker-build。

运行应用

• 不使用 Docker：

  • 启动 FastAPI 服务器：make start-backend。
  • 启动 Next.js 开发服务器：make start-frontend。

• 使用 Docker：

  • 启动 FastAPI 服务器容器：make docker-start-backend。
  • 启动 Next.js 开发服务器容器：make docker-start-frontend。

• 访问：

  • 后端 API：http://localhost:8000。
  • 前端应用：http://localhost:3000。

3. 应用案例和最佳实践

（此处可以添加具体的案例和最佳实践，例如如何利用模板构建一个简单的博客系统，或者如何实现用户认证等。）

4. 典型生态项目

（此处可以列出一些使用了 Next.js FastAPI 模板的典型项目，以及它们的特点和优势。）