@ynmobile/touch-trace-plugin

全链路日志追踪能力独立插件包 —— Vue2 工程一行 Vue.use 接入,自动为所有命中后端的请求注入 X-Trace-Id / X-Span-Id / X-Menu-Id / X-Client-Type。

简介

从 chbn-web 工程级 trace 注入改造(a7edaf7c0)沉淀而来,封装为独立、自包含、零运行时依赖的 Vue2 插件:

• patch 全局 XMLHttpRequest / fetch,在底层注入追踪头,不替代工程的请求层 / 加密 / 签名;
• trace 状态完全自包含(模块级单例 + sessionStorage),零 Vuex / router / utils / TouchVue 依赖;
• 显式 opt-in —— 主动 Vue.use 才生效,不存在"升级被自动注入"的行为变更;
• 覆盖业务 axios / weblog axios / TouchUI 组件请求 / 原生 fetch 四类通道;
• 任何 trace 侧异常都裸发原请求,永不阻断业务。

安装

npm i @ynmobile/touch-trace-plugin

vue 为 peerDependencies(^2.6.0,覆盖 2.6 / 2.7)。npm 7+ 会自动安装;版本冲突时可用 --legacy-peer-deps 兜底。

快速上手(一行)

import Vue from 'vue'
import TouchTrace from '@ynmobile/touch-trace-plugin'

Vue.use(TouchTrace, {
  // 同源部署可省略 backendBaseURL,会自动命中 location.origin
  backendBaseURL: process.env.VUE_APP_BASE_API
})

完成。此后所有命中后端的请求会自动带上 X-Trace-Id / X-Span-Id / X-Menu-Id / X-Client-Type。

trace patch 在 new Vue() 之前完成,早于任何业务首请求;send / fetch 内还有 ensureReady() 兜底。

配置(opts 顶层)

| 选项 | 类型 | 默认 | 说明 | |---|---|---|---| | enabled | boolean | true | false 关闭整包 | | backendBaseURL | string \| string[] | — | 同源可不传;跨域 / 多后端显式传 | | includeOrigins | string[] | [] | 额外白名单 origin | | excludePatterns | RegExp[] | [] | 追加到默认排除规则 | | headerNames | {traceId?,spanId?,menuId?,clientType?} | X-Trace-Id 等 | 自定义头名 | | clientType | string | 'web' | 静态 WEB 来源标识;显式传 '' 则不注入该头 | | inbound | {windowKey?,queryKey?} | __traceId / traceId | 入口来源 key | | resolveMenuId | () => string | 见下 | 自定义 menuId 解析 |

默认排除(excludePatterns 追加于此):localhost / 0.0.0.0 / 127.0.0.1(本地设备 SDK)、静态资源(js/css/图片/字体)、data: / blob:、dev 热更新 / WebSocket。

后端地址发现

注入的 origin 集合 = location.origin(同源) ∪ backendBaseURL 解析出的 origin ∪ includeOrigins。请求 URL 经此白名单命中后才会注入,且不被排除规则匹配。

三档关闭开关(优先级高 → 低)

| 档位 | 方式 | 用途 | |---|---|---| | 安装时 | Vue.use(TouchTrace, { enabled: false }) | 整工程主动不要 | | HTML | <meta name="touch-trace" content="off"> | 整站关,不碰代码 | | 运行时 | window.__TOUCH_TRACE_DISABLE__ = true(加载前设) | 生产事故逃生阀 |

入口优先级链(首屏 / 刷新)

window[windowKey] → ?queryKey= → sessionStorage → 新建 uuid。新增 ?traceId= URL 透传档,支持跨系统串联。

路由模式

history / hash 双支持。顶层路由段切换 → rotate 生成新 traceId;同段子路由跳转 → 不变。

自定义 menuId resolver

依赖 route.meta.menuId 的工程:

import { createRouterMenuIdResolver } from '@ynmobile/touch-trace-plugin'

const router = new Router({ routes })              // ① router 先创建
Vue.use(TouchTrace, {
  resolveMenuId: createRouterMenuIdResolver(router) // ② 再传入
})
new Vue({ router }).$mount('#app')

默认 resolver:?MENU_ID 优先 → URL / hash 首段兜底。

X-Client-Type:WEB 来源标识

每个命中后端的注入请求还会额外携带 X-Client-Type: web,供后端区分请求来自 WEB 端 还是 APP 原生/转发。

| 选项 | 默认 | 说明 | |---|---|---| | clientType | 'web' | 来源标识值;显式传 '' 则不注入该头 | | headerNames.clientType | 'X-Client-Type' | 头名(并入 headerNames) |

跨团队契约:后端据此区分的前提是 APP 原生/转发请求不携带 X-Client-Type: web(由 APP 侧保证,本插件不强制)。该值为静态自标识,不做宿主探测,不参与 traceId 的入站 / 落盘 / 轮换。

命名导出(供精细控制 / 非 Vue 入口 / SSR)

import {
  installTrace, uninstallTrace, status,
  TraceContext, createRouterMenuIdResolver
} from '@ynmobile/touch-trace-plugin'

• installTrace(opts) / uninstallTrace():手动装配 / 还原(适合 SSR 守卫后精确控制时机);
• status():返回 { enabled, patched, mode, traceId, spanId, menuId, clientType, lastDecision },用于自检与排障;
• TraceContext:状态机单例(只读访问器为主);
• createRouterMenuIdResolver(router):见上。

UMD / CDN

<script src="https://unpkg.com/@ynmobile/touch-trace-plugin"></script>
<script>
  // UMD 全局 TouchTrace 为 named 导出集合,默认导出在 .default
  Vue.use(TouchTrace.default, { backendBaseURL: 'https://api.example.com' })
</script>

推荐 npm 接入;UMD 仅为产物完备性保留(TD-2 决策:首版以 npm 接入为主)。

覆盖范围与已知限制

覆盖:业务 axios(XHR 底层)、weblog axios、TouchUI 组件请求、原生 fetch。

不覆盖(声明为已知限制):

• navigator.sendBeacon;
• Web Worker / Service Worker 内的 fetch / XHR;
• 跨 iframe 请求、WebSocket(本地设备 SDK 多走 WS,不在 HTTP patch 范围);
• 微前端多实例同页共存、依赖树多版本共存 —— 检测到重复 patch 会告警(status.enabled 可能不生效)。

开发

npm install      # 装依赖
npm test         # lint + karma(真浏览器 + 覆盖率门禁 ≥80%)
npm run build    # rollup 产出 ESM + CJS + UMD 到 dist/

测试栈:仓库内自建 karma + mocha + chai + sinon + karma-coverage + karma-webpack + ChromeHeadless。无系统 Chrome 的环境(WSL2 / CI)会自动定位 puppeteer 下载的 chrome for testing。

License

MIT