frontend-backend-integration

此技能专门用于前后端API对接检查和调试，包括：

• 检查前后端接口文档
• 分析代码总结API规范
• 验证请求/响应格式一致性
• 确保数据结构正确映射
• 调试网络调用问题

• "检查前后端对接是否正确"
• "前端调用后端API报错"
• "确保前后端数据格式一致"
• "调试接口调用问题"
• "新增API的对接工作"

第一步：查看项目结构

首先了解项目的前后端目录结构：

```bash

# 查看前端目录

ls frontend/src/

ls frontend/src/api/

ls frontend/src/stores/

# 查看后端目录

ls backend/

ls backend/app/

```

第二步：查找或创建API文档

#### 优先查找现有文档

```bash

# 查找API文档

find docs/ -name "api" -o -name "API" -o -name "接口"

find backend/docs/ -type f

find frontend/docs/ -type f

```

#### 常见文档位置

• docs/api-reference.md - API参考文档
• docs/frontend/ - 前端相关文档
• backend/tests/test_*.py - 后端测试文件（包含API行为）
• backend/README.md - 后端说明

第三步：分析后端API规范

#### 1. 查看后端主入口文件

```python

# backend/app/main.py 或类似文件

# 重点查找：

# - @app.get/post/put/delete 装饰器定义的路由

# - response_model 指定的响应格式

# - 参数定义（query, path, body）

```

#### 2. 查看Schema定义

```python

# backend/app/schemas.py

# 重点查找：

# - Pydantic模型定义

# - 字段类型和验证规则

# - ApiResponse格式

# - PaginatedResponse格式

```

#### 3. 查看测试文件

```python

# backend/tests/test_main.py

# 重点查找：

# - 测试请求的参数格式

# - 预期的响应格式

# - 断言检查的数据结构

```

第四步：分析前端API调用

#### 1. 查看API封装

```javascript

// frontend/src/api/index.js

// 重点查找：

// - baseURL配置

// - axios拦截器处理

// - 各个API方法的参数和返回值

```

#### 2. 查看Store状态管理

```javascript

// frontend/src/stores/*.js

// 重点查找：

// - API调用方式

// - 响应数据处理方式

// - 数据提取路径（res.data vs res.items）

```

#### 3. 查看页面组件

```vue

// frontend/src/views/*.vue

// 重点查找：

// - API调用时机

// - 数据使用方式

// - 错误处理

```

第五步：对比验证

#### 响应格式对照表

| 后端返回格式 | 前端应提取 | 验证点 |

|--------------|------------|--------|

| ApiResponse {code, message, data} | res.data | 前端是否用.data |

| PaginatedResponse {items, total, page} | res.items, res.total | 前端是否直接访问 |

| 嵌套对象 {category: {id, name}} | item.category.name | 组件是否正确访问 |

| 数组字段 {tags: [...]} | item.tags.map() | 是否作为数组处理 |

#### 端口配置验证

后端配置：

```python

# backend/app/config.py

# 查找 host, port 配置

# 默认通常是 0.0.0.0:8000

```

前端代理配置：

```javascript

// frontend/vite.config.js

// server.proxy['/api'] 应指向后端地址

// 例如：target: 'http://localhost:8000'

```

前端baseURL：

```javascript

// frontend/src/api/index.js

// baseURL 应为 '/api'（走代理）

```

第六步：检查清单

• [ ] 后端API端点路径与前端调用一致
• [ ] 请求方法（GET/POST/PUT/DELETE）匹配
• [ ] 请求参数名称和类型正确
• [ ] 响应格式处理正确（.data vs 直接访问）
• [ ] 数据字段映射正确（嵌套对象、数组）
• [ ] 错误处理覆盖异常情况
• [ ] CORS配置允许前端域名

问题1：响应格式不一致

症状：前端获取不到数据，显示undefined

原因：后端有些API返回ApiResponse包装，有些直接返回数据

解决方案：

```javascript

// 检查后端返回格式，调整前端处理

// 如果是 ApiResponse 格式：

this.data = res.data

// 如果是直接返回格式：

this.data = res

```

问题2：CORS错误

症状：浏览器控制台显示CORS policy错误

解决方案：

```python

# backend/app/main.py

app.add_middleware(

CORSMiddleware,

allow_origins=["http://localhost:5173"], # 前端地址

allow_credentials=True,

allow_methods=["*"],

allow_headers=["*"],

)

```

问题3：端口冲突

症状：前端启动后无法访问后端API

解决方案：

• 检查后端是否在正确端口运行（默认8000）
• 检查前端vite.config.js的proxy配置
• 使用netstat -ano | findstr :8000检查端口占用

问题4：字段名不匹配

症状：某些数据显示不正常

解决方案：

• 对比后端Schema定义和前端使用字段
• 检查snake_case vs camelCase转换
• 确认嵌套对象访问路径

案例：Vue3 + FastAPI 对接

后端（FastAPI）：

```python

@app.get("/api/articles", response_model=PaginatedResponse)

async def list_articles(page: int = 1, page_size: int = 20):

# 返回格式：{items: [...], total: 100, page: 1, page_size: 20, total_pages: 5}

return PaginatedResponse(...)

```

前端（Vue3 + Pinia）：

```javascript

// stores/article.js

const res = await articleApi.getList({ page: 1, page_size: 20 })

// 直接访问，因为后端返回PaginatedResponse而不是ApiResponse

this.articles = res.items || []

this.pagination = {

total: res.total || 0,

page: res.page || 1,

// ...

}

```

案例：React + Node.js 对接

后端（Express）：

```javascript

res.json({

success: true,

data: { items: [...], total: 100 }

})

```

前端（React）：

```javascript

const res = await api.get('/articles')

// 需要访问 .data.data.items

setItems(res.data.data.items)

```

API对接文档模板

```markdown

# 前后端API对接文档

• 前端：http://localhost:5173
• 后端：http://localhost:8000
• API代理：/api -> http://localhost:8000/api

文章列表

• 请求：GET /api/articles?page=1&page_size=20
• 响应：

- 格式：直接 PaginatedResponse

- 字段：{items, total, page, page_size, total_pages}

文章详情

• 请求：GET /api/articles/{id}
• 响应：

- 格式：ApiResponse {code, message, data}

- 数据在 data 字段中

文章对象（列表）

```javascript

{

id: number,

title: string,

slug: string,

summary: string | null,

cover_image: string | null,

category: { id, name, slug } | null,

tags: [{ id, name, slug }],

author_name: string,

views: number,

published_at: string | null

}

```

```

1. 响应格式不统一：很多后端框架的列表接口直接返回分页数据，而详情接口返回包装格式
2. 日期格式：后端通常返回ISO格式字符串，前端需要解析
3. 空值处理：前端需要处理可能为null的字段
4. 错误处理：确保拦截器正确处理HTTP错误状态
5. 类型安全：使用TypeScript可以提前发现类型不匹配

• API测试：Postman, curl, HTTPie
• 网络抓包：浏览器DevTools Network面板
• 文档生成：FastAPI自动生成Swagger文档
• 类型检查：TypeScript接口定义