工具分享:实现前端埋点的自动化管理

阿强酱_9862

阿强酱_9862

2022-12-07

2593人浏览

转载

埋点一直是 H5 项目中的重要一环,埋点数据更是后期改善业务和技术优化的重要基础。【推荐学习:web前端、编程教学】

在日常的工作中,经常会有产品或者业务的同学来问,“这个项目现在有哪些埋点?”,“这个埋点用在哪些地方?”像这样的问题基本上都是问一次查一次代码,效率很低。

这也许跟埋点本身的性质有关系。埋点属于相对独立的功能,随着迭代的进行,开发者很难记住埋点的用途。开发者出于自测验证的需要,也得对项目中的埋点数据加以整理。因此结合当前的场景,可以实现一个工具:通过对代码进行扫描,分析埋点相关的代码,并对之加以处理,转化成特定的数据,供后续在其他的管理平台中使用。

实现思路

这个工具大致可以分成三个部分,JSDoc 提取埋点、路由依赖分析和 ESLint 插件。

  • JSDoc 是根据 JavaScript 中的注释信息,生成 API 文档的一个工具。结合 JSDoc 的这一个特性,这个埋点工具把 JSDoc 作为核心部分,用于输出代码中的埋点数据。
  • Webpack 插件作为辅助,为 JSDoc 提供路由信息。
  • ESLint 插件则作为最后的检验,确保文件中的埋点代码都有对应的 JSDoc 注释。

自定义 JSDoc 标记埋点

我们知道,JSDoc 可以根据代码中的注释输出一份文档。首先我们自定义一个 JSDoc 的 tag 来标注这是一个埋点的注释,这样后续处理时可以过滤掉其他注释的干扰。结合具体项目中使用的代码可以画出这样一个流程图:

下面是具体的代码实现的过程。

编写 JSDoc 插件,自定义一个 tag:

// jsdoc.plugin.js
// 自定义一个 @log,含有 @log 才是埋点的注释
exports.defineTags = function (dictionary) {
  dictionary.defineTag('log', {
    canHaveName: true,
    onTagged: function (doclet, tag) {
      doclet.meta.log = tag.text;
    },
  });
};

解析 .ts 和 .vue 文件。

// jsdoc.plugin.js
exports.handlers = {
  beforeParse: function (e) {
    // 对文件预处理
    if (/.vue/.test(e.filename)) {
      // 解析 vue 文件
      const component = compiler.parseComponent(e.source);
      // 获取 vue 文件的 script 代码
      const ast = parse.parse(component.script.content, {
        // ...
      });
    }

    if (/.ts/.test(e.filename)) {
      // ts 转 js
    }
  },
};

自定义 JSDoc 模版。

// publish.js
exports.publish = function (taffyData, opts, tutorials) {
  // ...
  data().each(function (doclet) {
    // 有 log 这个 tag 的才是埋点注释
    if (doclet.meta && doclet.meta.log) {
      doclet.tags?.forEach((item) => {
        // 获取对应的路由地址
      });

      // 拿到埋点数据
      logData.push({});
    }
  });

  // 输出 md 文档
  fs.writeFileSync(outpath, mdContent, 'utf8');
};

到这里,已经可以完整地输出代码中的所有埋点了。此时再来看下目前这个工具的能力:

  • 自动提取埋点信息,生成埋点文档:✅
  • 自动给埋点注释添加自定义 tag(@log):❌
  • 自动给埋点注释添加上报的埋点信息:❌
  • 自动给埋点注释添加路由信息:❌
  • 自动给埋点注释添加埋点描述信息:❌
  • 自动提示没有注释的埋点代码:❌

通过上面的梳理我们可以看出:

  • 需要手动给每个埋点加上注释
  • 需要手动去查每个埋点所对应的路由
  • 如果忘了给埋点加注释怎么办?

做这个工具的初衷,就是为省去一些重复繁琐的工作,如果为了能自动从代码中输入一份文档而增加了其他一些工作量,这未免有点得不偿失。通过对这些问题的分析,可以得出以下的解决方案:

  • 需要手动给每个埋点加上注释 -> 自动填充代码 -> ESLint fix 功能 / VSCode 插件
  • 需要手动去查每个埋点所对应的路由 -> 自动找到组件所对应的路由 -> Webpack 依赖分析
  • 如果忘了给埋点加注释怎么办?-> 忘写注释有提示 -> ESLint 插件

到这一步解决问题的方法就已经变得明朗了。接下来让看一下 webpack 插件与 ESLint 插件的实现过程。

