@guodun/vue-shared

Vue 3 跨端（PC / H5 / uni-app 小程序）共用能力包。第一期：请求错误时统一携带 traceId（响应体优先，其次响应头 trace-id），由业务自行接入 message / notification / Toast / uni.showToast。

• 不耦合任何 UI 库；通过 notify(err: TraceError) 注入。
• 业务成功判定为白名单模式：successCode（默认 0），非名单即错误；ignoreCodes 可排除不弹窗的业务码（如 401 由路由静默处理）。
• HTTP 层失败走 handleError：msg 取自响应体字段（默认 msg），无则用 Error.message（如网络错误），最后用 defaultMsg。
• 少侵入：推荐使用 createTraceErrorHandler，仅在已有 axios / alova 拦截器各加一行调用；亦可 setupAxiosTrace / createAlovaTraceResponded 一行糖。

安装

在各端项目中（已安装 vue@^3.5），按需安装请求库。

pnpm add @guodun/vue-shared axios
# 或小程序 alova
pnpm add @guodun/vue-shared alova @alova/adapter-uniapp

axios / alova 为 optional peer：未使用的端不会打进业务包，本包构建时亦 external 掉二者。

TraceError

| 字段 | 含义 | |------|------| | msg | 展示文案 | | traceId | body[traceIdKey] 或头部 traceIdHeader，无则空串 | | code | 业务码（HTTP 分支可能取自 body） | | status | HTTP 状态码（*Error / 适配器返回值可解析到时） | | source | 'business'：HTTP 成功但业务失败；'http'：传输层失败 | | raw | 原始 AxiosResponse / 错误对象 / alova 透传 |

PC：axios + ant-design-vue notification

import axios from 'axios'
import { notification } from 'ant-design-vue'
import { createTraceErrorHandler } from '@guodun/vue-shared/request'

const trace = createTraceErrorHandler({
  notify: (e) =>
    notification.error({
      message: e.msg,
      description: e.traceId ? `traceId: ${e.traceId}` : undefined,
    }),
  successCode: 0,
  ignoreCodes: [401],
})

axios.interceptors.response.use(
  (res) => {
    trace.handleSuccess(res)
    return res
  },
  (err) => {
    trace.handleError(err)
    return Promise.reject(err)
  },
)

或一行挂载：

import { setupAxiosTrace } from '@guodun/vue-shared/request/axios'
setupAxiosTrace(axios, { notify, successCode: 0, ignoreCodes: [401] })

H5：axios + Vant Toast（示例）

import axios from 'axios'
import { showToast } from 'vant'
import { createTraceErrorHandler } from '@guodun/vue-shared/request'

const trace = createTraceErrorHandler({
  notify: (e) =>
    showToast({
      type: 'fail',
      message: e.traceId ? `${e.msg}（traceId: ${e.traceId}）` : e.msg,
      duration: 3000,
    }),
  successCode: 0,
})
axios.interceptors.response.use((r) => (trace.handleSuccess(r), r), (err) => (trace.handleError(err), Promise.reject(err)))

uni-app：alova + @alova/adapter-uniapp

适配器返回值中的 header / headers、statusCode / status 已由内部 normalizeResponseLike 兼容。若全局 responded.onSuccess 仅收到解构后的业务 data 而无 headers，则 traceId 只能来自 body——请尽量透传原始响应或通过网关保证 body 中带 traceId。

import { createAlova } from 'alova'
import VueHook from 'alova/vue'
import AdapterUniapp from '@alova/adapter-uniapp'
import { createAlovaTraceResponded } from '@guodun/vue-shared/request/alova'

const alovaInst = createAlova({
  ...AdapterUniapp(),
  statesHook: VueHook,
  responded: createAlovaTraceResponded({
    notify: (e) => {
      uni.showToast({
        title: e.traceId ? `${e.msg}\nid:${e.traceId.slice(0, 12)}…` : e.msg,
        icon: 'none',
        duration: 3000,
      })
    },
    successCode: 0,
  }),
})

配置项摘要

| 选项 | 默认 | 说明 | |------|------|------| | notify | 必填 | (err: TraceError) => void | | successCode | 0 | 成功业务码或数组（如 [0, 200]） | | ignoreCodes | [] | 不触发 notify 的业务码 | | codeKey / msgKey / traceIdKey | code / msg / traceId | 后端字段别名 | | traceIdHeader | trace-id | 回退读取响应头时的名字（大小写不敏感） | | defaultMsg | 请求异常，请稍后重试 | 无 msg 时兜底 | | shouldNotify | 不传 | 若传入则完全由其决定是否弹出（取代内置 success/ignore 判定） | | dedupe | { window:1000, by:'msg' } | 短时间去重；false 关闭；by 可选 'msg' / 'traceId' / 'msg+code' |

导出子路径（tree-shaking）

| 导入路径 | 用途 | |-----------|------| | @guodun/vue-shared | 主入口，聚合常用 API | | @guodun/vue-shared/request | createTraceErrorHandler、抽取与工具函数 | | @guodun/vue-shared/request/axios | createAxiosTraceInterceptor / setupAxiosTrace | | @guodun/vue-shared/request/alova | createAlovaTraceResponded |

开发与构建（monorepo）

pnpm --filter @guodun/vue-shared run build

预留

src/composables/ 为空目录占位，后续可补充 useXxx composable。