背景

作为程序猿，想必大家有过这样的经验。有报错信息，能必现的问题，调试修改起来一般都比较顺利。而那种没有报错的问题，难以发现、难以调试。很可能查了大半天，最后发现只需要改几行代码。付出与收益不成比。

举个例子：

> 某个小程序上调用某个 API，开发测试时候可以的，但后面因为一些原因突然没达到预期的效果。排查时候发现这个 API 因为一些原因走到了 fail 回调，但代码里只写了 success 回调，并没有写 fail 回调。

在实际开发中一般不会对每个 API 调用和其回调都打日志，多个 API，我们很难知道其调用过程，冷不丁就会出现意料外的情况而不知。

举个例子：

> 小程序上调用某个广告 API，但发现点广告关闭按钮，onClose 的回调一直没被调用。排查时候发现开发者在 page 的 onHide 回调里调用了 offClose，而进入广告会触发 page 的 onHide。

如果在小程序开发中能收集 API 调用与 API 回调的信息，对这些异常情况进行判断，在需要的时候能知道哪些 API 被执行，以及相互间的关系，那么在出现这类问题时能省掉大量排查时间。

快速开始

安装

在项目中
npm install --save proxy-monitor

在小程序中会用到 npm，参考文档

使用

以微信小程序为例
在小程序的 app.js 中

``javascript
const ProxyMonitor = require('proxy-monitor').default;
const monitor = new ProxyMonitor(wx, {
apiPrefix: 'wx',
report(data) {
console.log('report data', data);
}
});
wx = monitor.proxy; //修改全局变量
`

调用某个 api，没有传 fail 回调，却应该走到 fail 回调，如：

`javascript
wx.downloadFile({
url: 'test',
success() {
console.log('download file success');
}
});
`

那么能收到打印信息：

`json
{
"apiId": "2",
"apiName": "wx.downloadFile",
"property": "downloadFile",
"traceId": "2",
"traceApiName": "wx.downloadFile",
"args": [{ "url": "test", "success": "function" }],
"ret": "ok",
"isAsync": null,
"time": 1589512456512
}