路由依赖分析

webpack 本身自带依赖分析,轻松就能拿到组件间的父子关系。

HISUI 前端框架开发指南(IRIS版)
HISUI 前端框架开发指南(IRIS版)

HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库,专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。 涵盖 40 个组件的官方文档参考,支持声明式与编程式两种初始化方式,提供 $cm/$m 数据访问方法。

下载
compiler.hooks.normalModuleFactory.tap('routeAnalysePlugin', (nmf) => {
  nmf.hooks.afterResolve.tapAsync('routeAnalysePlugin', (result, callback) => {
    const { resourceResolveData } = result;
    // 子组件
    const path = resourceResolveData.path;

    // 父组件
    const fatherPath = resourceResolveData.context.issuer;

    // 只获取 vue 文件的依赖关系
    if (/.vue/.test(path) && /.vue/.test(fatherPath)) {
      // 将组件间的父子关系存到变量中
    }
  });
});

把组件之间的依赖关系拼成我们想要的数据格式

[
  {
    "path": "src/views/register-v2/index.vue",
    "deps": [
      {
        "path": "src/components/landing-banner/index.vue",
        "deps": []
      }
    ]
  }
  // ...
]

组件之间的依赖关系有了,接下来就是找到组件和路由的对应关系,这里我们用 AST 来解析路由文件,获取路由和组件的对应关系。

// 遍历路由文件
for (let i = 0; i  {
        // 组件
        if (item.key.name === 'component') {
        }

        // 路由地址
        if (item.key.name === 'path') {
        }
      });
    },
  });
}

同样地,把组件与路由的映射关系拼成合适的数据格式。

{
  "src/views/register-v3/index.vue": "/register"
  // ...
}

再将路由的映射关系和组件间的依赖关系整合到一起,得出每个组件与路由的对应关系。

{
  "src/components/landing-banner/index.vue": [
    "/register_v2",
    "/register"
    //...
  ]
  // ...
}

因为使用 AST 遍历的方式来解析路由文件,目前支持的解析的路由文件写法有以下四种,基本上满足了当前的场景:

const page1 = (resolve) => {
  require.ensure(
    [],
    () => {
      resolve(require('page1.vue'));
    },
    'page1',
  );
};

const page2 = () =>
  import(
    /* webpackChunkName: "page2" */
    'page2.vue'
  );

export default [
  { path: '/page1', component: page1 },
  { path: '/page2', component: page2 },
  {
    path: '/page3',
    component: (resolve) => {
      require.ensure(
        [],
        () => {
          resolve(require('page3.vue'));
        },
        'page3',
      );
    },
  },

  {
    path: '/page4',
    component: () =>
      import(
        /* webpackChunkName: "page4" */
        'page4.vue'
      ),
  },
];

再得到了上面的对应关系之后,可以把埋点数据放到传到埋点管理平台上,从而实现一键查询:

编写 ESLint 插件

先来看看代码中埋点上报的三种方式:

// 神策 sdk
sensors.track('xxx', {});

// 挂载到 Vue 实例中
this.$sa.track('xxx', {});

// 装饰器
@SensorTrack('xxx', {})

观察上面三种方式,可以知道埋点上报是通过 track 函数和 SensorTrack 函数,所以我们的 ESLint 插件对这两个函数进行校验。

function create(context) {
  // 调用 track 函数的对象
  const checkList = ['sensor', 'sensors', '$sa', 'sa'];

  return {
    Literal: function (node) {
      // ...
      // 调用埋点函数而缺少注释时
      if (
        isNoComment &&
        ((isTrack && isSensor) || (is$Track && isThisExpression))
      ) {
        context.report({
          node,
          messageId: 'missingComment',
          fix: function (fixer) {
            // 自动修复
          },
        });
      }

      // 使用修饰器但没有注释时
      if (
        callee.name === 'SensorTrack' &&
        sourceCode.getCommentsBefore(node).length === 0
      ) {
        context.report({
          node,
          messageId: 'missingComment',
          fix: function (fixer) {
            // 自动修复
          },
        });
      }
    },
  };
}

看下完成后的效果:

效果对比

我们再来对比下优化前后的区别:


优化前 优化后
自动提取埋点信息,生成埋点文档 ✅ ✅
自动给埋点注释添加自定义 tag(@log) ❌ ✅
自动给埋点注释添加上报的埋点信息 ❌ ✅
自动给埋点注释添加路由信息 ❌ ✅
自动给埋点注释添加埋点描述信息 ❌ ❌
自动提示没有注释的埋点代码 ❌ ✅

