stack-trace 项目技术文档

1. 安装指南

安装方式

要安装 stack-trace 模块，请在终端中运行以下命令：

npm install stack-trace

依赖环境

• Node.js 环境
• npm 包管理器

2. 项目的使用说明

stack-trace 模块用于获取 V8 堆栈跟踪信息，并将其表示为 CallSite 对象的数组。以下是该模块的主要使用场景：

获取当前堆栈跟踪

你可以使用 stack-trace.get() 方法来获取当前的堆栈跟踪信息：

import { get } from 'stack-trace';
const trace = get();

expect(trace[0].getFileName()).toBe(__filename);

解析错误对象的堆栈跟踪

如果你已经有一个 Error 对象，并且想要解析其堆栈跟踪信息，可以使用 stack-trace.parse() 方法：

import { parse } from 'stack-trace';
const err = new Error('something went wrong');
const trace = parse(err);

expect(trace[0].getFileName()).toBe(__filename);

需要注意的是，解析 Error#stack 属性并不是完美的，只有部分属性可以被正确解析。

长堆栈跟踪

stack-trace 模块与 long-stack-traces 模块兼容。当解析跨越事件循环边界的 err.stack 时，CallSite 对象会返回 '----------------------------------------' 作为 getFileName() 的值，其他方法则返回 null。

3. 项目API使用文档

stackTrace.get([belowFn])

• 功能: 返回一个 CallSite 对象数组，其中数组的第 0 个元素表示当前的调用位置。
• 参数:
  • belowFn (可选): 当前堆栈中的一个函数。如果提供了该参数，返回的数组将只包含该函数之后的 CallSite 对象。
• 返回值: CallSite 对象数组。

stackTrace.parse(err)

• 功能: 将 Error 对象的 err.stack 属性解析为一个与 stackTrace.get() 返回值兼容的数组。
• 参数:
  • err: 一个 Error 对象。
• 返回值: CallSite 对象数组，但只有以下方法被实现：
  • getTypeName
  • getFunctionName
  • getMethodName
  • getFileName
  • getLineNumber
  • getColumnNumber
  • isNative

CallSite 对象

CallSite 对象是 V8 堆栈跟踪 API 的一部分，提供了以下方法：

• getThis(): 返回 this 的值。
• getTypeName(): 返回 this 的类型名称。
• getFunction(): 返回当前函数。
• getFunctionName(): 返回当前函数的名称。
• getMethodName(): 返回当前函数的属性名称。
• getFileName(): 如果函数定义在脚本中，返回脚本名称。
• getLineNumber(): 如果函数定义在脚本中，返回当前行号。
• getColumnNumber(): 如果函数定义在脚本中，返回当前列号。
• getEvalOrigin(): 如果函数是通过 eval 创建的，返回 eval 调用位置的 CallSite 对象。
• isToplevel(): 判断是否为顶层调用。
• isEval(): 判断是否在 eval 代码中调用。
• isNative(): 判断是否为原生 V8 代码。
• isConstructor(): 判断是否为构造函数调用。

4. 项目安装方式

如前所述，项目的安装方式非常简单，只需在终端中运行以下命令即可：

npm install stack-trace

安装完成后，你可以在项目中导入并使用 stack-trace 模块来获取和解析堆栈跟踪信息。