caught

一个可配置，且可扩展的，前端信息捕获工具 (A configurable, extensible h5 information capture tool)

原生支持TypeScript （Native support for TypeScript）

安装 (installation)

• 直接引入脚本 (Import scripts directly)

<script src="https://unpkg.com/caught-core"></script>

• 与打包工具一起使用 (Use with the packaging tool)

npm install caught-core -save

使用方法 (usage)

// 直接引入脚本 (Import scripts directly)
var caught = window.createCaught({
  //...options
  errorHandler: (errs) => {
    console.log('错误列表：', errs)
  },
  plugins: []
})
var createCustomInsert = caught.createCustomInsert
var proxyCaught = caught.proxyCaught
// 使用npm包 (Use NPM package)
import createCaught from 'caught-core'

const { createCustomInsert, proxyCaught } = createCaught({
  //...options
  errorHandler: (errs) => {
    console.log('错误列表：', errs)
  },
  plugins: []
})

说明 (instruction)

1. 各配置项及用途 (onfiguration items and usage)

| 选项名 | 用途 | 类型 | 默认值 | ---- | ---- | ---- | ---- | | sameLimit | 批量上传模式时，相同错误的最大载入限制 (Max load limit for the same error in batch upload mode) | number | 10 | retry | 是否开启处理失败重试模式 (Whether to enable retry after processing failure) | boolean | true | retryTime | 失败重试的间隔时间, 单位毫秒 (Retry interval, in milliseconds) | number | 5000 | failMaxNum | 最大失败次数，超出则停止捕获 (Maximum number of failures, beyond which capture stops) | number | 5 | listeners | 是否启用错误事件监听功能 (Whether to enable error event listening) | boolean or object| true | errorHandler | 信息处理方法，必传项 (Information processing method, must pass) | function | - | plugins | 插件配置项 (Plug-in configuration items) | array | [] | sync | 是否开启同步捕获 (Whether to enable synchronization capture) | boolean | fasle

除errorHandler外，其他都是可选项 (All except errorHandler are optional)

2. errorHandler选项说明

• errorHandler为必选项，若未设置，则整个caught工具不会生效
• errorHandler为函数类型，默认会注入两个参数，infoList数组及notify方法，infoList为当前捕获到的信息队列，notify由开发者方调用，用于通知caught本次信息处理成功(notify(true))或失败(notify(false))

{
  errorHandler(infoList, notify) {
    axios.post(url, data: infoList)
    .then(() => {
      notify(true)
    })
    .catch(() => {
      notify(false)
    })
  }
}

• 调用notify的目的有两个：1. 用于失败重试功能， 2. caught内存优化，若不调用，caught依然能正常运行，但失败重试功能将失效

3. createCaught返回值说明

• createCaught返回一个对象，目前包含2个属性 createCustomInsert 及 proxyCaught
• createCustomInsert 为开发者提供一个自定义错误类型的方式，包含3个参数 type, flag, extra, 分别对应错误类型（必传），错误标识（必传），额外标识（可选） type 用来限定错误类型，这个很重要，比如caught内置的错误类型有：jsError, staticError, promiseRection, proxy flag 用来标注一个特定的错误，比如 proxyCaught 就需要传入这样一个flag，用于标识当前函数的错误 extra 是额外的标识，用于指定唯一性的 在caught内部会为每个特定错误配置一个唯一的flag标识(不是createCustomInsert参数里的flag), 这个flag的格式如下 ${type}-${flag}-${index}${extra && '-' + extra}, index存在是考虑到相同参数的createCustomInsert会被调用多次，此时通过index来标识唯一性 createCustomInsert 返回一个customInsertInfo方法，开发者可通过此方法，将自定义的错误信息加入到 caught的调度系统中

  // 示例
  const customInsertInfo = createCustomInsert('http', 'get')
  axios(args).catch(err => {
    customInsertInfo({
      error: err,
      meta: {
        arges
      }
    })
  })

• proxyCaught 为开发者提供一个代理捕获错误的方式

  function userHandle() {
    // 假设出现了任何未捕获的错误（Any uncaught errors occurred）
  }
  const proxyUserHandle = proxyCaught(userHandle, {
    flag: 'todo'
  })
  proxyUserHandle()
  // 此时proxyUserHandle将自动捕获到userHandle中的错误，并交给caught的调度系统处理

