316 lines
7.9 KiB
Markdown
316 lines
7.9 KiB
Markdown
# 前后端接口一致性规范
|
|
|
|
> **文档创建时间**: 2025-01-16
|
|
> **适用项目**: 校园管理系统 (hzdyjs_xg)
|
|
> **目标**: 彻底杜绝前后端字段名不一致等接口问题
|
|
|
|
## 🎯 规范目标
|
|
|
|
- **零容忍**前后端字段名不一致
|
|
- **统一化**接口定义和文档管理
|
|
- **自动化**一致性检查和验证
|
|
- **标准化**开发流程和协作机制
|
|
|
|
---
|
|
|
|
## 📋 核心规范标准
|
|
|
|
### 1. 字段命名统一原则
|
|
|
|
#### 🔴 强制性规范
|
|
```markdown
|
|
✅ 前后端字段名必须**完全一致**（大小写、拼写）
|
|
✅ 使用**驼峰命名法** (camelCase)
|
|
✅ 后端Entity/Bo/Vo**统一字段名**
|
|
✅ 前端TypeScript接口**严格对应**后端模型
|
|
```
|
|
|
|
#### 📝 标准字段名对照表
|
|
| 中文含义 | 标准字段名 | 错误示例 | 说明 |
|
|
|---------|-----------|---------|-----|
|
|
| 学生学号 | `studentNo` | ~~studentCode~~ | 统一使用No结尾 |
|
|
| 学生姓名 | `studentName` | ~~name~~ | 明确实体前缀 |
|
|
| 创建时间 | `createTime` | ~~createdTime~~ | 与RuoYi框架保持一致 |
|
|
| 当前状态 | `currentStatus` | ~~status~~ | 明确状态含义 |
|
|
|
|
### 2. 接口定义同步机制
|
|
|
|
#### 🔄 开发流程（必须遵循）
|
|
```mermaid
|
|
graph LR
|
|
A[后端模型定义] --> B[生成API文档]
|
|
B --> C[前端接口定义]
|
|
C --> D[一致性验证]
|
|
D --> E[代码审查]
|
|
E --> F[集成测试]
|
|
```
|
|
|
|
#### 📚 文档同步要求
|
|
- **后端模型变更** → **立即更新API文档**
|
|
- **API文档更新** → **立即通知前端团队**
|
|
- **前端接口定义** → **必须基于最新API文档**
|
|
|
|
---
|
|
|
|
## 🔧 技术实现方案
|
|
|
|
### 1. TypeScript接口自动生成
|
|
|
|
#### 方案A: 基于Swagger自动生成
|
|
```bash
|
|
# 安装swagger-typescript-api
|
|
npm install -D swagger-typescript-api
|
|
|
|
# 自动生成TypeScript接口
|
|
npx swagger-typescript-api -p http://localhost:8080/v3/api-docs -o ./src/api/types -n api-types.ts
|
|
```
|
|
|
|
#### 方案B: 后端注解驱动生成
|
|
```java
|
|
// 后端使用详细注解
|
|
@ApiModel(description = "奖学金申请记录")
|
|
public class JcbtScholarshipApplicationVo {
|
|
@ApiModelProperty(value = "学生学号", required = true)
|
|
private String studentNo; // 标准字段名
|
|
}
|
|
```
|
|
|
|
### 2. 一致性检查脚本
|
|
|
|
#### 检查脚本示例 (`scripts/check-api-consistency.js`)
|
|
```javascript
|
|
// 检查前后端字段名一致性
|
|
const fs = require('fs');
|
|
const path = require('path');
|
|
|
|
function checkApiConsistency() {
|
|
// 读取Swagger文档
|
|
const swaggerDoc = require('../docs/swagger.json');
|
|
|
|
// 读取前端TypeScript接口
|
|
const frontendTypes = fs.readFileSync('./src/api/types.ts', 'utf8');
|
|
|
|
// 字段名一致性检查
|
|
const inconsistencies = [];
|
|
|
|
Object.keys(swaggerDoc.definitions).forEach(model => {
|
|
const backendFields = Object.keys(swaggerDoc.definitions[model].properties);
|
|
const frontendInterface = extractInterfaceFields(frontendTypes, model);
|
|
|
|
backendFields.forEach(field => {
|
|
if (!frontendInterface.includes(field)) {
|
|
inconsistencies.push({
|
|
model: model,
|
|
field: field,
|
|
issue: 'Backend field missing in frontend'
|
|
});
|
|
}
|
|
});
|
|
});
|
|
|
|
if (inconsistencies.length > 0) {
|
|
console.error('❌ API一致性检查失败:', inconsistencies);
|
|
process.exit(1);
|
|
} else {
|
|
console.log('✅ API一致性检查通过');
|
|
}
|
|
}
|
|
|
|
checkApiConsistency();
|
|
```
|
|
|
|
### 3. Git Pre-commit Hook
|
|
|
|
#### `.husky/pre-commit` 配置
|
|
```bash
|
|
#!/usr/bin/env sh
|
|
. "$(dirname -- "$0")/_/husky.sh"
|
|
|
|
# 运行一致性检查
|
|
npm run check:api-consistency
|
|
|
|
# ESLint检查
|
|
npm run lint
|
|
|
|
# 类型检查
|
|
npm run type-check
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 Code Review检查清单
|
|
|
|
### 🔍 前后端接口变更必查项
|
|
|
|
#### ✅ 后端变更检查
|
|
- [ ] Entity/Bo/Vo字段名是否一致？
|
|
- [ ] 新增字段是否有JSR303校验注解？
|
|
- [ ] 是否更新了对应的API文档？
|
|
- [ ] 是否通知了前端团队？
|
|
|
|
#### ✅ 前端变更检查
|
|
- [ ] TypeScript接口是否与后端模型一致？
|
|
- [ ] 新增字段是否有对应的校验规则？
|
|
- [ ] 是否测试了完整的数据流转？
|
|
- [ ] 是否处理了字段为空的情况？
|
|
|
|
#### ✅ API文档检查
|
|
- [ ] 字段类型是否准确描述？
|
|
- [ ] 必填字段是否明确标注？
|
|
- [ ] 示例数据是否真实有效？
|
|
- [ ] 变更记录是否完整记录？
|
|
|
|
---
|
|
|
|
## 🧪 测试验证机制
|
|
|
|
### 1. 接口契约测试
|
|
|
|
#### Postman集合测试
|
|
```json
|
|
{
|
|
"name": "奖学金申请API测试",
|
|
"tests": [
|
|
{
|
|
"name": "字段完整性检查",
|
|
"script": "pm.test('Response has all required fields', function () {
|
|
const response = pm.response.json();
|
|
pm.expect(response.data).to.have.property('studentNo');
|
|
pm.expect(response.data).to.have.property('studentName');
|
|
pm.expect(response.data).to.have.property('currentStatus');
|
|
});"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 2. 自动化集成测试
|
|
|
|
#### Jest测试用例
|
|
```typescript
|
|
describe('ScholarshipApplication API', () => {
|
|
test('should have consistent field names', async () => {
|
|
const response = await getScholarshipApplication(1);
|
|
|
|
// 检查关键字段是否存在
|
|
expect(response.data).toHaveProperty('studentNo');
|
|
expect(response.data).not.toHaveProperty('studentCode'); // 确保错误字段不存在
|
|
expect(response.data).toHaveProperty('currentStatus');
|
|
});
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 监控和度量
|
|
|
|
### 1. 错误监控指标
|
|
|
|
#### 关键监控点
|
|
- **接口调用失败率** - 字段缺失导致的400错误
|
|
- **前端TypeError数量** - undefined字段访问错误
|
|
- **Code Review拒绝率** - 接口不一致相关的PR被拒绝次数
|
|
|
|
### 2. 质量度量标准
|
|
|
|
#### 🎯 目标指标
|
|
- **零字段名不一致**事故
|
|
- **API文档准确率** > 99%
|
|
- **接口契约测试覆盖率** > 90%
|
|
- **一致性检查自动化率** = 100%
|
|
|
|
---
|
|
|
|
## 🚨 应急处理流程
|
|
|
|
### 发现不一致问题时的处理步骤
|
|
|
|
#### 1. 立即响应 (10分钟内)
|
|
```bash
|
|
# 1. 确认影响范围
|
|
git log --oneline --grep="studentCode\|studentNo" -n 10
|
|
|
|
# 2. 创建紧急修复分支
|
|
git checkout -b hotfix/field-consistency-fix
|
|
|
|
# 3. 快速定位所有不一致点
|
|
grep -r "studentCode" web/src/
|
|
```
|
|
|
|
#### 2. 快速修复 (30分钟内)
|
|
- 统一修改为标准字段名
|
|
- 更新相关TypeScript接口
|
|
- 执行一致性检查脚本
|
|
- 提交带有详细说明的commit
|
|
|
|
#### 3. 验证和部署 (60分钟内)
|
|
- 执行完整的接口测试
|
|
- Code Review快速通道
|
|
- 生产环境热修复部署
|
|
- 监控系统错误日志
|
|
|
|
#### 4. 复盘和改进 (24小时内)
|
|
- 记录问题根因分析
|
|
- 更新预防措施
|
|
- 加强相关流程和检查
|
|
|
|
---
|
|
|
|
## 🎓 培训和知识传递
|
|
|
|
### 1. 团队培训计划
|
|
|
|
#### 📚 培训内容
|
|
- **接口设计最佳实践**
|
|
- **前后端协作规范**
|
|
- **一致性检查工具使用**
|
|
- **问题排查和修复流程**
|
|
|
|
### 2. 文档和资料
|
|
|
|
#### 🔗 参考资料
|
|
- [RESTful API设计规范](./RESTful-API设计规范.md)
|
|
- [TypeScript接口定义标准](./TypeScript接口定义标准.md)
|
|
- [前后端协作流程](./前后端协作流程.md)
|
|
- [常见问题FAQ](./前后端接口FAQ.md)
|
|
|
|
---
|
|
|
|
## 📈 持续改进
|
|
|
|
### 季度审查机制
|
|
- **接口质量回顾** - 每季度统计不一致问题
|
|
- **工具链优化** - 评估和改进自动化工具
|
|
- **流程迭代** - 基于实际问题优化流程
|
|
- **培训效果评估** - 团队技能提升评估
|
|
|
|
### 长期规划
|
|
- **接口代码生成自动化**
|
|
- **实时一致性监控系统**
|
|
- **AI辅助接口设计**
|
|
- **跨项目规范标准化**
|
|
|
|
---
|
|
|
|
## ⚡ 快速参考
|
|
|
|
### 常用命令
|
|
```bash
|
|
# 检查字段名一致性
|
|
npm run check:api-consistency
|
|
|
|
# 生成TypeScript接口
|
|
npm run generate:api-types
|
|
|
|
# 运行接口契约测试
|
|
npm run test:api-contract
|
|
```
|
|
|
|
### 应急联系人
|
|
- **前端负责人**: 技术负责人
|
|
- **后端负责人**: 技术负责人
|
|
- **DevOps负责人**: 运维负责人
|
|
|
|
---
|
|
|
|
**📝 文档维护**: 本规范文档随项目发展持续更新，每月审查一次，确保实用性和时效性。 |