用途
前后端对接技能专门用于前后端 API 对接检查和调试。当用户需要检查前后端 API 对接、调试接口调用、确保数据格式一致时使用此技能。典型使用场景包括：检查前后端对接是否正确、前端调用后端 API 报错、确保前后端数据格式一致、调试接口调用问题、新增 API 的对接工作。
主要能力
该技能覆盖以下对接检查与调试工作：
- 检查前后端接口文档
- 分析代码总结 API 规范
- 验证请求/响应格式一致性
- 确保数据结构正确映射
- 调试网络调用问题
使用方式
技能按六步对接流程展开：
第一步：查看项目结构
先了解项目的前后端目录结构，例如查看前端目录（frontend/src/、frontend/src/api/、frontend/src/stores/）和后端目录（backend/、backend/app/）。
第二步：查找或创建 API 文档
优先查找现有文档，例如使用 find 命令搜索 docs/、backend/docs/、frontend/docs/ 下的 API 相关文件。常见文档位置包括 docs/api-reference.md、docs/frontend/、backend/tests/test_*.py、backend/README.md。
第三步：分析后端 API 规范
查看后端主入口文件（如 backend/app/main.py），重点查找 @app.get/post/put/delete 装饰器定义的路由、response_model 指定的响应格式、参数定义（query、path、body）；查看 Schema 定义（如 backend/app/schemas.py），重点查找 Pydantic 模型定义、字段类型和验证规则、ApiResponse 格式、PaginatedResponse 格式；查看测试文件（如 backend/tests/test_main.py），重点查找测试请求的参数格式、预期的响应格式、断言检查的数据结构。
第四步：分析前端 API 调用
查看 API 封装（如 frontend/src/api/index.js），重点查找 baseURL 配置、axios 拦截器处理、各个 API 方法的参数和返回值；查看 Store 状态管理（如 frontend/src/stores/.js），重点查找 API 调用方式、响应数据处理方式、数据提取路径（res.data vs res.items）；查看页面组件（如 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()，验证是否作为数组处理
端口配置验证：后端配置（如 backend/app/config.py）查找 host、port 配置，默认通常是 0.0.0.0:8000；前端代理配置（如 frontend/vite.config.js）中 server.proxy['/api'] 应指向后端地址，例如 target: 'http://localhost:8000'；前端 baseURL（如 frontend/src/api/index.js）应为 '/api'（走代理）。
第六步：检查清单
- 后端 API 端点路径与前端调用一致
- 请求方法（GET/POST/PUT/DELETE）匹配
- 请求参数名称和类型正确
- 响应格式处理正确（.data vs 直接访问）
- 数据字段映射正确（嵌套对象、数组）
- 错误处理覆盖异常情况
- CORS 配置允许前端域名
常见问题与解决方案
问题1：响应格式不一致
症状：前端获取不到数据，显示 undefined。原因：后端有些 API 返回 ApiResponse 包装，有些直接返回数据。解决方案：检查后端返回格式，调整前端处理。如果是 ApiResponse 格式，使用 this.data = res.data；如果是直接返回格式，使用 this.data = res。
问题2：CORS 错误
症状：浏览器控制台显示 CORS policy 错误。解决方案：在后端（如 backend/app/main.py）添加 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）定义 GET /api/articles，response_model 为 PaginatedResponse，返回格式为 {items: [...], total: 100, page: 1, page_size: 20, total_pages: 5}。前端（Vue3 + Pinia）在 stores/article.js 中调用 articleApi.getList({ page: 1, page_size: 20 })，直接访问 res.items 和 res.total，因为后端返回 PaginatedResponse 而不是 ApiResponse。
案例：React + Node.js 对接
后端（Express）返回 res.json({ success: true, data: { items: [...], total: 100 } })。前端（React）调用 api.get('/articles') 后，需要访问 res.data.data.items，即 setItems(res.data.data.items)。
文档模板
技能提供 API 对接文档模板，包含服务地址（前端、后端、API 代理）、API 端点列表（请求方式与响应格式）、数据结构（如文章对象的字段定义）以及注意事项。
注意事项
- 响应格式不统一：很多后端框架的列表接口直接返回分页数据，而详情接口返回包装格式
- 日期格式：后端通常返回 ISO 格式字符串，前端需要解析
- 空值处理：前端需要处理可能为 null 的字段
- 错误处理：确保拦截器正确处理 HTTP 错误状态
- 类型安全：使用 TypeScript 可以提前发现类型不匹配
工具推荐
- API 测试：Postman, curl, HTTPie
- 网络抓包：浏览器 DevTools Network 面板
- 文档生成：FastAPI 自动生成 Swagger 文档
- 类型检查：TypeScript 接口定义
限制
该技能的具体安装方式、运行环境要求、是否收费及价格等信息暂未提供。