Step Monitor

简介

一个轻量级的步骤监控工具，用于追踪和记录多步骤流程的执行状态。

功能特点

• 🌳 支持多层级步骤嵌套
• 🔄 异步流程监控
• 📝 自动记录每个步骤的状态
• ⏱️ 记录执行时间
• 🎯 支持自定义数据存储
• 🔍 详细的输入输出追踪
• 🔁 支持流程断点恢复

安装

npm install @step-monitor/core

快速开始

import { StepMonitor,type MonitorRecord,type StepRecord } from "@step-monitor/core";

// 创建监控器实例
const monitor = new StepMonitor({
   // monitor.stepStart() 时会调用 insertMonitor
  insertStep: async (step: StepRecord): Promise<{ id: string }> => ({ id: "1" }),
  // monitor.stepEnd() 时会调用 updateStep
  updateStep: async (step: StepRecord): Promise<{ id: string }> => ({ id: step.id }),
  // monitor.start() 时会调用 insertMonitor
  insertMonitor: async (monitor: MonitorRecord): Promise<{ id: string }> => ({ id: "1" }),
  // monitor.end() 时会调用 updateMonitor
  updateMonitor: async (monitor: MonitorRecord): Promise<{ id: string }> => ({ id: monitor.id }),
  // monitor.recover() 时会调用 getMonitor
  getMonitor: async (monitorId: string): Promise<MonitorRecord | null> => null,
  // monitor.recover() 时会调用 getMonitorSteps
  getMonitorSteps: async (monitorId: string): Promise<StepRecord[]> => [],
});

// 使用监控器
async function example() {
  let currentMonitor;
  try {
    // 开始监控
    currentMonitor = (await monitor.start("示例流程"));

    // 执行顶级步骤
    const step1 = await monitor.stepStart("步骤1");
    await monitor.stepEnd(step1.step_id, { result: "ok" });

    // 执行带子步骤的步骤
    const step2 = await monitor.stepStart("步骤2");
    const childStep = await monitor.stepStart("子步骤2-1", step2.step_id);
    await monitor.stepEnd(childStep.step_id, { done: true });
    await monitor.stepEnd(step2.step_id, { success: true });

    // 从数据库恢复流程
    const recoveredMonitor = await monitor.recover(currentMonitor.monitor_id);
    console.log(JSON.stringify(recoveredMonitor, null, 2));

    // 恢复后可以继续执行子步骤的步骤
    const step3 = await monitor.stepStart("步骤3");
    await monitor.stepEnd(step3.step_id, { success: true });


    // 完成流程
    await monitor.end({ success: true });
  } catch (error) {
    await monitor.end(null, error);
  }

  // 获取监控树
  const monitorTree = monitor.getMonitorTree();
  console.log(JSON.stringify(monitorTree, null, 2));
}

使用示例

完整的示例代码可以在 examples 目录中找到：

• 基础使用
• 错误处理
• 监控列表

运行示例

npm run example

API 参考

核心方法

流程控制

• start(name, input?, description?): 开始新流程
• recover(monitorId): 从数据库已有流程恢复
• end(output, error?): 结束当前流程

步骤控制

• stepStart(name, parentId?, input?, description?): 开始新步骤
• stepEnd(stepId, output, error?): 结束步骤

状态查询

• getMonitorTree(): 获取当前活动监控的树状结构
• getMonitorDetails(monitorId): 获取指定监控的详细信息
• listMonitors(options?): 查询监控列表

数据表设计参考

使用单表设计存储监控流程和步骤记录：

CREATE TABLE monitor_records (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    monitor_id VARCHAR(64) NOT NULL,         -- 监控ID
    step_id VARCHAR(64) UNIQUE NOT NULL,    -- 步骤ID
    parent_id VARCHAR(64),                    -- 父级ID：level=0时为空，level=1时为monitor_id，level>=2时为step_id
    type ENUM('monitor', 'step') NOT NULL,    -- 记录类型：监控流程/步骤
    level INT NOT NULL DEFAULT 0,             -- 步骤层级：0=监控，1=顶级步骤，2=子步骤...
    name VARCHAR(255) NOT NULL,               -- 名称
    status ENUM('pending', 'running', 'success', 'failed') NOT NULL,
    step_index INT,                           -- 同级步骤中的序号（从0开始）
    input JSON,                               -- 输入参数
    output JSON,                              -- 输出结果
    error TEXT,                               -- 错误信息
    description TEXT,                         -- 描述信息
    duration BIGINT,                          -- 执行时长(毫秒)
    metadata JSON,                            -- 扩展字段
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

    INDEX idx_step_id (step_id),
    INDEX idx_monitor_id (monitor_id),
    INDEX idx_parent (parent_id),
    INDEX idx_type_status (type, status),
    INDEX idx_level (level),
    INDEX idx_created_at (created_at)
);

设计说明

1. ID 设计

   • 使用自增主键作为内部 ID
   • step_id 作为业务 ID，用于外部引用
   • parent_id 用于关联流程和步骤

2. 类型区分

   • type 字段区分记录类型
   • monitor: 监控流程记录
   • step: 步骤记录

3. 状态追踪

   • 统一的状态定义
   • 包含时间戳和执行时长
   • 支持错误信息记录

4. 扩展性

   • input/output 使用 JSON 类型存储
   • metadata 字段支持额外信息
   • 支持描述信息

使用建议

1. 步骤组织

   • 使用 parentId 创建子步骤
   • 推荐最多使用三层步骤结构
   • 合理规划步骤粒度

2. 状态管理

   • 子步骤状态会影响父步骤
   • 步骤完成后状态不可更改
   • 错误发生时及时结束流程

3. 性能考虑

   • 合理使用分页查询
   • 避免过深的步骤嵌套
   • 及时清理历史数据

许可证

MIT