panda
db867dcbe5
Deploy to Staging / deploy (push) Has been cancelled
Conflict detector / main (push) Has been cancelled
Lint Backend / lint-backend (push) Has been cancelled
Playwright Tests / changes (push) Has been cancelled
Test Backend / test-backend (push) Has been cancelled
Test Docker Compose / test-docker-compose (push) Has been cancelled
Playwright Tests / test-playwright (1, 4) (push) Has been cancelled
Playwright Tests / test-playwright (2, 4) (push) Has been cancelled
Playwright Tests / test-playwright (3, 4) (push) Has been cancelled
Playwright Tests / test-playwright (4, 4) (push) Has been cancelled
Playwright Tests / merge-playwright-reports (push) Has been cancelled
Playwright Tests / alls-green-playwright (push) Has been cancelled
Issue Manager / issue-manager (push) Has been cancelled
153 lines
4.5 KiB
Markdown
153 lines
4.5 KiB
Markdown
# FastAPI 项目 - 前端（Frontend）
|
||
|
||
前端基于 [Vite](https://vitejs.dev/)、[React](https://reactjs.org/)、[TypeScript](https://www.typescriptlang.org/)、[TanStack Query](https://tanstack.com/query)、[TanStack Router](https://tanstack.com/router) 与 [Tailwind CSS](https://tailwindcss.com/) 构建。
|
||
|
||
## 前端开发
|
||
|
||
在开始之前，请确保系统中安装了 Node 版本管理工具：Node Version Manager（nvm）或 Fast Node Manager（fnm）。
|
||
|
||
* 安装 fnm 可参考 [官方文档](https://github.com/Schniz/fnm#installation)；如果你更喜欢 nvm，可参考 [nvm 官方文档](https://github.com/nvm-sh/nvm#installing-and-updating)。
|
||
|
||
* 安装好 nvm 或 fnm 后，进入 `frontend` 目录：
|
||
|
||
```bash
|
||
cd frontend
|
||
```
|
||
|
||
* 如果系统尚未安装 `.nvmrc` 中指定的 Node.js 版本，可以运行对应命令进行安装：
|
||
|
||
```bash
|
||
# 使用 fnm 时
|
||
fnm install
|
||
|
||
# 使用 nvm 时
|
||
nvm install
|
||
```
|
||
|
||
* 安装完成后，切换到该版本的 Node.js：
|
||
|
||
```bash
|
||
# 使用 fnm 时
|
||
fnm use
|
||
|
||
# 使用 nvm 时
|
||
nvm use
|
||
```
|
||
|
||
* 在 `frontend` 目录中安装依赖：
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
* 使用下面的脚本启动本地开发服务器（支持热更新）：
|
||
|
||
```bash
|
||
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）
|
||
|
||
### 自动方式
|
||
|
||
* 激活后端虚拟环境。
|
||
* 在项目根目录执行脚本：
|
||
|
||
```bash
|
||
./scripts/generate-client.sh
|
||
```
|
||
|
||
* 将生成的变更提交到仓库。
|
||
|
||
### 手动方式
|
||
|
||
* 启动 Docker Compose stack。
|
||
|
||
* 从 `http://localhost/api/v1/openapi.json` 下载 OpenAPI JSON 文件，并将其保存为 `frontend` 目录根下的 `openapi.json`。
|
||
|
||
* 生成前端客户端：
|
||
|
||
```bash
|
||
npm run generate-client
|
||
```
|
||
|
||
* 将生成的变更提交到仓库。
|
||
|
||
请注意，每当后端发生影响 OpenAPI Schema 的变更时，都需要重新执行上述步骤以更新前端客户端。
|
||
|
||
## 使用远程 API
|
||
|
||
如果你希望前端调用远程环境的 API，可以设置环境变量 `VITE_API_URL` 为远程 API 的基础 URL，例如在 `frontend/.env` 中配置：
|
||
|
||
```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。可以使用如下命令启动（至少需要后端）：
|
||
|
||
```bash
|
||
docker compose up -d --wait backend
|
||
```
|
||
|
||
然后运行 Playwright 测试：
|
||
|
||
```bash
|
||
npx playwright test
|
||
```
|
||
|
||
你也可以使用 UI 模式运行测试，以便查看浏览器界面并与之交互：
|
||
|
||
```bash
|
||
npx playwright test --ui
|
||
```
|
||
|
||
测试完成后，如果希望停止并移除 Docker Compose stack，同时清理测试期间创建的数据，可运行：
|
||
|
||
```bash
|
||
docker compose down -v
|
||
```
|
||
|
||
如需更新或新增 E2E 测试用例，只需到 `frontend/tests` 目录中修改现有测试文件或新增文件。
|
||
|
||
更多关于编写与运行 Playwright 测试的说明，可参考官方文档：[Playwright documentation](https://playwright.dev/docs/intro)。
|