Vue3前端开发与联调
页面导读
适用场景适合开发 Vue3 管理端页面、接入后端接口、维护 OpenAPI 类型和执行前后端联调检查。
源码位置Vue3 管理端位于源码仓库 `vue3/`，历史 Vue2 管理端位于 `vue/`。
核心命令`npm run dev`、`npm run dev:mock`、`npm run openapi`、`npm run verify:integration`。
验收点页面可运行、接口契约一致、Mock 和真实接口一致、E2E 联调检查通过。
一、目录结构
| 目录 | 作用 |
|---|---|
vue3/src/views | 页面入口，按业务模块组织 |
vue3/src/api | API 请求封装 |
vue3/src/router | 路由、固定页面和动态路由基础逻辑 |
vue3/src/mocks | 稳定 Mock 数据 |
vue3/e2e | Playwright E2E 用例 |
vue3/scripts | OpenAPI、集成检查等脚本 |
vue3/src/api/schema.d.ts | OpenAPI 生成的类型定义 |
二、本地开发
bash
cd vue3
npm install
npm run dev常用模式：
| 命令 | 用途 |
|---|---|
npm run dev | 本地前端连接本地后端 |
npm run dev:mock | 本地前端连接 Mock 服务 |
npm run dev:test | 本地前端连接共享测试后端 |
npm run build | 生产构建 |
npm run preview | 预览构建产物 |
浏览器请求前缀统一保持为 /dev-api，不同环境通过环境变量和代理目标切换。
三、接口契约
后端 OpenAPI 是前后端接口契约来源。
默认生成：
bash
cd vue3
npm run openapi检查 schema 是否过期：
bash
cd vue3
npm run openapi:check指定 OpenAPI 地址：
powershell
cd vue3
$env:FASTBEE_OPENAPI_URL="http://test-api.fastbee.cn/v3/api-docs"
npm run openapi每次后端接口变更，都需要确认 URL、Method、请求参数、响应结构、分页结构、上传下载行为和错误码。
四、Mock 与联调
推荐流程：
- 后端接口未完成时，使用
npm run dev:mock开发页面。 - 在 Apifox 中维护成功、空数据、业务失败、401/403 示例。
- 对关键流程在
vue3/src/mocks中维护稳定 Mock。 - 页面完成后运行联调检查。
- 接入真实后端后，重新运行 E2E 和 Apifox 集合。
聚合检查：
bash
cd vue3
npm run verify:integration该命令会执行集成静态检查和 Playwright 联调用例。
五、请求追踪
Vue3 Axios 请求会携带 X-Request-Id。后端响应和日志应回显同一个 requestId。
联调时如果接口失败，应记录：
- requestId。
- 请求 URL 和 Method。
- 请求参数。
- 响应体。
- 当前登录用户和角色。
- 复现页面和操作步骤。
这样后端可以快速在日志中定位。
六、新模块接入步骤
- 在
vue3/src/views下新增页面目录。 - 在
vue3/src/api下新增 API 文件。 - 确认后端 OpenAPI 已包含目标接口。
- 执行
npm run openapi更新类型。 - 补充 Mock 示例。
- 接入菜单和按钮权限。
- 补充 Playwright 稳定用例。
- 执行
npm run verify:integration。
七、常见问题
页面请求 404
检查接口路径是否带 /dev-api 前缀、代理目标是否正确、后端接口是否已注册。
页面有权限但按钮不显示
检查菜单权限、按钮权限标识、角色授权和前端权限指令。
openapi:check 失败
说明后端契约变化后 schema.d.ts 未更新。执行 npm run openapi 后再检查类型变化是否符合预期。
E2E 失败但页面手动正常
检查 Mock 数据是否变化、定位选择器是否稳定、异步等待是否充分，以及测试环境是否污染本地缓存。