panda
db867dcbe5
FastAPI 项目 - 前端（Frontend）
前端基于 Vite、React、TypeScript、TanStack Query、TanStack Router 与 Tailwind CSS 构建。
前端开发
在开始之前，请确保系统中安装了 Node 版本管理工具：Node Version Manager（nvm）或 Fast Node Manager（fnm）。
cd frontend
- 如果系统尚未安装
.nvmrc中指定的 Node.js 版本，可以运行对应命令进行安装：
# 使用 fnm 时
fnm install
# 使用 nvm 时
nvm install
- 安装完成后，切换到该版本的 Node.js：
# 使用 fnm 时
fnm use
# 使用 nvm 时
nvm use
- 在
frontend目录中安装依赖：
npm install
- 使用下面的脚本启动本地开发服务器（支持热更新）：
npm run dev
- 然后在浏览器中打开
http://localhost:5173/。
注意：这个开发服务器是在本机直接运行的，不在 Docker 容器中。这是推荐的前端开发方式：在本地使用 Vite 的热更新体验进行快速迭代；当前端就绪后，再构建前端 Docker 镜像，在接近生产环境的 Docker 中做最终验证。频繁为每次改动重建 Docker 镜像，会远不如直接用本地开发服务器高效。
更多可用的 npm 脚本与命令可以查看 package.json。
移除前端
如果你只需要开发纯 API（仅后端），想要彻底移除前端，可以按照下面步骤操作：
-
删除整个
./frontend目录。 -
在
docker-compose.yml中删除frontend服务（整个 service 区块）。 -
在
docker-compose.override.yml中删除frontend与playwright两个服务的配置。
完成后，你就获得了一个“无前端”（仅 API）的应用。🤓
如果你愿意，还可以从以下位置删除与 FRONTEND 相关的环境变量，仅用于清理配置（保留它们也不会产生实际影响）：
.env./scripts/*.sh
生成前端客户端（API Client）
自动方式
- 激活后端虚拟环境。
- 在项目根目录执行脚本：
./scripts/generate-client.sh
- 将生成的变更提交到仓库。
手动方式
-
启动 Docker Compose stack。
-
从
http://localhost/api/v1/openapi.json下载 OpenAPI JSON 文件，并将其保存为frontend目录根下的openapi.json。 -
生成前端客户端：
npm run generate-client
- 将生成的变更提交到仓库。
请注意，每当后端发生影响 OpenAPI Schema 的变更时，都需要重新执行上述步骤以更新前端客户端。
使用远程 API
如果你希望前端调用远程环境的 API，可以设置环境变量 VITE_API_URL 为远程 API 的基础 URL，例如在 frontend/.env 中配置：
VITE_API_URL=https://api.my-domain.example.com
之后启动前端时，它会将该地址作为 API 请求的基础 URL。
代码结构
前端代码结构大致如下：
frontend/src- 前端主要源代码。frontend/src/assets- 静态资源。frontend/src/client- 通过 OpenAPI 生成的前端客户端代码。frontend/src/components- 各种通用组件与业务组件。frontend/src/hooks- 自定义 Hooks。frontend/src/routes- 路由定义及页面组件。
使用 Playwright 做端到端测试（E2E）
前端中预置了基于 Playwright 的端到端测试。要运行测试，需要先启动 Docker Compose stack。可以使用如下命令启动（至少需要后端）：
docker compose up -d --wait backend
然后运行 Playwright 测试：
npx playwright test
你也可以使用 UI 模式运行测试，以便查看浏览器界面并与之交互：
npx playwright test --ui
测试完成后，如果希望停止并移除 Docker Compose stack，同时清理测试期间创建的数据，可运行：
docker compose down -v
如需更新或新增 E2E 测试用例，只需到 frontend/tests 目录中修改现有测试文件或新增文件。
更多关于编写与运行 Playwright 测试的说明，可参考官方文档：Playwright documentation。