Mermaid DetailedError 接口详解:图表解析与渲染的错误契约

原创2026-09-06 09:59:261,825 阅读
文章标签:前端数据可视化图表库

Mermaid DetailedError 接口详解:图表解析与渲染的错误契约

本文以 Mermaid 仓库中自动生成的 API 文档 docs/config/setup/mermaid/interfaces/DetailedError.md 为主体,完整覆盖 DetailedError 接口的全部字段定义,并结合 utils.ts 与 mermaid.ts 中的真实实现,讲清这一错误契约在 mermaid.run() 渲染管线中的产生、识别、归一化与抛出流程。读完本文,你将能够准确使用 parseError 回调、suppressErrors 选项处理渲染异常,并理解如何在自定义集成中判断与消费一个 DetailedError。

一、DetailedError 接口定义

DetailedError 是 Mermaid 对外抛出的"富错误"数据结构,定义于 packages/mermaid/src/utils.ts,官方接口文档为 docs/config/setup/mermaid/interfaces/DetailedError.md(该文件标注为自动生成,源文档位于 packages/mermaid/src/docs/ 下)。其源码如下:

// packages/mermaid/src/utils.ts#L782-L789
export interface DetailedError {
  str: string;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  hash: any;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  error?: any;
  message?: string;
}

四个字段的含义与约束如下:

属性 类型 是否必需 说明
str string 是 错误的描述字符串,是整个接口中唯一的必需字段,也是运行时识别 DetailedError 的依据
hash any 是 附带上下文的哈希/定位信息(在 mermaid.ts 中通常承载 error.name 或图表模块传来的附加标识),类型刻意宽松
error any(可选) 否 原始的底层错误对象,便于调用方进一步检查堆栈或类型
message string(可选) 否 人类可读的错误消息,通常与 str 内容一致

从源码结构看,hash 与 error 均采用 any 类型并附带 eslint-disable 注释,说明该接口刻意保持开放:各图表模块(flowchart、sequence、gantt 等)抛出的底层错误形态不一,统一收敛到 { str, hash } 这一最小契约上,避免把某一种解析器的错误细节泄漏到公共 API 中。

二、配套工具:类型守卫与消息提取

DetailedError 定义之后,utils.ts 紧接着提供了两个直接服务于它的工具函数:

// packages/mermaid/src/utils.ts#L793-L795
export function isDetailedError(error: any): error is DetailedError {
  return 'str' in error;
}

// packages/mermaid/src/utils.ts#L798-L803
export function getErrorMessage(error: unknown): string {
  if (error instanceof Error) {
    return error.message;
  }
  return String(error);
}
  • isDetailedError 是一个 TypeScript 类型守卫,判定逻辑极简:只要对象带有 str 属性,就视为 DetailedError。这正是 str 成为必需字段的深层原因——它是运行时 duck-typing 的锚点。
  • getErrorMessage 则负责把任意形态的错误(Error 实例、string 或其他值)安全地转成字符串消息,供日志与展示层使用。

三、错误处理管线:从图表模块到调用方

DetailedError 并非静态数据,而是贯穿 mermaid.run() 的错误传输协议。核心实现在 packages/mermaid/src/mermaid.ts 中。

3.1 handleError:错误归一化

mermaid.ts#L77-L100 定义了统一入口 handleError:

const handleError = (error: unknown, errors: DetailedError[], parseError?: ParseErrorFunction) => {
  log.warn(error);
  if (isDetailedError(error)) {
    // handle case where error string and hash were
    // wrapped in object like`const error = { str, hash };`
    if (parseError) {
      parseError(error.str, error.hash);
    }
    errors.push({ ...error, message: error.str, error });
  } else {
    // assume it is just error string and pass it on
    if (parseError) {
      parseError(error);
    }
    if (error instanceof Error) {
      errors.push({
        str: error.message,
        message: error.message,
        hash: error.name,
        error,
      });
    }
  }
};

这段代码揭示了 DetailedError 在管线中的两种形态:

  1. 已是 DetailedError(各图表解析/渲染模块按契约抛出 { str, hash }):直接调用 parseError(error.str, error.hash),把 str 与 hash 拆成两个参数传给回调;随后补上 message 与 error 两个可选字段后压入错误列表。
  2. 普通 Error 对象:被"归一化"成一个 DetailedError 形态——取 error.message 作为 str/message、error.name 作为 hash,原始对象放入 error 字段。

也就是说,message 与 error 两个可选字段主要由 handleError 在归一化时填充,这解释了它们为何在接口中是可选的。

3.2 runThrowsErrors:逐图渲染与错误收集

runThrowsErrors 负责遍历所有 .mermaid 节点逐个渲染,错误收集逻辑如下:

// packages/mermaid/src/mermaid.ts
const errors: DetailedError[] = [];   // L171
// ...对每个节点执行 await render(id, txt, element)
} catch (error) {
  handleError(error, errors, mermaid.parseError);   // L207
}
// ...
if (errors.length > 0) {
  // TODO: We should be throwing an error object.
  throw errors[0];   // L210-L213
}

