115 lines
3.0 KiB
Markdown
115 lines
3.0 KiB
Markdown
# Training Full-Stack Project
|
||
|
||
前后端分离的培训项目：
|
||
|
||
- `frontend`：React 18、TypeScript、Vite、React Router、Zustand、Tailwind CSS、SCSS Modules
|
||
- `backend`：Spring Boot 3.4.5、Java 21、Maven、MyBatis-Plus
|
||
- `MySQL`：外部 MySQL 8 数据库，应用不会自动创建或修改表结构
|
||
|
||
## 环境要求
|
||
|
||
- Node.js 20+
|
||
- JDK 21+
|
||
- Maven 3.9+
|
||
- 可访问目标 MySQL 的网络和账号
|
||
|
||
## 配置环境
|
||
|
||
使用 `.env.example` 作为本地配置参考，并将真实值写入未提交的根目录 `.env`：
|
||
|
||
```powershell
|
||
Copy-Item .env.example .env
|
||
```
|
||
|
||
生产环境使用 `.env`，或由部署平台注入同名 Secret。不要将真实密码、令牌或数据库地址写入示例文件、日志或提交内容。
|
||
|
||
## 数据库初始化与迁移
|
||
|
||
SQL 文件只保存在根目录 `sql/`：
|
||
|
||
- `sql/USERS.sql`：新环境的最终建表语句，包含表和字段中文注释。
|
||
- `sql/migrations/V1__rename_users_to_USERS.sql`：保留既有 `users` 数据的人工迁移脚本。
|
||
|
||
迁移前只读检查目标库和影响范围：
|
||
|
||
```sql
|
||
SHOW TABLES LIKE 'users';
|
||
SHOW TABLES LIKE 'USERS';
|
||
```
|
||
|
||
确认备份、目标数据库和回滚方式后，人工执行迁移脚本。MySQL 的 `RENAME TABLE` 会隐式提交，回滚使用：
|
||
|
||
```sql
|
||
RENAME TABLE USERS TO users;
|
||
```
|
||
|
||
应用启动不会自动执行 SQL；迁移和建表必须由数据库管理员按环境流程执行。
|
||
|
||
## 启动后端
|
||
|
||
```powershell
|
||
mvn -f backend/pom.xml spring-boot:run
|
||
```
|
||
|
||
后端默认运行在 `http://127.0.0.1:8080`，健康检查地址为 `GET /api/v1/health`。每次请求支持并返回 `X-Request-Id`。
|
||
|
||
## 启动前端
|
||
|
||
```powershell
|
||
Set-Location frontend
|
||
npm ci
|
||
npm run dev -- --host 127.0.0.1
|
||
```
|
||
|
||
前端默认运行在 `http://127.0.0.1:5173`，开发服务器将 `/api` 请求代理到后端。API 基础路径为 `/api/v1`。
|
||
|
||
## API 示例
|
||
|
||
用户列表使用 1-based 分页：
|
||
|
||
```text
|
||
GET /api/v1/users?page=1&pageSize=50&keyword=&role=&status=
|
||
GET /api/v1/users/summary
|
||
```
|
||
|
||
成功响应统一为：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
## 构建与测试
|
||
|
||
```powershell
|
||
Set-Location frontend
|
||
npm ci
|
||
npm run test
|
||
npm run build
|
||
|
||
Set-Location ..
|
||
mvn -f backend/pom.xml test
|
||
mvn -f backend/pom.xml verify
|
||
```
|
||
|
||
## 全栈只读验证
|
||
|
||
从项目根目录执行：
|
||
|
||
```powershell
|
||
python .codex/skills/fullstack-start-verify/scripts/start_and_verify.py `
|
||
--backend-cmd "mvn -f backend/pom.xml spring-boot:run" `
|
||
--backend-dir . `
|
||
--backend-url http://127.0.0.1:8080/api/v1/health `
|
||
--frontend-cmd "npm run dev -- --host 127.0.0.1" `
|
||
--frontend-dir frontend `
|
||
--frontend-url http://127.0.0.1:5173/ `
|
||
--check-url summary=http://127.0.0.1:8080/api/v1/users/summary `
|
||
--check-url "users=http://127.0.0.1:8080/api/v1/users?page=1& pageSize=50"
|
||
```
|
||
|
||
验证期间只执行健康检查和 GET 查询，不执行新增、修改、删除或数据库迁移。脚本默认清理本次启动的进程；排查启动失败时增加 `--keep-logs` 保留日志，并确认日志中没有敏感信息。
|