优化之后除了整个流程基本都由工具自动完成,剩下一个埋点描述信息。因为埋点的描述信息只是为了让我们更好地理解这个埋点,本身并不在上报的代码中,所以工具没有办法自动生成,但是我们可以直接在产品提供的埋点文档中拷贝过来完成这一步。

总结

在项目中接入这个工具之后,可以快速地知道项目的埋点有哪些以及各个埋点所在的页面,也方便我们对埋点的梳理,同时利用导出的埋点数据开发后台应用,有效地提升了开发者效率。

这个工具的实现是在 JSDoc、webpack 和 ESLint 插件的加持下水到渠成的,说是水到渠成是因为一开始的想法只是做到第一步,先有个一键查询功能和能够输出一份文档用着先。但是第一版出来后发现要手动去处理这些埋点注释还是比较繁琐,恰巧平常开发中常见的 webpack 插件和 ESLint 插件可以很好地解决这些问题,于是便有路由依赖分析和 ESLint 插件。像是《牧羊少年奇幻之旅》中所说的,“如果你下定决心要做一件事情,整个宇宙都会合力帮助你。”

【推荐学习:web前端开发、编程基础视频教程】

前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!

相关文章

PHP速学视频免费教程(入门到精通)
PHP速学视频免费教程(入门到精通)

PHP怎么学习?PHP怎么入门?PHP在哪学?PHP怎么学才快?不用担心,这里为大家提供了PHP速学教程(入门到精通),有需要的小伙伴保存下载就能学习啦!

下载

相关标签:

前端 vue.js

本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

相关专题

更多
Navicat创建数据库教程
Navicat创建数据库教程

本专题整理Navicat创建数据库相关教程,介绍新建前的准备、基础设置和创建后的检查方法。内容兼顾入门学习及实际使用需求,帮助用户了解不同数据库类型下的操作差异,为后续建表、保存数据和日常管理提供参考。

2026.11.20

0

7

Navicat入门教程大全
Navicat入门教程大全

本专题整理Navicat入门教程,从认识软件界面到开展数据库操作,介绍初次使用需要了解的知识和方法。内容兼顾连接配置、数据管理及日常使用中的疑问,方便用户按学习进度查阅,为后续实践和独立操作打好基础。

2026.11.20

0

17

Navicat数据库连接配置指南
Navicat数据库连接配置指南

从确认数据库信息到建立可用连接,本专题串联Navicat连接数据库的相关知识和操作方法。既有初次配置时需要了解的基础内容,也有连接后的检查思路,方便用户按实际需求查阅教程,逐步熟悉数据库连接的设置流程。

2026.11.20

0

10

PHP8.6数组与数据处理教程
PHP8.6数组与数据处理教程

本专题汇总PHP8.6数组与数据处理教程,涵盖CSV读取和导出、引用遍历删除、array_filter回调模式、配置键名冲突、pathinfo文件名校验、GMP大整数进制转换及UTF-8正则筛选,说明升级兼容变化、输入范围和失败处理方法。

2026.11.20

0

8

PHP8.6升级迁移教程
PHP8.6升级迁移教程

本专题汇总PHP8.6升级迁移与弃用接口改造教程,涵盖反射调用、对象属性赋值、标识符更名、构造函数与__debugInfo调整,以及插件类名检查、常量导出、ArrayIterator排序、SPL和DTO查询参数转换,帮助梳理弃用提示并完成代码兼容改造。

2026.11.20

0

10

PHP8.6安装配置与FPM运维教程
PHP8.6安装配置与FPM运维教程

本专题汇总PHP8.6正式版安装部署与FPM运维教程,涵盖Linux并存安装、独立ini配置、扩展重新编译、Nginx切换与回滚、FPM状态监控和慢日志排查,以及环境变量、请求超时、OPcache刷新和预加载配置。

2026.11.20

0

10

Nginx CVE-2026-123007排查与防护指南
Nginx CVE-2026-123007排查与防护指南

Nginx HTTP/2漏洞该怎么修复?本专题围绕CVE-2026-123007,介绍安全版本升级、模块兼容检查和配置恢复方法,以及日志排查、权限设置等后续加固操作,方便你按实际部署情况查找对应教程。

2026.11.20

20

8

GoFrame框架Web开发与路由中间件
GoFrame框架Web开发与路由中间件

本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。

2026.11.17

60

15

GoFrame框架安装与gf命令行工具
GoFrame框架安装与gf命令行工具

本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.17

80

15

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程