En
745f4e4b06
- 添加 api-generator.bat/api-generator.sh 脚本，简化后端接口修改后的前端 API 同步流程 - 新增 reading-platform-frontend/README.md，说明 API 开发协作规范 - 更新 docs/开发协作指南.md，补充协作模式说明和新功能开发检查清单 - 同步最新 API 规范和生成的 TypeScript 类型代码 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
475 lines
14 KiB
Markdown
475 lines
14 KiB
Markdown
# 少儿智慧阅读平台 · 开发协作指南
|
||
|
||
> 本文档面向：**后端工程师、前端工程师、测试工程师、原型开发工程师**
|
||
> 目标：让每个人清楚自己该做什么、怎么做，无需反复沟通。
|
||
|
||
---
|
||
|
||
## 一、项目概览
|
||
|
||
### 线上访问地址
|
||
|
||
| 用途 | 地址 |
|
||
|---|---|
|
||
| **前端页面** | http://8.148.151.56:8081 |
|
||
| **接口文档** | http://8.148.151.56:3002/doc.html |
|
||
| **代码仓库** | http://8.148.151.56:3000/tonytech/kindergarten_java |
|
||
|
||
### 共享数据库（开发服务器）
|
||
|
||
> 本地开发和服务器**共用同一个数据库**，数据实时同步。
|
||
|
||
| 项目 | 值 |
|
||
|---|---|
|
||
| **Host** | `8.148.151.56` |
|
||
| **Port** | `3306` |
|
||
| **数据库名** | `reading_platform` |
|
||
| **用户名** | `root` |
|
||
| **密码** | `reading_platform_pwd` |
|
||
| **JDBC URL** | `jdbc:mysql://8.148.151.56:3306/reading_platform?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true` |
|
||
|
||
用 DBeaver / Navicat / TablePlus 等 GUI 工具填入以上信息即可直连查看数据。
|
||
|
||
### 测试账号
|
||
|
||
| 角色 | 账号 | 密码 |
|
||
|---|---|---|
|
||
| 超级管理员 | admin | admin123 |
|
||
| 学校管理员 | school | 123456 |
|
||
| 教师 | teacher1 | 123456 |
|
||
| 家长 | parent1 | 123456 |
|
||
|
||
### 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|---|---|
|
||
| 前端 | Vue 3 + TypeScript + Ant Design Vue + Vite |
|
||
| 后端 | Java 17 + Spring Boot 3 + MyBatis-Plus |
|
||
| 数据库 | MySQL 8.0 |
|
||
| 部署 | Docker + Nginx |
|
||
|
||
---
|
||
|
||
## 二、环境准备（所有人）
|
||
|
||
### 1. 安装 Git
|
||
|
||
- Windows：https://git-scm.com/download/win
|
||
- Mac：`brew install git`
|
||
- 安装后验证：`git --version`
|
||
|
||
### 2. 克隆项目
|
||
|
||
```bash
|
||
git clone http://tonytech:cnh05791@8.148.151.56:3000/tonytech/kindergarten_java.git
|
||
cd kindergarten_java
|
||
```
|
||
|
||
### 3. 项目结构
|
||
|
||
```
|
||
kindergarten_java/
|
||
├── reading-platform-java/ # 后端（Java Spring Boot）
|
||
│ ├── src/main/java/ # Java 源码
|
||
│ ├── src/main/resources/ # 配置文件、数据库迁移脚本
|
||
│ └── Dockerfile
|
||
│
|
||
├── reading-platform-frontend/ # 前端（Vue 3）
|
||
│ ├── src/
|
||
│ │ ├── views/ # 页面组件（admin/school/teacher/parent）
|
||
│ │ ├── api/
|
||
│ │ │ ├── generated/ # ⚠️ 自动生成，不要手动修改
|
||
│ │ │ └── index.ts # axios 实例配置
|
||
│ │ └── stores/ # Pinia 状态管理
|
||
│ ├── api-spec.yml # OpenAPI 接口规范（后端更新后提交）
|
||
│ └── orval.config.ts # API 代码生成配置
|
||
│
|
||
└── docs/ # 项目文档
|
||
```
|
||
|
||
---
|
||
|
||
## 三、核心协作机制
|
||
|
||
本项目采用 **OpenAPI 规范驱动开发**，前后端通过规范文件对齐接口，不需要口头沟通接口格式。
|
||
|
||
```
|
||
后端工程师 前端工程师
|
||
│ │
|
||
│ 写 Java Controller │
|
||
│ + Swagger 注解 │
|
||
│ │
|
||
│ 运行 npm run api:update ───────→│ git pull
|
||
│ 提交 api-spec.yml │ src/api/generated/ 自动更新
|
||
│ 提交 generated/ ───────→│ TypeScript 类型保证接口正确
|
||
│ │
|
||
└── 推送到 git → 自动部署上线 ──────┘
|
||
```
|
||
|
||
**前后端唯一的同步方式**：后端改了接口 → 更新 `api-spec.yml` → 前端 `git pull` → TypeScript 报错的地方 = 需要适配的地方。
|
||
|
||
### 协作模式说明
|
||
|
||
#### 为什么选择 OpenAPI 规范驱动开发？
|
||
|
||
| 协作方式 | 优点 | 缺点 | 适用场景 |
|
||
|---------|------|------|---------|
|
||
| **OpenAPI 规范驱动**（当前） | 类型安全、零沟通成本、可并行开发 | 需要遵守规范 | **推荐：常规功能开发** |
|
||
| 一人全流程开发 | 速度快（单人） | 资源浪费、难以深度优化 | 仅适用于原型验证 |
|
||
| 按模块一人包干 | 责任清晰 | 接口对齐成本高、错误发现晚 | 不推荐 |
|
||
|
||
**关键优势**：
|
||
1. **类型安全** - TypeScript 自动校验接口参数和返回值
|
||
2. **零沟通成本** - 接口定义就是 contract，不需要问"这个字段要不要"
|
||
3. **并行开发** - 后端写接口时，前端可以基于规范提前写页面框架
|
||
4. **自动同步** - `npm run api:update` 一键同步，不会有人用旧接口
|
||
|
||
---
|
||
|
||
## 四、后端工程师
|
||
|
||
### 新功能开发检查清单
|
||
|
||
| 步骤 | 后端工程师 | 前端工程师 | 说明 |
|
||
|-----|-----------|-----------|------|
|
||
| 1. 需求确认 | 评估接口可行性 | 评估页面结构 | 确保需求可实现 |
|
||
| 2. 接口设计 | 写 Swagger 注解 | 确认接口需求 | api-spec.yml 作为 contract |
|
||
| 3. 代码开发 | 实现 Controller | 开发 Vue 页面 | 可并行开发 |
|
||
| 4. 本地联调 | `docker compose up` | `npm run dev` | 对齐测试账号登录 |
|
||
| 5. 提交代码 | 提交后端代码 | Git Pull 后提交 | 一次性提交所有改动 |
|
||
|
||
### 开发环境要求
|
||
|
||
- Docker Desktop（必须，用于本地启动服务）
|
||
- IDE：IntelliJ IDEA（推荐，用于编写 Java 代码）
|
||
- Java 17+ / Maven 3.8+（可选，仅在需要 IDE 内直接运行时安装）
|
||
|
||
### 本地启动（推荐：Docker Compose）
|
||
|
||
```bash
|
||
# 在项目根目录执行
|
||
git pull origin main
|
||
docker compose up --build
|
||
```
|
||
|
||
启动完成后（约 2-3 分钟，看到 `Started ReadingPlatformApplication` 日志）访问：
|
||
- 本地前端：http://localhost:3000
|
||
- 本地接口文档：http://localhost:8080/doc.html
|
||
|
||
> **数据库说明**：本地后端直接连接开发服务器的共享数据库（`8.148.151.56:3306`），
|
||
> 本地和服务器数据完全同步，在本地创建的数据在服务器也能看到，反之亦然。
|
||
|
||
> **注意**：本地 Flyway 自动迁移已关闭（`SPRING_FLYWAY_ENABLED=false`）。
|
||
> 需要新增数据库字段时，先在本地写好 SQL 脚本，提交代码后由**服务器**自动执行迁移。
|
||
|
||
### 仅启动后端（不重新构建前端）
|
||
|
||
```bash
|
||
docker compose up --build backend
|
||
```
|
||
|
||
### 新增或修改接口
|
||
|
||
**第一步**：在对应 Controller 里添加方法，写好 Swagger 注解
|
||
|
||
```java
|
||
// 示例：新增一个接口
|
||
@Operation(summary = "获取学生列表", description = "支持分页和姓名搜索")
|
||
@GetMapping("/students")
|
||
public Result<PageResult<Student>> getStudents(
|
||
@Parameter(description = "页码，从1开始") @RequestParam(defaultValue = "1") int page,
|
||
@Parameter(description = "每页数量") @RequestParam(defaultValue = "10") int size,
|
||
@Parameter(description = "姓名关键词") @RequestParam(required = false) String name
|
||
) {
|
||
return Result.success(studentService.getPage(page, size, name));
|
||
}
|
||
```
|
||
|
||
**第二步**：接口写好后，更新前端的规范文件
|
||
|
||
```bash
|
||
# 在 reading-platform-frontend 目录下执行
|
||
cd ../reading-platform-frontend
|
||
npm install # 首次需要安装依赖
|
||
npm run api:update # 拉取最新规范 + 重新生成 TypeScript 代码
|
||
```
|
||
|
||
**第三步**：提交所有变更
|
||
|
||
```bash
|
||
cd .. # 回到项目根目录
|
||
git add reading-platform-java/
|
||
git add reading-platform-frontend/api-spec.yml
|
||
git add reading-platform-frontend/src/api/generated/
|
||
git commit -m "feat(backend): 新增学生列表接口"
|
||
git push origin main
|
||
```
|
||
|
||
> 推送后服务器会**自动部署**，约 2-3 分钟生效。
|
||
|
||
### 数据库变更
|
||
|
||
所有数据库改动必须通过 Flyway 迁移脚本，**不要直接在数据库里改表结构**。
|
||
|
||
```bash
|
||
# 新建迁移脚本（文件名按序号递增）
|
||
touch reading-platform-java/src/main/resources/db/migration/V7__your_description.sql
|
||
```
|
||
|
||
```sql
|
||
-- V7__add_student_grade.sql 示例
|
||
ALTER TABLE students ADD COLUMN grade VARCHAR(20) COMMENT '年级';
|
||
```
|
||
|
||
脚本提交后，后端启动时 Flyway 会自动执行。
|
||
|
||
---
|
||
|
||
## 五、前端工程师
|
||
|
||
### 开发环境要求
|
||
|
||
- Node.js 18+（`node -v` 验证）
|
||
- npm 9+（`npm -v` 验证）
|
||
- IDE：VS Code（推荐安装 Volar 插件）
|
||
|
||
### 本地启动
|
||
|
||
```bash
|
||
cd reading-platform-frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
访问：http://localhost:5173（本地开发，自动代理到测试服务器接口）
|
||
|
||
### 调用接口的正确方式
|
||
|
||
**使用自动生成的函数**，不要手写 axios 请求：
|
||
|
||
```typescript
|
||
// ✅ 正确：用生成的函数，有完整类型提示
|
||
import { getStudentPage } from '@/api/generated/api'
|
||
import type { Student } from '@/api/generated/model'
|
||
|
||
const { data } = await getStudentPage({ page: 1, size: 10, name: '张' })
|
||
// data 类型自动推断为 PageResult<Student>
|
||
|
||
// ❌ 错误：不要手写请求
|
||
const res = await request.get('/api/v1/school/students', { params: { page: 1 } })
|
||
```
|
||
|
||
### 获取最新接口定义
|
||
|
||
当后端提交了接口变更后：
|
||
|
||
```bash
|
||
git pull # 拉取最新代码
|
||
# src/api/generated/ 已自动更新，TypeScript 报红的地方 = 需要适配的地方
|
||
```
|
||
|
||
> 如果遇到 TypeScript 编译报错，说明接口有变化，根据错误提示修改调用代码即可。**不需要问后端接口格式**，类型定义就是答案。
|
||
|
||
### 新功能开发检查清单
|
||
|
||
| 步骤 | 前端工程师 | 后端工程师 | 说明 |
|
||
|-----|-----------|-----------|------|
|
||
| 1. 需求确认 | 评估页面结构 | 评估接口可行性 | 确保需求可实现 |
|
||
| 2. 接口设计 | 确认接口需求 | 写 Swagger 注解 | api-spec.yml 作为 contract |
|
||
| 3. 代码开发 | 开发 Vue 页面 | 实现 Controller | 可并行开发 |
|
||
| 4. 本地联调 | `npm run dev` | `docker compose up` | 对齐测试账号登录 |
|
||
| 5. 提交代码 | Git Pull 后提交 | 提交后端代码 | 一次性提交所有改动 |
|
||
|
||
### 前端 Mock 数据（可选）
|
||
|
||
在后端接口未完成时，前端可基于 api-spec.yml 使用 Mock 数据：
|
||
|
||
```typescript
|
||
// 使用 mockjs 或 orval 的 mock 功能
|
||
import { mockGetStudentPage } from '@/api/generated/mock'
|
||
|
||
const { data } = await mockGetStudentPage({ page: 1, size: 10 })
|
||
```
|
||
|
||
### 新增页面
|
||
|
||
```
|
||
src/views/
|
||
├── admin/ # 超管功能
|
||
├── school/ # 学校管理功能
|
||
├── teacher/ # 教师功能
|
||
└── parent/ # 家长功能
|
||
```
|
||
|
||
在对应目录下新建 `.vue` 文件，然后在 `src/router/index.ts` 注册路由。
|
||
|
||
### 提交代码
|
||
|
||
```bash
|
||
git add reading-platform-frontend/src/
|
||
git commit -m "feat(frontend): 新增学生列表页面"
|
||
git push origin main
|
||
```
|
||
|
||
---
|
||
|
||
## 六、测试工程师
|
||
|
||
### 接口测试
|
||
|
||
直接使用接口文档页面测试，无需额外工具：
|
||
|
||
1. 打开 http://8.148.151.56:3002/doc.html
|
||
2. 点击右上角「调试」或接口右侧「测试」
|
||
3. 填写参数，点击「发送」
|
||
4. 查看响应结果
|
||
|
||
**登录获取 Token**（测试需要鉴权的接口）：
|
||
|
||
1. 找到 `Auth → 登录` 接口
|
||
2. 发送登录请求，复制响应中的 `token`
|
||
3. 点击右上角「Authorize」，填入 `Bearer {token}`
|
||
4. 之后所有请求都会自动带上 Token
|
||
|
||
### 前端功能测试
|
||
|
||
- 测试地址：http://8.148.151.56:8081
|
||
- 每次有代码推送后约 2-3 分钟自动更新
|
||
|
||
### 提 Bug
|
||
|
||
在 git 仓库提 Issue，描述：
|
||
1. 操作步骤
|
||
2. 期望结果
|
||
3. 实际结果
|
||
4. 截图（如有）
|
||
|
||
---
|
||
|
||
## 七、原型开发工程师
|
||
|
||
原型工程师需要同时改前端页面和后端逻辑，按以下流程操作。
|
||
|
||
### 修改前端页面（无接口变更）
|
||
|
||
```bash
|
||
# 直接修改 src/views/ 下的 .vue 文件
|
||
git add reading-platform-frontend/src/views/
|
||
git commit -m "feat(ui): 修改学生列表页布局"
|
||
git push origin main
|
||
```
|
||
|
||
### 修改涉及接口变更
|
||
|
||
按以下顺序操作：
|
||
|
||
```
|
||
① 修改后端 Java 代码（Controller / Service / Entity）
|
||
② 本地启动后端验证接口正常
|
||
③ 更新接口规范：cd reading-platform-frontend && npm run api:update
|
||
④ 修改前端页面，使用新的接口函数
|
||
⑤ 一次性提交所有改动
|
||
```
|
||
|
||
```bash
|
||
git add reading-platform-java/src/
|
||
git add reading-platform-frontend/api-spec.yml
|
||
git add reading-platform-frontend/src/api/generated/
|
||
git add reading-platform-frontend/src/views/
|
||
git commit -m "feat: 学生列表新增年级筛选功能"
|
||
git push origin main
|
||
```
|
||
|
||
### 修改数据库结构
|
||
|
||
1. 新建 Flyway 脚本（`V7__描述.sql`）
|
||
2. 本地验证迁移脚本正确
|
||
3. 随代码一起提交
|
||
|
||
```bash
|
||
git add reading-platform-java/src/main/resources/db/migration/
|
||
git commit -m "feat(db): 学生表新增年级字段"
|
||
```
|
||
|
||
---
|
||
|
||
## 八、Git 提交规范
|
||
|
||
### 提交信息格式
|
||
|
||
```
|
||
类型(范围): 简短描述
|
||
|
||
类型：
|
||
feat 新功能
|
||
fix Bug 修复
|
||
chore 配置、依赖等杂项
|
||
refactor 重构（不影响功能）
|
||
docs 文档修改
|
||
```
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
feat(backend): 新增课程评价接口
|
||
feat(frontend): 新增课程评价页面
|
||
fix(backend): 修复分页参数未生效的问题
|
||
feat: 学生档案新增健康信息字段 # 前后端同时改
|
||
chore(api): 同步最新接口规范
|
||
```
|
||
|
||
### 常用 Git 命令
|
||
|
||
```bash
|
||
git pull # 拉取最新代码（每天开始工作前执行）
|
||
git status # 查看当前改了哪些文件
|
||
git add 文件路径 # 暂存指定文件
|
||
git add reading-platform-frontend/ # 暂存整个目录
|
||
git commit -m "feat: 描述" # 提交
|
||
git push origin main # 推送到服务器（触发自动部署）
|
||
git log --oneline -10 # 查看最近10条提交记录
|
||
git diff # 查看未提交的改动
|
||
```
|
||
|
||
---
|
||
|
||
## 九、自动部署说明
|
||
|
||
推送代码后服务器会自动完成部署，**无需手动操作**。
|
||
|
||
```
|
||
git push origin main
|
||
↓ 约 2-3 分钟
|
||
服务器自动：git pull → docker build → docker restart
|
||
↓
|
||
http://8.148.151.56:8081 更新完成
|
||
```
|
||
|
||
如果推送后超过 5 分钟页面未更新，可能是构建失败，联系管理员查看日志。
|
||
|
||
---
|
||
|
||
## 十、常见问题
|
||
|
||
**Q：推送失败，提示"rejected"**
|
||
```bash
|
||
git pull --rebase # 先拉取最新代码，合并后再推送
|
||
git push origin main
|
||
```
|
||
|
||
**Q：本地启动后端报数据库连接失败**
|
||
- 确认能访问开发服务器：`ping 8.148.151.56`
|
||
- 确认开发服务器 MySQL 容器正在运行（联系管理员）
|
||
- 检查 `docker-compose.yml` 中数据库地址和密码是否正确
|
||
|
||
**Q：运行 `npm run api:update` 报错**
|
||
- 确认服务器后端正在运行（http://8.148.151.56:3002 可访问）
|
||
- 或直接 `git pull` 使用已提交的 `api-spec.yml`，运行 `npm run api:gen`
|
||
|
||
**Q：前端 TypeScript 报错，提示类型不匹配**
|
||
- 这是正常现象，说明后端接口有变化
|
||
- 查看 `src/api/generated/` 里的新类型定义，按提示修改调用代码
|
||
|
||
**Q：想查看某个接口的详细参数**
|
||
- 打开 http://8.148.151.56:3002/doc.html 查看
|