从零打造专业级前端 SDK (一)：架构与工程化

前言：在前端开发中，我们经常需要接入各种第三方 SDK（如统计埋点、即时通讯、地图服务）。但你是否想过，如果让你从零开发一个 SDK，该如何设计？本文将带你一步步打造一个生产可用的前端埋点 SDK。

1. 为什么我们需要自研 SDK？

市面上已有 Google Analytics、Mixpanel 等成熟方案，为什么还要造轮子？

数据安全：敏感数据必须私有化部署。
定制需求：需要采集特定的业务数据（如停车场车位状态、设备温度）。
极致轻量：第三方 SDK 往往功能臃肿，我们只需要核心功能。

2. 工程化基石：TypeScript + Vite

工欲善其事，必先利其器。对于 SDK 开发，我的技术选型是：

语言 : TypeScript (类型安全是 SDK 的生命线)。
构建 : Vite (Library Mode) (基于 Rollup，打包体积小，配置简单)。

2.1 初始化项目

bash 复制代码

npm create vite@latest parking-tracker-sdk -- --template vanilla-ts
npm install uuid @types/uuid
npm install -D vite-plugin-dts # 用于生成 .d.ts 类型文件

2.2 Vite 配置 (Library Mode)

我们需要 SDK 能同时支持 import (ESM) 和 <script> (UMD) 引入。

vite.config.ts:

typescript 复制代码

import { defineConfig } from 'vite';
import { resolve } from 'path';
import dts from 'vite-plugin-dts';

export default defineConfig({
  plugins: [dts({ include: ['src'] })], // 自动生成类型声明
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      name: 'ParkingTracker', // UMD 全局变量名
      fileName: (format) => `index.${format}.js`
    }
  }
});

3. 核心设计模式

SDK 的代码质量直接决定了接入者的体验。这里我们使用了两个经典的设计模式。

3.1 单例模式 (Singleton) ------ 唯一的指挥官

场景：无论用户调用多少次 init()，或者在多少个组件里引入 SDK，我们都希望全局只有一个 Tracker 实例，保证配置和状态的唯一性。

实现 (src/core/Tracker.ts):

typescript 复制代码

export class Tracker {
  private static instance: Tracker; // 静态属性存储实例

  // 1. 私有构造函数：禁止外部直接 new Tracker()
  private constructor() {
    this.config = { ... };
  }

  // 2. 静态方法获取实例
  public static getInstance(): Tracker {
    if (!Tracker.instance) {
      Tracker.instance = new Tracker();
    }
    return Tracker.instance;
  }
}

3.2 外观模式 (Facade) ------ 极简的门面

场景：Tracker.getInstance().track(...) 这种写法太啰嗦了。用户只想要 Tracker.track(...)。

实现 (src/index.ts):

typescript 复制代码

import { Tracker } from './core/Tracker';

// 导出一个对象，代理核心方法
export default {
  init: (config: TrackerConfig) => Tracker.getInstance().init(config),
  track: (eventName: string, props?: any) => Tracker.getInstance().track(eventName, props)
};

这样用户就可以愉快地使用了：

javascript 复制代码

import Tracker from 'parking-tracker-sdk';

Tracker.init({ appId: '123' });
Tracker.track('login');

4. 阶段总结

到目前为止，我们已经完成了一个 SDK 的骨架：

类型安全：完整的 TS 支持。
构建产物：支持 ESM/CJS/UMD。
架构设计：单例保证状态唯一，外观提供极致体验。

但现在的 SDK 还是个"哑巴"，只能在控制台打印日志。 下一篇 ，我们将为它注入灵魂------实现网络发送能力 ，并探讨如何使用策略模式来应对复杂的浏览器环境。

本文代码已开源，欢迎 Star ⭐️