• proxyCaught包含2个参数，一个是被代理的函数，一个是代理配置

// 代理配置
type proxyConfig = {
  flag: any, // 错误标识
  withArgs?: boolean, // 捕获到的错误是否携带参数
  others?: any, // 其他开发者自定义信息
} | string // 代理配置可传入一个字符串，caught内部将默认识别为flag

• proxyCaught对原函数是无害的，可以将代理后的函数完全等价于原函数（包括原型链等都进行了衔接）

4. 为插件编写提供的钩子 (Hooks provided for plug-in authoring)

| 钩子名 | 用途 | 参数 | ---- | ---- | ---- | | addInfo | caught默认只收集部分重要信息，若需要自定义额外信息，可通过次钩子添加 (Caught Collects only some important information by default. If you need to customize additional information, you can add it using the secondary hook ) | info | fail | 处理失败时的钩子 (Handle failed hooks) | infoList | success | 处理成功时的钩子 (Handle success hooks) | infoList | jsError | js error 事件触发时的钩子 (js Error the hook when the event is raised) | info, event | staticError | 静态资源加载 error 事件触发时的钩子 (Static resource loading hooks when the error event is raised) | info, event | promiseRejection | 未catch的promsie (Did not catch promsie) | info, event | schedulable | 调度机制初始化完成时的钩子 (oks for scheduling mechanism initialization when complete) | createCustomInsert

5. plugins选项说明 类似于webpack插件，caught也提供了插件扩展的能力，通过注册钩子来实现功能扩展，具体用法如下

class PluginDemo {
  apply(register) { // register 用于hook注册
    const handler = info => {
      const { type, flag, error, meta } = info
      return {
        myInfo: {
          name: 'meili',
        }
      }
      // 返回的对象将与原info中的meta信息合并
    }
    register.addInfo('add-info-plugin', handler) // 注册 addInfo 钩子， handler为回调函数
  }
}

createCaught({
  //...options
  plugins: [
    new PluginDemo()
  ]
})

• 插件需要用构造函数编写，原型上需要具备apply方法作为整个插件的入口

6. 详细的钩子说明

• addInfo: 此钩子一般用于添加额外的信息，开发者需要在回调函数中返回一个信息对象{ [key: any]： value: any }, 此对象将与caught内部提供的meta对象（若存在，如proxyCaught处理时）合并。
• fail: 此钩子将在notify(fasle)时触发, 参数为当前捕获的错误信息列表
• success: 此钩子将在notify(true)时触发, 参数为当前捕获的错误信息列表
• jsError: js错误事件钩子，error事件触发时会执行此钩子，并传入错误信息info及错误事件对象event，开发者可针对此事件进行自定义操作，若回调函数返回一个对象，则会人为是额外的信息，将与meta合并
• staticError: 静态资源加载失败事件钩子，事件触发时会执行此钩子，并传入错误信息info及错误事件对象event，开发者可针对此事件进行自定义操作，若回调函数返回一个对象，则会人为是额外的信息，将与meta合并
• promiseRejection: 未catch的promsie事件钩子，事件触发时会执行此钩子，并传入错误信息info及错误事件对象event，开发者可针对此事件进行自定义操作，若回调函数返回一个对象，则会人为是额外的信息，将与meta合并
• schedulable: 当caught调度系统初始化完成时会执行此钩子，此时会将createCustomInsert方法作为参数传递到回调函数中，用户可以在此阶段自定义捕获内容。（proxyCaught 方法就是在此时生成的）

7. 内置错误类型说明

• proxy --- 由proxyCaught代理捕获到的错误
• jsError --- error事件监听到的错误
• staticError --- 静态资源加载失败
• promiseRejection --- 未catch的promise

8. 内置的错误信息包含的内容

interface Info {
  type: string // 错误类型
  flag: string // 内部生成的错误标识 `${type}-${flag}-${index}${extra && '-' + extra}`
  meta?: Meta | Meta[] // 额外的信息，比如proxyCaught可选的一些信息：proxyCaught: { args, others }
  count?: number // 同一错误出现的次数
  error?: any // 错误信息
  message?: string // error事件对象中的 message
  filename?: string // error事件对象中的 filename （文件名）
  lineno?: number // error事件对象中的 lineno （行）
  colno?: number // error事件对象中的 colno （列）
  time?: number // 错误捕获的时间戳（ms）
}