chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
hospital_performance/.qoder/repowiki/zh/content/前端开发指南/API集成与数据处理.md
chenqi 44f250f58e 提交文件
2026-02-28 15:16:15 +08:00

17 KiB
Raw Permalink Blame History

API集成与数据处理

**本文引用的文件** - [frontend/src/api/request.js](file://frontend/src/api/request.js) - [frontend/src/api/index.js](file://frontend/src/api/index.js) - [frontend/src/api/auth.js](file://frontend/src/api/auth.js) - [frontend/src/api/department.js](file://frontend/src/api/department.js) - [frontend/src/api/staff.js](file://frontend/src/api/staff.js) - [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js) - [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js) - [frontend/src/api/salary.js](file://frontend/src/api/salary.js) - [frontend/src/api/template.js](file://frontend/src/api/template.js) - [frontend/src/api/stats.js](file://frontend/src/api/stats.js) - [frontend/src/stores/user.js](file://frontend/src/stores/user.js) - [frontend/src/stores/app.js](file://frontend/src/stores/app.js) - [frontend/src/router/index.js](file://frontend/src/router/index.js) - [frontend/package.json](file://frontend/package.json) - [frontend/vite.config.js](file://frontend/vite.config.js)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本指南围绕前端API集成与数据处理展开，覆盖HTTP请求封装、拦截器配置与错误处理、认证token管理、请求参数与查询条件传递、响应数据处理与状态码判断、分页与筛选排序、以及开发环境代理与生产部署要点。文档同时给出常见问题排查建议，帮助开发者快速理解并扩展该系统的API层。

项目结构

前端采用模块化API目录组织，按业务域拆分接口文件，并通过统一的请求封装与拦截器实现跨域代理、鉴权、错误提示等横切能力；Pinia用于状态管理，Vue Router负责路由与鉴权守卫；Vite提供开发服务器与代理配置。

graph TB
subgraph "前端"
VUE["Vue 应用<br/>main.js"]
ROUTER["路由<br/>router/index.js"]
STORE_USER["用户状态<br/>stores/user.js"]
STORE_APP["应用状态<br/>stores/app.js"]
API_INDEX["API聚合<br/>api/index.js"]
API_REQ["请求封装<br/>api/request.js"]
API_AUTH["认证接口<br/>api/auth.js"]
API_DEPT["科室接口<br/>api/department.js"]
API_STAFF["员工接口<br/>api/staff.js"]
API_IND["指标接口<br/>api/indicator.js"]
API_ASSESS["考核接口<br/>api/assessment.js"]
API_SAL["工资接口<br/>api/salary.js"]
API_TPL["模板接口<br/>api/template.js"]
API_STATS["统计接口<br/>api/stats.js"]
end
VUE --> ROUTER
VUE --> STORE_USER
VUE --> STORE_APP
VUE --> API_INDEX
API_INDEX --> API_REQ
API_INDEX --> API_AUTH
API_INDEX --> API_DEPT
API_INDEX --> API_STAFF
API_INDEX --> API_IND
API_INDEX --> API_ASSESS
API_INDEX --> API_SAL
API_INDEX --> API_TPL
API_INDEX --> API_STATS

图表来源

章节来源

核心组件

  • 统一请求封装与拦截器
    • 基础配置：基础URL、超时、默认Content-Type
    • 请求拦截：自动注入Authorization头（Bearer Token）
    • 响应拦截：统一错误码判断、状态码分支处理、消息提示与路由跳转
  • 认证与会话管理
    • 登录、获取当前用户、登出
    • Token持久化与路由守卫联动
  • 状态管理
    • 用户状态：token、userInfo、登录/登出
    • 应用状态：侧边栏折叠、科室树加载
  • 路由与鉴权
    • 全局前置守卫：未登录禁止访问受保护页面
  • 开发代理与构建
    • Vite代理到后端服务
    • 构建脚本与依赖

章节来源

架构总览

下图展示从前端调用到后端服务的整体链路，包括请求拦截、认证、响应处理与错误反馈。

sequenceDiagram
participant View as "视图组件"
participant Store as "Pinia状态"
participant API as "API模块"
participant Req as "请求封装(request.js)"
participant Axios as "Axios实例"
participant Proxy as "Vite代理(/api)"
participant Backend as "后端服务"
View->>Store : 触发动作(如登录/加载数据)
Store->>API : 调用具体接口函数
API->>Req : 发起HTTP请求
Req->>Axios : 配置headers/params/timeout
Axios->>Proxy : 将/api前缀转发
Proxy->>Backend : 代理到后端地址
Backend-->>Proxy : 返回JSON响应
Proxy-->>Axios : 返回响应
Axios-->>Req : 进入响应拦截器
Req-->>API : 统一处理code/status
API-->>Store : 返回标准化数据
Store-->>View : 更新UI

图表来源

详细组件分析

统一请求封装与拦截器

  • 基础配置
    • 基础URL为/api/v1，所有接口以此为前缀
    • 默认超时30秒，Content-Type为application/json
  • 请求拦截器
    • 从localStorage读取token并在请求头Authorization中附加Bearer前缀
  • 响应拦截器
    • 自定义code字段判断：当code不等于200时，弹出错误消息并reject
    • 对常见HTTP状态码进行分支处理：401清理token并跳转登录、403无权限、404资源不存在、500服务器错误
    • 其他错误：优先展示后端detail，否则提示网络错误
flowchart TD
Start(["进入响应拦截器"]) --> CheckCode["检查自定义code字段"]
CheckCode --> CodeOK{"code是否为200?"}
CodeOK --> |是| ReturnRes["返回data"]
CodeOK --> |否| ShowMsg["弹出错误消息"]
ShowMsg --> RejectErr["Promise.reject(error)"]
ReturnRes --> End(["结束"])
RejectErr --> End

图表来源

章节来源

认证与会话管理

  • 登录
    • 使用表单编码提交用户名与密码
    • 成功后保存access_token至localStorage并写入store
  • 获取当前用户
    • 通过受保护接口获取用户信息
  • 登出
    • 清空token与用户信息，删除localStorage中的token并跳转登录页
  • 路由守卫
    • 未携带token访问受保护路由时重定向至登录页
sequenceDiagram
participant View as "登录页"
participant Store as "useUserStore"
participant API as "auth.js"
participant Req as "request.js"
participant Router as "router/index.js"
View->>Store : 调用login(username,password)
Store->>API : 调用login接口
API->>Req : POST /auth/login(表单编码)
Req-->>API : 返回{access_token}
API-->>Store : 返回token
Store->>Store : 写入localStorage与store
Store->>Router : 登录成功后继续导航

图表来源

章节来源

数据格式与参数传递

  • 查询参数
    • 多数GET接口通过{ params }传入查询条件，支持分页、筛选、排序等
  • 特殊场景
    • 批量创建考核时，后端期望重复的查询参数名，前端使用URLSearchParams拼接数组值
  • 表单提交
    • 登录接口使用application/x-www-form-urlencoded，其余接口默认JSON

章节来源

响应数据处理与状态码判断

  • 自定义code字段
    • 当响应data.code不为200时，统一视为业务错误并提示
  • HTTP状态码分支
    • 401：清除token并跳转登录
    • 403/404/500：分别提示对应错误
    • 其他：展示后端detail或网络错误
  • 返回值
    • 成功时返回data，便于上层直接消费

章节来源

分页、搜索与排序

  • 分页
    • 通过查询参数传递页码与每页数量，后端返回总数与列表
  • 搜索与过滤
    • 通过查询参数传入关键词与筛选条件
  • 排序
    • 通过查询参数传入排序字段与方向
  • 示例接口
    • 科室、员工、指标、模板、统计等均支持上述模式

章节来源

文件上传与下载

  • 上传
    • 使用multipart/form-data提交文件，后端返回上传结果
  • 下载
    • 通过a链接或Blob对象触发浏览器下载
  • 进度显示
    • 可通过axios上传配置的onUploadProgress回调实现
  • 取消请求
    • 可使用AbortController在组件卸载或切换时取消未完成请求

说明：当前仓库未发现具体的上传/下载实现代码，以上为通用实践建议。

Mock数据与开发环境

  • 开发代理
    • Vite将/api前缀代理到本地后端服务，避免跨域问题
  • Mock策略
    • 可在开发阶段引入mock库或后端模拟服务，便于联调与前端独立开发

章节来源

生产环境部署

  • 构建产物
    • 使用Vite构建静态资源，输出至dist目录
  • 静态部署
    • 将dist作为静态站点部署，保持/api前缀不变
  • 后端代理
    • 生产环境需确保/api请求能正确转发至后端服务

章节来源

依赖关系分析

  • 组件耦合
    • API模块仅依赖统一请求封装，低耦合高内聚
    • 路由守卫与状态管理共同保障鉴权
  • 外部依赖
    • axios：HTTP客户端
    • element-plus：消息提示与UI组件
    • pinia/vue-router：状态与路由
graph LR
API_REQ["api/request.js"] --> AXIOS["axios"]
API_AUTH["api/auth.js"] --> API_REQ
API_DEPT["api/department.js"] --> API_REQ
API_STAFF["api/staff.js"] --> API_REQ
API_IND["api/indicator.js"] --> API_REQ
API_ASSESS["api/assessment.js"] --> API_REQ
API_SAL["api/salary.js"] --> API_REQ
API_TPL["api/template.js"] --> API_REQ
API_STATS["api/stats.js"] --> API_REQ
STORE_USER["stores/user.js"] --> API_AUTH
STORE_APP["stores/app.js"] --> API_DEPT
ROUTER["router/index.js"] --> STORE_USER

图表来源

章节来源

性能考虑

  • 请求合并与去抖
    • 对频繁触发的搜索/筛选操作，可在组件层增加防抖
  • 缓存策略
    • 对不常变动的数据（如字典、类型列表）可加入内存缓存
  • 分页与懒加载
    • 列表页使用分页，结合虚拟滚动提升渲染性能
  • 体积优化
    • 按需引入Element Plus组件，减少打包体积

故障排查指南

  • 登录后仍被重定向至登录页
    • 检查localStorage中token是否存在，确认路由守卫逻辑
  • 401错误频繁出现
    • 检查请求头Authorization是否正确附加，确认后端token有效期
  • 403/404/500错误
    • 查看后端日志与接口文档，确认权限与资源存在性
  • 网络错误提示
    • 检查Vite代理配置与后端服务连通性
  • 批量参数传递异常
    • 确认后端期望的重复参数名与数值类型

章节来源

结论

该前端API层通过统一的请求封装与拦截器实现了鉴权、错误处理与跨域代理，配合Pinia与路由守卫形成清晰的认证与状态管理闭环。业务接口按模块化组织，查询参数传递规范，具备良好的扩展性。建议在后续迭代中补充文件上传/下载与Mock能力，并完善批量参数与分页的通用工具方法，以进一步提升开发效率与用户体验。

附录

  • 常用接口一览（示例）
    • 认证：登录、获取当前用户、注册
    • 基础数据：科室、员工、指标、模板
    • 考核与工资：创建、提交、审核、生成、确认
    • 统计：部门统计、周期统计、趋势、排名、仪表盘、预警
  • 开发与部署
    • 开发：npm run dev（Vite启动+代理）
    • 构建：npm run build（输出dist）
    • 预览：npm run preview

章节来源