npm package: @lx-frontend/multi-report
Description: Sentry excepiton report.
Author: jeek tan
Latest version: 0.1.3

## @lx-frontend/report

### 开发

**1. 安装依赖**

```js
npm run bootstrap
```

---

**2. 构建**

```js
npm run build
```

---

**3. 发布**

```js
npm run publish
```

### 使用

**1. 安装**

```js
npm install --save @lx-frontend/report
```

---

**2. 初始化**

使用：

```js
import { init } from "@lx-frontend/report";

init({
  enable: process.env.RUN_ENV === "production",
  platform: "mp",
  dsn: "https://2e7514ffe05d464caf4f4f447a7212f4@sentry.lixinio.com/20",
  release: "",
  environment: process.env.RUN_ENV,
});
```

参数说明：

- enable (boolean)：是否开启 sentry 上报
- platform (string)：运行平台，传入 mp 或者 web，目前只支持 mp
- dsn (string)：sentry 密钥
- release (string)：项目版本
- environment (string)：运行环境

---

**3. 上报 http 异常**

使用：

```js
import { reportHttpException } from "@lx-frontend/report";

const { config, data, header, statusCode } = res;

const request = {
  url: config.url,
  method: config.method,
  header: config.header,
  body: config.body,
  timeout: config.timeout,
  custom: config.custom,
};

const response = {
  status: statusCode,
  header,
  data,
};

const tags = {
  user_id: 99,
};

const extra = {
  test: "hello",
};

reportHttpException({
  request,
  response,
  tags,
  extra,
});
```

参数说明：

- request (object)
  - url (string)：请求链接
  - method (string)：请求方法
  - header (object)：请求头部
  - body (any)：请求参数
  - timeout (number)：请求超时时间（可选）
  - custom (object)：自定义请求配置（可选）
- response (object)
  - status (number)：响应状态码
  - header (object)：响应头部
  - data (any)：响应数据
- tags (object)：自定义标签（可选）
- extra (any)：额外携带数据（可选）

---

**4. 上报业务异常**

使用：

```js
import { reportBusinessException } from "@lx-frontend/report";

const extra = {
  test: "hello",
};

reportBusinessException("上报业务异常", extra);
```

参数说明：

- 参数一 (string)：异常描述
- 参数二 (any)：额外携带数据（可选）

---

**5. 上报 socket 异常**

使用：

```js
import { reportSocketException } from "@lx-frontend/report";

const extra = {
  test: "hello",
};

reportSocketException("上报 socket 异常", extra);
```

参数说明：

- 参数一 (string)：异常描述
- 参数二 (any)：额外携带数据（可选）

### 小程序 babel 插件使用说明

插件的主要目的是，将上报库代码打包进分包，减小小程序主包大小。

其原理是，替换业务代码中的上报函数，避免主包直接引用上报库，替换的函数会根据全局变量判断上报库是否初始化，若没有，则将数据存储在 localStorage 中，若已经初始化，则上报存储的数据，后续可直接上报。插件的主要逻辑就是将业务代码中的上报函数，替换为插件提供的 sentryReport 函数，该函数会根据情况判断是存储还是直接上报，同时删除业务代码中对上报函数的引用。

**配置步骤**：

1. 在 App 文件中导入`sentryReport`函数，并将其挂载到全局的 globalData 下

```js
import sentryReport from '@lx-frontend/multi-report/lib/helper/sentryReport'

// 将这个函数挂载到全局变量中
class App extends Component {
  globalData: {
    sentryReport
  }
}
```

2. 在分包业务代码中导入 helper 下的初始化函数，使用该函数初始化上报库。

```js
// page
import initLxReport from "@lx-frontend/multi-report/lib/helper/initLxReport";

// 其他业务代码，比如useEffect内。
initLxReport({
  /* 上报库初始化参数 */
});
```

这一步是保证上报库被打包进分包代码

3. 配置 babel 插件

`log`配置为 boolean 类型，默认为 false，表示是否打印日志

```js
{
  plugins: [
    "other-plugin",
    [
      // babel配置文件到插件的路径
      require.resolve(
        "@lx-frontend/multi-report/lib/plugins/babel-transfer-plugin-mp"
      ),
      {
        //
        excludes: [
          // 对于肯定没有使用上报库函数的代码也可以排除在外，提升打包的速度，比如 node_modules 下的文件。
          /[\\/]node_modules[\\/]/,
        ],
        // log: true
      },
    ],
  ];
}
```

使用了插件后，除了初始化函数，其他上报函数的使用方式和上报库一致。