状态管理与接口调用规范

状态管理与接口调用规范

技术栈

• Vuex 3（Vue2 版，模块化 store）。
• axios 0.15（注意是较旧版本，拦截器/取消令牌 API 用对应版本写法，不要用 1.x 的 AbortController 写法）。
• 接口基础前缀、token、错误处理统一在封装层，不要在业务组件里裸调 axios。

接口封装（必须走封装层）

• 所有请求通过项目封装的 http 实例（如 @/api/http 或 @/utils/request，以既有为准）发送，不要在组件里直接 import axios from 'axios' 调用。
• 按业务模块组织 API 文件：src/api/<模块>.js，导出命名函数；组件 import 调用。

// src/api/appoint.js
import request from '@/utils/request'

// Do：每个接口一个命名函数，明确入参出参
export function getRegList(params) {
  return request({ url: '/appoint/reg/list', method: 'get', params })
}

// Don't：组件里裸调 + 拼字符串
// axios.get('/appoint/reg/list?id=' + this.id)  ❌

请求/响应处理

• 统一拦截器处理：baseURL、token 注入、错误码统一处理、loading、超时。
• 错误处理在拦截器统一兜底；业务层只处理需要特殊提示的场景，不要每个调用都重复 try/catch 弹错。
• 返回结构遵循后端统一返回体（code/message/data），拦截器判断 code 成功才 resolve，否则 reject/统一提示。
• 分页接口统一参数与返回字段命名（如 page/limit、list/totalCount），与后端约定一致。

数据安全

• token、用户信息存 vuex + 持久化（localStorage/cookie，按既有）。
• 不要在 url query 里传递 token 或敏感参数（会被日志记录）。
• 日志/控制台不要打印身份证、医保卡完整号（见 security-anti-leak.md）。

Vuex 使用

模块化

• store 按模块拆分 modules（user、app、<业务模块>），开启 namespaced: true。
• 组件用 mapState/mapActions/mapMutations（带命名空间），避免 $store.state.xxx.xxx 散落。

何时用 vuex

• 跨组件/跨路由共享的状态（登录信息、机构、权限、全局字典）放 vuex。
• 组件私有状态用 data，不要什么都塞 vuex（难以维护）。

修改方式

• 状态变更只能通过 mutations（同步）/actions（异步），不要在组件里直接 $store.state.x = y。

异步与并发

• 多个无依赖请求用 Promise.all 并行，避免串行 await 拖慢页面。
• 列表查询带 loading 态；切换查询条件注意取消上一次未完成请求（axios 0.15 用 CancelToken）。
• 节流/防抖搜索输入。

错误兜底

• 接口失败时给用户可见的反馈（message/空状态占位），不要让页面白屏或停在 loading。
• 关键操作（提交、删除、结算）失败后保留用户已填数据，不要清空。