两个关键行为:

  • 错误不会中断批量渲染:单个图表失败只会被 handleError 记录并继续处理后续图表;
  • 最终抛出的是 DetailedError 对象:循环结束后若 errors 非空,抛出的是 errors[0](一个带 str、hash、message、error 的对象,而非 Error 实例)。源码中的 TODO 注释也表明团队已知此处抛出的是结构化对象。因此调用方 catch 到错误后,可用 isDetailedError 判断后再取 str。

3.3 run 与 suppressErrors:决定是否向外抛出

包装函数 run 决定错误最终去向:

const run = async function (options: RunOptions = { querySelector: '.mermaid' }) {
  try {
    await runThrowsErrors(options);
  } catch (e) {
    if (isDetailedError(e)) {
      log.error(e.str);
    }
    if (mermaid.parseError) {
      mermaid.parseError(e as string);
    }
    if (!options.suppressErrors) {
      log.error('Use the suppressErrors option to suppress these errors');
      throw e;
    }
  }
};

配合 RunOptions 接口 中的 suppressErrors?: boolean(默认 false):

  • suppressErrors: false(默认):错误记录日志后继续 throw,由外层 try/catch 处理;
  • suppressErrors: true:错误仅写入日志,run() 正常返回,适合"尽力渲染"的场景(例如页面中混杂大量第三方图表源码时)。
// 实践示例:批量渲染且抑制错误
await mermaid.run({
  querySelector: '.mermaid',
  suppressErrors: true,
  postRenderCallback: (id) => console.log('rendered:', id),
});

四、ParseErrorFunction:让图表模块注册解析错误回调

DetailedError 的另一条消费路径是 parseError 回调。其类型定义在 packages/mermaid/src/Diagram.ts#L10:

export type ParseErrorFunction = (err: string | DetailedError | unknown, hash?: any) => void;

对应文档见 docs/config/setup/mermaid/type-aliases/ParseErrorFunction.md。各图表模块在解析失败时通过它把 { str, hash } 上报;handleError 中 parseError(error.str, error.hash) 的调用方式与该签名一一对应。

对于无法直接给 mermaid 对象添加成员的环境(如文档中提到的 dart interop wrapper),setParseErrorHandler 提供了等价入口:

// packages/mermaid/src/mermaid.ts#L317-L319
const setParseErrorHandler = function (parseErrorHandler: (err: any, hash: any) => void) {
  mermaid.parseError = parseErrorHandler;
};

完整用法(摘自 mermaid.ts 的 JSDoc):

// 方式一:直接赋值
mermaid.parseError = function (err, hash) {
  forExampleDisplayErrorInGui(err); // 在 GUI 中展示错误
};

// 方式二:通过 setter
mermaid.setParseErrorHandler(function (err, hash) {
  console.error('Parse failed:', err, hash);
});

五、在自定义集成中使用 DetailedError

基于以上源码事实,在第三方集成中处理 mermaid 渲染错误的推荐模式为:

import mermaid from 'mermaid';
// 从 utils 导出的类型守卫(同包内);跨包集成时可用等价判断
function isDetailedError(error) {
  return typeof error === 'object' && error !== null && 'str' in error;
}

mermaid.initialize({ startOnLoad: false });

try {
  await mermaid.run({ querySelector: '.mermaid' });
} catch (e) {
  if (isDetailedError(e)) {
    // e.str      -> 错误描述
    // e.hash     -> 附加上下文
    // e.message   -> 由 handleError 填充,通常等于 e.str
    // e.error    -> 原始底层错误对象
    console.error('Mermaid render error:', e.str, e.hash);
  } else {
    console.error('Unexpected error:', e);
  }
}

要点回顾:

  1. str 是契约核心:它是唯一必需字段,也是 isDetailedError 的判定依据,catch 后应优先读取它;
  2. 抛出的不是 Error 实例:runThrowsErrors 抛出的是 errors[0] 这一结构化对象,不能直接用 instanceof Error 判断;
  3. message/error 由管线填充:图表模块只需按最小契约抛 { str, hash },其余字段由 handleError 归一化补齐。

六、相关文档与源码索引

内容 路径
DetailedError 接口文档(本文主体) docs/config/setup/mermaid/interfaces/DetailedError.md
接口与工具函数实现 packages/mermaid/src/utils.ts#L782-L803
错误处理管线(handleError / run / runThrowsErrors) packages/mermaid/src/mermaid.ts#L77-L141
ParseErrorFunction 类型定义 packages/mermaid/src/Diagram.ts#L10
RunOptions(含 suppressErrors)接口文档 docs/config/setup/mermaid/interfaces/RunOptions.md
Mermaid 主对象接口文档 docs/config/setup/mermaid/interfaces/Mermaid.md
渲染与配置使用指南 docs/config/usage.md
登录后查看全文
mermaid