npm package: @one-pieces/wxapp-goldexp
Description: 小程序开发调试时错误检测提示工具
Author: one-pieces
Latest version: 0.0.0

# GoldExp
小程序开发调试时错误检测提示工具

## 介绍
在微信小程序开发过程中，会经常遇到大大小小的错误和警告，其中有一些原因会导致我们无法察觉项目中的问题：
- 哪些是需要我们关注的、有意义的、重要的错误警告
- 错误警告数量太多，容易忽略一些重要信息
- 错误警告只在开发者工具 Console 输出，提示不够明显

GoldExp 是小程序异常提示工具，用于开发调试时异常检测，可保证线下开发质量。

## UI 提示

异常提示目前分两种：Error、Warning

| 级别 | 图示 | 备注 |
| ---- | ---- | ---- |
| Error | ![image](./docs/imgs/4.png) | 全屏半透明灰底层展示 |
| Warning | ![image](./docs/imgs/5.png) ![image](./docs/imgs/6.png) | 使用浅黄色悬浮按钮加浅色黄底展示（悬浮层展示 warning 数量，点击后，展示 warning 详情） |

## 使用之前
使用 GoldExp 前，请确保你已经学习过微信官方的 [小程序简易教程](https://developers.weixin.qq.com/miniprogram/dev/framework/) 和 [自定义组件介绍](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/)。

## 安装
### 方式一. 通过 npm 安装 (推荐)
小程序已经支持使用 npm 安装第三方包，详见 [npm 支持](https://developers.weixin.qq.com/miniprogram/dev/devtools/npm.html?search-key=npm)

```bash
# 通过 npm 安装
npm i @ops/wxapp-goldexp -S --production
# 通过 yarn 安装
yarn add @ops/wxapp-goldexp --production
```
### 方式二. 下载代码

直接通过 git 下载 GoldExp 源代码，并将`dist`目录拷贝到自己的项目中
```bash
git clone https://github.com/one-pieces/wxapp-goldexp.git
```

## 使用组件
只需要在 json 文件中引入对应的自定义组件即可，一般在 app.json 引入。

```json
{
  "usingComponents": {
    "gold-exp": "@ops/wxapp-goldexp/components/index/index"
  }
}
```

接着就可以在 wxml 中直接使用组件

```html
<gold-exp wx:if="{{$goldExp}}" goldExp="{{$goldExp}}"></gold-exp>
```

然后接入中间件
```javascript
// app.js
import { GEApp } from '@wmfe/wxapp-goldexp';
GEApp({
	...
	onLaunch: function () {
	},
	globalData: {

	}
});

// page.js
import { GEPage } from '@wmfe/wxapp-goldexp';
GEPage({
	...
	onShow: function () {
	},
	Data: {

	}
});
```

最后设置配置
```javascript
// app.js
import { GEApp } from '@wmfe/wxapp-goldexp';
GEApp({
	...
    $goldExpConfig: {
		// 设置 env
		env: 'development',
		// env: 'production',
		report(reportData) {
			console.log('reportData: ', reportData);
		}
	},
	...
});
```
$goldExpConfig 为线下质量检测工具配置。不配置时，则不会监听。其中
- isConsoleOpen：是否开启 console 的检测。如果为 true，则会监听 console.warn 和 console.error，将展示提示面板，否则不监听。
- env：环境配置项。如果为 development，则监听，出现被检测的错误时，会展示提示面板，否则不会监听。
- level：错误级别配置项。值域为默认（''）、error（'error'）、warning（'warning'）。如果设置为默认则各个错误项按原本设定错误级别展示，error 则所有错误项按 error 级别展示，warning 同理。
- report：展示回调配置项。提示面板展示时，会执行该回调，用于上报错误信息，评估收益。其中 reportData 格式为
  ```javascript
    {
      type: 'ErrorShown', // 上报类型，ErrorShown 为展示 error，WarningShown 为展示 warning
      total: 1, // 展示错误的个数
      detail: [ // 错误详细信息
        {
            type: 'Js Error', // 错误类型，当前有'Js Error'和'Memory Warning'
          reason: 'thirdScript...' // 错误详情
        }
      ]
    }
  ```


## 在开发者工具中预览

```bash
# 安装项目依赖
yarn install
# 执行编译
yarn run dev
```

打开[微信开发者工具](https://mp.weixin.qq.com/debug/wxadoc/dev/devtools/download.html)，把`wxapp-goldexp/example`目录添加进去就可以预览示例了。

## 异常类型
| 类型 | 说明 | 级别 | 备注 |
| ---- | ---- | ---- | ---- |
| Page Drift Warning（内存泄露） | 页面飘移：被调用函数的上下文页面与当前页面不一致 | Warning | 提供暴露拦截函数对所有运行的函数进行包装，如果有非用户当前所在页面，但是却调用的，直接弹窗或整屏提示。 |
| Js Error | app.onError | Error | 监听 App onError，做线下提示 |
| Promise Warning | Promise._unhandledRejectionFn & app.onUnhandledRejection | Warning | 监听未处理的 Promise 拒绝事件 |
| Console | console.warn & console.error | Warning/Error | 监听 console.warn 和 console.error |