Mermaid DetailedError 接口详解:图表解析与渲染的错误契约
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 在管线中的两种形态:
- 已是 DetailedError(各图表解析/渲染模块按契约抛出
{ str, hash }):直接调用parseError(error.str, error.hash),把str与hash拆成两个参数传给回调;随后补上message与error两个可选字段后压入错误列表。 - 普通 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);
}
}
要点回顾:
str是契约核心:它是唯一必需字段,也是isDetailedError的判定依据,catch后应优先读取它;- 抛出的不是
Error实例:runThrowsErrors抛出的是errors[0]这一结构化对象,不能直接用instanceof Error判断; 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 |