前言
本文基于真实项目经验，系统梳理前后端分离架构下的开发规范、协作流程与部署实践，适用于 Vue + Spring Boot 技术栈，帮助团队快速搭建可维护、可扩展的现代化 Web 应用。
一、项目结构与角色边界
1、整体目录约定
project-root
├── frontend/ # Vue 前端
│ ├── src/api # 接口封装
│ ├── src/views # 业务页面
│ ├── src/router # 前端路由
│ └── .env.* # 多环境变量
├── backend/ # Spring Boot 后端
│ ├── src/main/java
│ │ ├── controller # REST 接口
│ │ ├── service # 业务逻辑
│ │ ├── repository # 数据访问
│ │ └── config # 统一配置
│ └── pom.xml
├── deploy/ # Docker & K8s 部署脚本
└── docs/ # Swagger/YApi 接口文档
2、角色职责与协作流程
| 阶段 |
前端 |
后端 |
共同点 |
| 需求评审 |
评估交互工作量 |
评估业务/数据工作量 |
输出接口粒度 |
| 接口定义 |
提供 UI 需要的数据结构 |
编写 Swagger/YApi 并生成 Mock |
评审后锁定接口文档 |
| 开发 |
使用 Mock 数据并行开发 |
实现业务逻辑 & 单元测试 |
Git Flow 分支管理 |
| 联调 |
切换代理到真实后端 |
打开 Swagger 在线调试 |
使用 Postman 做契约测试 |
| 上线 |
构建静态包→CDN |
Docker 镜像→K8s/虚拟机 |
CI/CD 同 Pipeline |
二、接口设计规范
1、RESTful URL + 版本控制
GET /api/v1/users?page=1&size=20
POST /api/v1/users
PUT /api/v1/users/{id}
DELETE /api/v1/users/{id}
2、统一返回体
{
"code": 0,
"msg": "success",
"data": { ... },
"traceId": "c0a8644e166..."
}
3、自动生成文档
Springfox/Knife4j 一键扫描注解 → 前端可直接在线调试，无需 Postman 导入。
三、安全与质量红线
| 维度 |
实践要点 |
| 认证 |
JWT + Spring Security；Token 存 HttpOnly Cookie 或 Authorization Header |
| 鉴权 |
@PreAuthorize(“hasRole(‘ADMIN’)”) |
| 参数校验 |
DTO 层 @Validated + Hibernate Validator |
| 跨域 |
Spring 全局 CORS 配置或使用 Gateway 统一处理 |
| 敏感数据 |
统一脱敏 + 返回最小化原则 |
| 审计日志 |
AOP 记录所有请求耗时、参数、返回值与异常 |
四、前端工程化实践
- 请求封装：基于 Axios 的
src/api/request.ts 自动携带 Token、统一错误提示。
- 环境变量：
.env.development / .env.production 区分代理地址。
- 路由守卫：动态加载菜单 + 权限指令
v-permission。
- 构建优化：Vite/Webpack 拆包 + CDN + Gzip，首屏 < 1.5 s。
五、后端可观测性
| 能力 |
技术方案 |
| 日志 |
Logback + ELK 收集 |
| 链路追踪 |
Spring Cloud Sleuth → Zipkin |
| 指标 |
Micrometer → Prometheus → Grafana Dashboard |
| 告警 |
PrometheusRule 钉钉/飞书机器人 |
六、部署与 CI/CD
- 容器化：
- 前端：
nginx:alpine 静态镜像，大小 < 20 MB。
- 后端：多阶段 Dockerfile
mvn package → openjdk:17-jre-slim。
- 流水线示例（GitLab CI）：
stages: [build, docker, deploy]
build:frontend:
script: cd frontend && npm ci && npm run build
build:backend:
script: cd backend && mvn -B package -DskipTests
deploy:k8s:
script: helm upgrade --install app chart/
- 灰度发布：K8s Ingress + Nginx 权重分流，支持秒级回滚。
七、团队协作 Tips
- 接口变更：通过 YApi 的「通知」功能告知全员，旧版本保留 2 个 Sprint。
- Mock 数据：Mock.js 自动拦截 Ajax 请求，支持随机图片、延迟返回。
- 代码规范：前端 ESLint + Prettier，后端 Spotless + Checkstyle，提交前 Git Hook 强制格式化。