{
"apiId": "3",
"apiName": "wx.downloadFile:args[0].fail:autoadd:callback",
"property": "fail",
"pid": "2",
"parentApiName": "wx.downloadFile",
"traceId": "2",
"traceApiName": "wx.downloadFile",
"args": [
{ "errMsg": "downloadFile:fail createDownloadTask:fail invalid url" }
],
"ret": "fail",
"isAsync": false,
"time": 1589512456521
}
`

建议一般情况只打印、上报 ret 不为 ok 的日志，要了解多个 API 及回调的调用顺序与依赖关系再打印更多信息。

原理说明

用Proxy和defineProperty可以监听对象属性的set、get，然后对函数进行包装，可以收集到参数、结果等信息。

Proxy和defineProperty不同点是：

Proxy可以在对象的属性get时进行处理，可以理解为懒处理。对于api调用缺少fail回调的情况，我们可以补一个空函数。如：

`
{
"apiId": "4",
"apiName": "wx.showToast:args[0].fail:autoadd:callback",
"property": "fail",
"pid": "3",
"parentApiName": "wx.showToast",
"traceId": "3",
"traceApiName": "wx.showToast",
"args": [
{
"errMsg": "showToast:fail parameter error: parameter.title should be String instead of Number;"
}
],
"ret": "fail",
"isAsync": false,
"time": 1589532839302
}
`

这样能发现api失败而漏传fail回调的情况。

defineProperty需要事先对对象属性进行改写监听，如果对每个缺少fail的api补充fail，那么可能会造成内存溢出的问题。

defineProperty性能会比Proxy好些，但不是高频调用，可忽略不计。

默认用Proxy进行处理，对不支持Proxy或用参数控制可以用defineProperty处理。

对api的结果进行递归处理，可以得到多层api调用链，如：wx.getFileSystemManager.saveFile。

综合处理api和其回调，可以分析判断一些异常情况，参考下面详细介绍。

详细介绍

ProxyMonitor 类

new ProxyMonitor(target[,options])

$3

监听目标对象

$3

选项

| 参数 | 类型 |
| ----------------------- | -------- |
| shouldHandleMethod | function |
| shouldHandleResult | function |
| shouldReportPropertySet | function |
| report | function |
| getApiId | function |
| hookSetTimeout | function |
| hookSetInterval | function |
| shouldHookConsoleError | function |
| apiCbkTimeout | number |
| eventCbkTimeout | number |
| dealType | string |

#### shouldHandleMethod(target,rootProperty,property):boolean

判断方法调用是否监听，缩小监听范围，避免大量无用信息

| 参数 | 类型 | 说明 |
| ------------ | ------ | --------------------------------------------- |
| target | object | 目标对，如 FileSystemManager 对象 |
| rootProperty | string | 调用链，如 wx.getFileSystemManager.saveFile |
| property | string | 方法名，如 FileSystemManager下的saveFile |

#### shouldHandleResult(target,rootProperty,property):boolean

判断是否对方法结果进行监听，如果该结果下的 api 属于高频调用，监听意义又不大，可以不做监听，如Canvas.getContext

| 参数 | 类型 | 说明 |
| ------------ | ------ | -------- |
| target | object | 目标对象 |
| rootProperty | string | 调用链 |
| property | string | 方法名 |

#### shouldReportPropertySet(target,rootProperty,property):boolean

判断是否监听对象的 set 操作，如多媒体对象的src的 set 操作可以监听，但其他的可以不做监听

| 参数 | 类型 | 说明 |
| ------------ | ------ | -------- |
| target | object | 目标对象 |
| rootProperty | string | 调用链 |
| property | string | 属性名 |

#### report(reportData)

接收处理 api 调用产生的数据

reportData对象

| 属性 | 类型 | 说明 |
| ------------- | ------- | --------------------------------------------------------------------------------------------- |
| apiId | string | id |
| apiName | string | 调用链 |
| property | string | 属性名 |
| pid | string | 父 id，如saveFile在downloadFile的回调中运行，那么其父 id 就是 downloadFile回调对应的 id |
| parentApiName | string | 父调用链 |
| traceId | string | 链路 id，既根api的 id |
| traceApiName | string | 根api |
| args | array | 方法参数 |
| res | array | 方法结果 |
| ret | string | 运行标识，一般情况下可以打印、上报不为ok的数据，需要分析排查问题时上报更多内容 |
| time | number | 执行时间 |
| isAsync | boolean | api的回调是否是异步执行 |

例子：

`
{
"apiId": "7",
"apiName": "wx.getFileSystemManager.saveFile:args[0].fail:callback",
"property": "fail",
"pid": "5",
"parentApiName": "wx.getFileSystemManager.saveFile",
"traceId": "3",
"traceApiName": "wx.downloadFile",
"args": [
{ "errMsg": "saveFile:fail permission denied, open \"./test.txt\"" }
],
"ret": "fail",
"isAsync": true,
"time": 1589524829196
}
`

对应代码是：

`
wx.downloadFile({
url: 'http://down.qq.com/qzone/c.txt',
success(res) {
console.log('download success', res)
fileSystemManager.saveFile({
tempFilePath: res.tempFilePath,
filePath: './test.txt',
success(res) {
console.log('save success')
},
fail(res) {
console.log('save fail', res)
}
})
},
fail(res) {
console.log('download fail', res)
}
})
`

parantApiName和traceApiName能关联离散的日志，帮助理解。借助zipkin这样的全链路日志系统，可以可视化观察 API 调用上下文，帮助开发者分析日志，排查问题。

##### ret的说明

| 名称 | 说明 |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| ok | 正常 |
| fail | fail 回调执行 |
| onError | 事件监听onError、onSocketError、onUpdateFailed的回调执行 |
| exception | api或回调执行出错。开发者可能会catch住错误但不打印，导致出问题而不知 |
| fail | fail回调执行 |
| timeout | success、fail回调超时 |
| timeout_maybe | 事件监听的回调超时 |
| errorLog | 构造参数shouldHookConsoleError传true时console.error的日志 |
| cbkMultiWarn | success、fail被多次调用的警告（一般是平台侧 api 实现的问题） |
| cbkOrderWarn | complete在success、fail调用前被调用（一般是平台侧 api 实现的问题） |
| cbkAsyncWarn | 可能你期望api的success、fail回调是异步的，但平台侧实现上是同步的，导致你的代码在时序上出现问题，这个会帮到你 |

#### getApiId():string

id 生成器

如果上报，需要生成唯一 id

#### hookSetTimeout(setTimeout)

包装setTimeout

因为setTimeout是异步的，setTimeout外的api调用和setTimeout回调里的api调用会失去关联关系。对setTimeout进行处理可以将上下关联起来。

一般情况下不用传

用法示例：

`
//app.js
const ProxyMonitor = require('proxy-monitor').default
const monitor = new ProxyMonitor(wx, {
apiPrefix: 'wx',
report(data) {
console.log('report data', JSON.stringify(data))
},
hookSetTimeout: setTimeout
});
wx = monitor.proxy //修改全局变量
App({
onLaunch: function () {
let fileSystemManager = wx.getFileSystemManager();
wx.downloadFile({
url: 'http://down.qq.com/qzone/c.txt',
success(res) {
console.log('download success', res)

monitor.setTimeout(function () {
fileSystemManager.saveFile({
tempFilePath: res.tempFilePath,
filePath: './test.txt',
success(res) {
console.log('save success')
},
fail(res) {
console.log('save fail', res)
}
})
})
},
fail(res) {
console.log('download fail', res)
}
})
}
})
`

上报数据示例：

`
{
"apiId": "8",
"apiName": "wx.getFileSystemManager.saveFile",
"property": "saveFile",
"pid": "7",
"parentApiName": "wx.setTimeout:callback",
"traceId": "3",
"traceApiName": "wx.downloadFile",
"args": [
{
"tempFilePath": "http://tmp/wx69f996eabbd34128.o6zAJs-_DIy1PGG3-yf5SNVll3yY.bpVYCxdHxs3P5d793fc5b00a2348c3fb9ab59e5ca98a.txt",
"filePath": "./test.txt",
"success": "function",
"fail": "function"
}
],
"ret": "ok",
"isAsync": null,
"time": 1589530097006
}
`

#### hookSetInterval(setInterval)

同上

#### shouldHookConsoleError:boolean

是否监听console.error，没有其他错误处理上报，可以设为 true

上报数据示例：

`
{
"apiId": "7",
"apiName": "wx.ConsoleError",
"pid": "6",
"parentApiName": "wx.getFileSystemManager.saveFile:args[0].fail:callback",
"traceId": "2",
"traceApiName": "wx.downloadFile",
"args": ["save file error"],
"ret": "errorLog",
"isAsync": null,
"time": 1589531227058
}
`

#### shouldHookConsoleError():boolean

是否监听console.error

#### apiCbkTimeout:number

判断success、fail回调超时时间，默认 3 秒

#### eventCbkTimeout:number

事件监听的回调超时时间，默认 30 秒

#### dealType:string

监听处理类型，Proxy或defineProperty。默认Proxy`