sobey-monitor-sdk 1.0.1 → 1.0.3

package/README.md

@@ -44,6 +44,68 @@ monitor.init({
 ### `monitor.flush()`
 立即上报缓冲区中的数据。
 
+## 框架集成
+
+### Vue 3
+
+使用 `VueMonitorPlugin` 插件，可以捕获 Vue 组件内的渲染错误：
+
+```typescript
+import { createApp } from 'vue';
+import App from './App.vue';
+import { VueMonitorPlugin } from 'sobey-monitor-sdk';
+
+const app = createApp(App);
+
+app.use(VueMonitorPlugin, {
+  appId: 'your-app-id',
+  dsn: 'http://localhost:3000/api/report',
+  debug: true,
+});
+
+app.mount('#app');
+```
+
+### React
+
+使用 `createReactErrorBoundary` 创建错误边界组件，包裹根组件以捕获渲染错误：
+
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import App from './App';
+import { createReactErrorBoundary } from 'sobey-monitor-sdk';
+
+// 创建错误边界组件
+const ErrorBoundary = createReactErrorBoundary(React, {
+  appId: 'your-app-id',
+  dsn: 'http://localhost:3000/api/report',
+  debug: true,
+});
+
+ReactDOM.render(
+  <ErrorBoundary fallback={<h1>页面出错了</h1>}>
+    <App />
+  </ErrorBoundary>,
+  document.getElementById('root')
+);
+```
+
+**注意**：框架集成会自动初始化 SDK，无需再手动调用 `monitor.init()`。
+
+## 配置项
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `appId` | string | 必填 | 应用唯一标识 |
+| `dsn` | string | 必填 | 数据上报地址 |
+| `debug` | boolean | false | 调试模式 |
+| `sampling.error` | number | 1 | 错误采样率 (0-1) |
+| `sampling.performance` | number | 1 | 性能采样率 (0-1) |
+| `sampling.behavior` | number | 1 | 行为采样率 (0-1) |
+| `report.maxBufferSize` | number | 10 | 缓冲区最大数量 |
+| `report.flushInterval` | number | 5000 | 上报间隔 (ms) |
+
 ## 构建
 
 ```bash

package/dist/frameworks/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 框架集成模块
+ * 导出 Vue 和 React 的集成组件
+ */
+export { VueMonitorPlugin } from './vue';
+export { createReactErrorBoundary, createUseMonitorError } from './react';
+export type { ErrorBoundaryProps, ErrorBoundaryState } from './react';

package/dist/frameworks/react.d.ts

@@ -0,0 +1,74 @@
+import type { MonitorConfig } from '../types';
+/**
+ * React ErrorBoundary 组件 Props
+ */
+export interface ErrorBoundaryProps {
+    /** 发生错误时显示的降级 UI */
+    fallback?: any;
+    /** 错误回调 */
+    onError?: (error: Error, errorInfo: any) => void;
+    /** 子组件 */
+    children?: any;
+}
+/**
+ * React ErrorBoundary 组件 State
+ */
+export interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * 创建 React 错误边界组件
+ *
+ * @param React - React 库引用
+ * @param config - SDK 配置
+ * @returns ErrorBoundary 组件类
+ *
+ * @example
+ * ```tsx
+ * import React from 'react';
+ * import ReactDOM from 'react-dom';
+ * import { createReactErrorBoundary } from 'sobey-monitor-sdk';
+ *
+ * const ErrorBoundary = createReactErrorBoundary(React, {
+ *   appId: 'your-app-id',
+ *   dsn: 'http://your-server/api/report',
+ * });
+ *
+ * ReactDOM.render(
+ *   <ErrorBoundary fallback={<h1>Something went wrong</h1>}>
+ *     <App />
+ *   </ErrorBoundary>,
+ *   document.getElementById('root')
+ * );
+ * ```
+ */
+export declare function createReactErrorBoundary(React: any, config: MonitorConfig): any;
+/**
+ * React Hook: 用于手动上报错误
+ *
+ * @example
+ * ```tsx
+ * import { useMonitorError } from 'sobey-monitor-sdk';
+ *
+ * function MyComponent() {
+ *   const reportError = useMonitorError();
+ *
+ *   const handleClick = async () => {
+ *     try {
+ *       await riskyOperation();
+ *     } catch (error) {
+ *       reportError(error, { action: 'riskyOperation' });
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleClick}>Click</button>;
+ * }
+ * ```
+ */
+export declare function createUseMonitorError(React: any): () => any;
+declare const _default: {
+    createReactErrorBoundary: typeof createReactErrorBoundary;
+    createUseMonitorError: typeof createUseMonitorError;
+};
+export default _default;

package/dist/frameworks/vue.d.ts

@@ -0,0 +1,21 @@
+import type { MonitorConfig } from '../types';
+/**
+ * Vue 3 错误监控插件
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { VueMonitorPlugin } from 'sobey-monitor-sdk';
+ *
+ * const app = createApp(App);
+ * app.use(VueMonitorPlugin, {
+ *   appId: 'your-app-id',
+ *   dsn: 'http://your-server/api/report',
+ * });
+ * app.mount('#app');
+ * ```
+ */
+export declare const VueMonitorPlugin: {
+    install(app: any, options: MonitorConfig): void;
+};
+export default VueMonitorPlugin;

package/dist/index.cjs.js

@@ -231,12 +231,6 @@ function getPageTitle() {
 function supportsSendBeacon() {
     return typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function';
 }
-/**
- * 判断页面是否即将卸载
- */
-function isPageHidden() {
-    return document.visibilityState === 'hidden';
-}
 
 /**
  * 数据发送器
@@ -277,32 +271,39 @@ class Sender {
     }
     /**
      * 执行发送
+     * 策略：优先使用 sendBeacon（更可靠），不支持或失败时降级为 fetch
      */
     doSend(data) {
         const cfg = config.get();
         const dsn = cfg.dsn;
         const payload = JSON.stringify(data);
-        // 页面卸载时优先使用 sendBeacon
-        if (isPageHidden() && supportsSendBeacon()) {
-            this.sendByBeacon(dsn, payload);
-            return;
+        // 优先使用 sendBeacon（更可靠、异步、不阻塞页面）
+        if (supportsSendBeacon()) {
+            const success = this.sendByBeacon(dsn, payload);
+            if (success) {
+                return;
+            }
+            // sendBeacon 失败，降级到 fetch
         }
-        // 正常情况使用 fetch
+        // 不支持 sendBeacon 或 sendBeacon 失败时，使用 fetch
         this.sendByFetch(dsn, payload);
     }
     /**
      * 使用 sendBeacon 发送
+     * 返回 true 表示成功加入队列，false 表示失败需要降级
      */
     sendByBeacon(url, payload) {
         try {
-            return navigator.sendBeacon(url, payload);
+            const success = navigator.sendBeacon(url, payload);
+            if (!success && config.get().debug) {
+                console.warn('[Monitor] sendBeacon returned false, falling back to fetch');
+            }
+            return success;
         }
         catch (e) {
             if (config.get().debug) {
                 console.error('[Monitor] sendBeacon failed:', e);
             }
-            // 降级到 fetch
-            this.sendByFetch(url, payload);
             return false;
         }
     }
@@ -618,17 +619,36 @@ function installHttpErrorHandler() {
 /**
  * 拦截 XMLHttpRequest
  */
+/**
+ * 检查是否是 SDK 自身的请求
+ */
+function isSdkRequest(url) {
+    const cfg = config.get();
+    if (!cfg.dsn)
+        return false;
+    return url.includes(cfg.dsn);
+}
 function interceptXHR() {
     XMLHttpRequest.prototype.open = function (method, url, async = true, username, password) {
+        const urlStr = url.toString();
+        // 排除 SDK 自身的上报请求
+        if (isSdkRequest(urlStr)) {
+            this._monitorSkip = true;
+            return originalXHROpen.call(this, method, url, async, username, password);
+        }
         // 存储请求信息
         this._monitorData = {
             method,
-            url: url.toString(),
+            url: urlStr,
             startTime: 0,
         };
         return originalXHROpen.call(this, method, url, async, username, password);
     };
     XMLHttpRequest.prototype.send = function (body) {
+        // 跳过 SDK 自身的请求
+        if (this._monitorSkip) {
+            return originalXHRSend.call(this, body);
+        }
         const monitorData = this._monitorData;
         if (monitorData) {
             monitorData.startTime = Date.now();
@@ -671,6 +691,10 @@ function interceptXHR() {
 function interceptFetch() {
     window.fetch = async function (input, init) {
         const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        // 排除 SDK 自身的上报请求
+        if (isSdkRequest(url)) {
+            return originalFetch.call(window, input, init);
+        }
         const method = init?.method || 'GET';
         const startTime = Date.now();
         const requestBody = typeof init?.body === 'string' ? init.body : undefined;
@@ -1338,6 +1362,223 @@ function installBehaviorMonitor() {
     installInputTracker();
 }
 
+/**
+ * Vue 3 框架集成
+ * 捕获 Vue 组件内的渲染错误
+ */
+/**
+ * Vue 3 错误监控插件
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { VueMonitorPlugin } from 'sobey-monitor-sdk';
+ *
+ * const app = createApp(App);
+ * app.use(VueMonitorPlugin, {
+ *   appId: 'your-app-id',
+ *   dsn: 'http://your-server/api/report',
+ * });
+ * app.mount('#app');
+ * ```
+ */
+const VueMonitorPlugin = {
+    install(app, options) {
+        if (!options || !options.appId || !options.dsn) {
+            console.warn('[Monitor] VueMonitorPlugin requires appId and dsn in options');
+            return;
+        }
+        // 初始化 SDK（如果尚未初始化）
+        try {
+            monitor.init(options);
+        }
+        catch (e) {
+            // SDK 可能已经初始化，忽略错误
+        }
+        // 保存原有的错误处理器
+        const originalErrorHandler = app.config.errorHandler;
+        // 设置 Vue 错误处理器
+        app.config.errorHandler = (err, instance, info) => {
+            // 提取错误信息
+            const error = err instanceof Error ? err : new Error(String(err));
+            // 获取组件名称
+            let componentName = 'Unknown';
+            if (instance) {
+                componentName = instance.$options?.name ||
+                    instance.$.type?.name ||
+                    instance.$.type?.__name ||
+                    'AnonymousComponent';
+            }
+            // 添加面包屑
+            context.addBreadcrumb({
+                type: 'framework',
+                category: 'vue_error',
+                data: {
+                    componentName,
+                    info,
+                    message: error.message,
+                },
+            });
+            // 上报错误
+            reporter.reportError({
+                type: 'vue_error',
+                message: error.message,
+                stack: error.stack,
+                componentName,
+                lifecycleHook: info,
+            });
+            // 调用原有的错误处理器
+            if (typeof originalErrorHandler === 'function') {
+                originalErrorHandler(err, instance, info);
+            }
+        };
+        // 设置警告处理器（仅在开发模式下）
+        if (options.debug) {
+            const originalWarnHandler = app.config.warnHandler;
+            app.config.warnHandler = (msg, instance, trace) => {
+                // 添加面包屑
+                context.addBreadcrumb({
+                    type: 'console',
+                    category: 'vue_warning',
+                    data: { message: msg },
+                });
+                // 调用原有的警告处理器
+                if (typeof originalWarnHandler === 'function') {
+                    originalWarnHandler(msg, instance, trace);
+                }
+            };
+        }
+        if (options.debug) {
+            console.log('[Monitor] Vue plugin installed');
+        }
+    },
+};
+
+/**
+ * React 框架集成
+ * 提供 ErrorBoundary 组件捕获渲染错误
+ */
+/**
+ * 创建 React 错误边界组件
+ *
+ * @param React - React 库引用
+ * @param config - SDK 配置
+ * @returns ErrorBoundary 组件类
+ *
+ * @example
+ * ```tsx
+ * import React from 'react';
+ * import ReactDOM from 'react-dom';
+ * import { createReactErrorBoundary } from 'sobey-monitor-sdk';
+ *
+ * const ErrorBoundary = createReactErrorBoundary(React, {
+ *   appId: 'your-app-id',
+ *   dsn: 'http://your-server/api/report',
+ * });
+ *
+ * ReactDOM.render(
+ *   <ErrorBoundary fallback={<h1>Something went wrong</h1>}>
+ *     <App />
+ *   </ErrorBoundary>,
+ *   document.getElementById('root')
+ * );
+ * ```
+ */
+function createReactErrorBoundary(React, config) {
+    if (!config || !config.appId || !config.dsn) {
+        console.warn('[Monitor] createReactErrorBoundary requires appId and dsn in config');
+        // 返回一个空的组件
+        return class EmptyBoundary extends React.Component {
+            render() {
+                return this.props.children;
+            }
+        };
+    }
+    // 初始化 SDK（如果尚未初始化）
+    try {
+        monitor.init(config);
+    }
+    catch (e) {
+        // SDK 可能已经初始化，忽略错误
+    }
+    /**
+     * React 错误边界组件
+     */
+    return class ErrorMonitorBoundary extends React.Component {
+        constructor(props) {
+            super(props);
+            this.state = { hasError: false, error: null };
+        }
+        static getDerivedStateFromError(error) {
+            return { hasError: true, error };
+        }
+        componentDidCatch(error, errorInfo) {
+            // 获取组件堆栈
+            const componentStack = errorInfo?.componentStack || '';
+            // 添加面包屑
+            context.addBreadcrumb({
+                type: 'framework',
+                category: 'react_error',
+                data: {
+                    message: error.message,
+                    componentStack: componentStack.substring(0, 500),
+                },
+            });
+            // 上报错误
+            reporter.reportError({
+                type: 'react_error',
+                message: error.message,
+                stack: error.stack,
+                componentStack,
+            });
+            // 调用自定义错误回调
+            if (typeof this.props.onError === 'function') {
+                this.props.onError(error, errorInfo);
+            }
+            if (config.debug) {
+                console.error('[Monitor] React error caught:', error);
+                console.error('[Monitor] Component stack:', componentStack);
+            }
+        }
+        render() {
+            if (this.state.hasError) {
+                // 显示降级 UI
+                return this.props.fallback || null;
+            }
+            return this.props.children;
+        }
+    };
+}
+/**
+ * React Hook: 用于手动上报错误
+ *
+ * @example
+ * ```tsx
+ * import { useMonitorError } from 'sobey-monitor-sdk';
+ *
+ * function MyComponent() {
+ *   const reportError = useMonitorError();
+ *
+ *   const handleClick = async () => {
+ *     try {
+ *       await riskyOperation();
+ *     } catch (error) {
+ *       reportError(error, { action: 'riskyOperation' });
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleClick}>Click</button>;
+ * }
+ * ```
+ */
+function createUseMonitorError(React) {
+    return function useMonitorError() {
+        return React.useCallback((error, extra) => {
+            monitor.captureError(error, extra);
+        }, []);
+    };
+}
+
 /**
  * 前端监控 SDK
  * @description 错误监控、性能监控、行为监控
@@ -1449,6 +1690,9 @@ class MonitorSDK {
 // 导出单例
 const monitor = new MonitorSDK();
 
+exports.VueMonitorPlugin = VueMonitorPlugin;
+exports.createReactErrorBoundary = createReactErrorBoundary;
+exports.createUseMonitorError = createUseMonitorError;
 exports.default = monitor;
 exports.monitor = monitor;
 //# sourceMappingURL=index.cjs.js.map