【免费下载链接】markitdownmarkitdownCliLib; Java项目地址https://gitcode.com/gh_mirrors/mark/markitdown点击查看免费下载markitdown 是一个把文档转成 Markdown 的开源工具其 Java 实现markitdown4j支持 PDF、Word、Excel、PPT、HTML、图片、音频、压缩包等 12 种文档转换器。本文带你走读两个核心源码DocumentConverter接口与ConverterRegistry注册表看懂 12 个转换器是如何被统一注册、按 MIME 类型路由并参与优先级选择的。一、整体架构一次转换要经过什么在 Java 模块markitdown-java中转换引擎的入口是 MarkItDownEngine.java。一次文件转换的完整链路只有 5 步校验文件存在性、是否普通文件、大小上限、可读性识别类型FileTypeDetector.detectMimeType()探测出 MIME 类型查找转换器ConverterRegistry.getConverter(mimeType)按优先级选出一个执行转换优先流式转换否则走路径转换返回结果统一的ConversionResult含 Markdown 内容、元数据、警告整个设计遵循策略模式 注册表每种文档格式是一个独立策略Converter注册表负责谁该上场。二、DocumentConverter 接口所有转换器的统一契约 接口源码DocumentConverter.java这个接口只有 6 个方法却定义了 12 个转换器共同遵守的规则方法类型作用convert(Path, ConversionOptions)必须实现把磁盘上的文件转成 Markdownconvert(InputStream, String, ConversionOptions)default流式转换默认直接抛异常见 L42-L49supportsStreaming()default是否支持流式转换默认falsesupports(String mimeType)必须实现声明我能处理哪些 MIME 类型getPriority()default优先级默认 0数值越大越先被选中getName()必须实现人类可读的唯一名称用于注册表去重两个容易忽略的细节流式转换是选择性加入的convert(InputStream, ...)的默认实现会抛出Stream-based conversion is not supported by ...异常转换器只有在明确支持时才需要覆写它配合supportsStreaming()返回true。优先级机制当多个转换器声明支持同一个 MIME 类型时getPriority()数值大者胜出。三、ConverterRegistry线程安全的转换器注册表 注册表源码ConverterRegistry.java注册表内部只有两个ConcurrentHashMap见 L35-L36nameToConverter转换器名称 → 实例保证名称唯一mimeTypeToConvertersMIME 类型 → 排序后的转换器列表惰性缓存3.1 注册名称冲突直接拒绝registerConverter()L53-L65是synchronized方法重复注册同名转换器会立即抛出IllegalArgumentException: Converter with name ... is already registered——这让名字冲突这种低级错误在启动阶段就暴露。3.2 查找按优先级排序 MIME 缓存getConverter(mimeType)L91-L113的查找逻辑先查 MIME 缓存命中直接取列表第 0 个未命中则遍历所有已注册转换器用supports(mimeType)过滤按getPriority()降序排序取第一个排序结果写入缓存后续同 MIME 的查找零开销此外还有配套方法getAllConverters(mimeType)返回全部匹配项供批量场景、getConverterByName(name)按名查找、getSupportedMimeTypes()基于 FileTypeDetector.java 的已知 MIME 集合推断支持范围。 注意unregisterConverter()移除转换器后会清空整个 MIME 缓存L73-L81避免读到过期结果——这是缓存一致性的关键细节。四、12 个内置转换器一览 转换器目录converters/所有转换器都实现DocumentConverter接口各自声明名称、优先级和 MIME 支持转换器优先级流式支持的 MIME 类型源码PdfConverter100✗application/pdfPdfConverter.javaDocxConverter100✗OOXML document、application/mswordDocxConverter.javaDocConverter100✗application/mswordDocConverter.javaPptxConverter100✗OOXML presentation、application/vnd.ms-powerpointPptxConverter.javaPptConverter100✗application/vnd.ms-powerpointPptConverter.javaXlsxConverter100✗OOXML sheet、application/vnd.ms-excel等 3 种XlsxConverter.javaXlsConverter100✗application/vnd.ms-excelXlsConverter.javaHtmlConverter100✗text/html、application/xhtmlxmlHtmlConverter.javaImageConverter80✗image/*前缀匹配ImageConverter.javaTextConverter50✓text/plain、text/markdown、text/csv、application/json、XML 等 6 种TextConverter.javaZipConverter50✗application/zip、application/x-zip-compressedZipConverter.javaAudioConverter30✗audio/*前缀匹配AudioConverter.java三个值得注意的设计MIME 重叠 优先级竞争如application/msword同时被 DocxConverter 和 DocConverter 声明此时靠优先级同为 100 时按注册表内部顺序决定image/*、audio/*则用前缀匹配一次覆盖整族格式。TextConverter 是唯一支持流式转换的内置转换器它一个类就覆盖了纯文本、Markdown、CSV、JSON、XML 六种 MIME 类型。优先级体现取舍PDF/Office 类给 100核心格式图片 80文本与压缩包 50音频 30依赖外部转写能力相对次要。五、注册流程createDefaultRegistry 如何装配 12 个转换器 注册入口MarkItDownEngine.javaMarkItDownEngine的无参构造默认调用createDefaultRegistry()它依次注册 11 个普通转换器registry.registerConverter(new PdfConverter()); registry.registerConverter(new DocxConverter()); // ... 共 11 个最后注册 ZipConverter 时源码展示了一个很有意思的委托模式L474-L488ZipConverter zipConverter new ZipConverter(); zipConverter.setDelegate(new ZipConverter.DocumentConverterDelegate() { ... }); registry.registerConverter(zipConverter);Zip 压缩包里的成员文件如a.zip/doc.pdf需要被解开再转一次。这里没有写死任何格式逻辑而是通过 ZipConverter.java 中的DocumentConverterDelegate函数式接口把解压后每个成员如何转换委托给一个复用同一注册表的新引擎实例——本质上实现了递归转换外层 zip 转成内部各文件 Markdown 的合集 摘要。六、一次转换的完整调用链把前面的知识串起来看doConvert()MarkItDownEngine.java#L182-L235的核心决策converterRegistry.getConverter(mimeType)查不到转换器时不会抛异常而是返回一个带警告信息的失败结果No converter found for MIME type ...并附上当前支持的全部类型拿到转换器后输入是流且supportsStreaming() true→convert(InputStream, ...)输入是文件 →convert(Path, ...)流输入但转换器不支持流式 → 抛ConversionException结果统一封装为 ConversionResult.java包含markdownContent、metadata、warnings、fileSize、originalFileName异步与批量场景下convertAsync()/convertParallel()只是把同步流程丢进ForkJoinPool选型逻辑完全相同——注册表是唯一的路由中枢。七、如何自定义一个新转换器得益于接口 注册表设计扩展只需两步// 1. 实现接口声明名称、优先级、MIME 支持实现 convert(Path, ...) // 2. 注册进引擎 markItDownEngine.registerConverter(new MyConverter());需要遵守的约定只有 3 条名称唯一重复注册会直接抛异常supports()声明尽量精确MIME 重叠时靠getPriority()分出先后仅当你确实能脱离文件系统工作时才覆写convert(InputStream, ...)并让supportsStreaming()返回true更多背景可参考项目文档development.md软件设计与模块职责、configuration.md配置项说明、markitdown.example.yml配置示例。小结markitdown4j 用最小接口 注册表就搭出了一个可扩展的文档转换框架DocumentConverter6 个方法定义契约default 方法让流式、优先级成为可选能力ConverterRegistry双 Map 结构名称唯一性检查 MIME 优先级排序 惰性缓存线程安全createDefaultRegistry()一处集中装配 12 个转换器Zip 委托模式优雅解决递归转换MarkItDownEngine校验 → 探测 → 路由 → 转换五步走完全链路这套策略 注册表 委托的组合值得任何需要按类型分发处理器的 Java 项目借鉴。赞分享【免费下载链接】markitdownmarkitdownCliLib; Java项目地址https://gitcode.com/gh_mirrors/mark/markitdown点击查看免费下载相关推荐Docling 架构解析DocumentConverter、Backend 与 Pipeline 如何协同完成文档转换Docling 架构解析DocumentConverter、Backend 与 Pipeline 如何协同完成文档转换 本篇围绕 Docling 官方架构文档人工智能计算机视觉OCRRAG学术论文 AI 流水线实战academic-research-skills 从文献到定稿学术论文 AI 流水线实战academic research skills 从文献到定稿 你一定遇到过这个瞬间打开 AI 帮你写的参考文献发现有一条引用根AI 技能科研AI 应用AI 评测markitdown4j 支持格式完整清单PDF、DOCX、XLSX、HTML 等 13 种文档转 Markdown 一次转换到位markitdown4j 支持格式完整清单PDF、DOCX、XLSX、HTML 等 13 种文档转 Markdown 一次转换到位 markitdown4j创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/25 12:22:34 · 阅读 1.2k markitdown4j源码走读：DocumentConverter接口与ConverterRegistry如何注册12种文档转换器
【免费下载链接】markitdownmarkitdownCliLib; Java项目地址https://gitcode.com/gh_mirrors/mark/markitdown点击查看免费下载markitdown 是一个把文档转成 Markdown 的开源工具其 Java 实现markitdown4j支持 PDF、Word、Excel、PPT、HTML、图片、音频、压缩包等 12 种文档转换器。本文带你走读两个核心源码DocumentConverter接口与ConverterRegistry注册表看懂 12 个转换器是如何被统一注册、按 MIME 类型路由并参与优先级选择的。一、整体架构一次转换要经过什么在 Java 模块markitdown-java中转换引擎的入口是 MarkItDownEngine.java。一次文件转换的完整链路只有 5 步校验文件存在性、是否普通文件、大小上限、可读性识别类型FileTypeDetector.detectMimeType()探测出 MIME 类型查找转换器ConverterRegistry.getConverter(mimeType)按优先级选出一个执行转换优先流式转换否则走路径转换返回结果统一的ConversionResult含 Markdown 内容、元数据、警告整个设计遵循策略模式 注册表每种文档格式是一个独立策略Converter注册表负责谁该上场。二、DocumentConverter 接口所有转换器的统一契约 接口源码DocumentConverter.java这个接口只有 6 个方法却定义了 12 个转换器共同遵守的规则方法类型作用convert(Path, ConversionOptions)必须实现把磁盘上的文件转成 Markdownconvert(InputStream, String, ConversionOptions)default流式转换默认直接抛异常见 L42-L49supportsStreaming()default是否支持流式转换默认falsesupports(String mimeType)必须实现声明我能处理哪些 MIME 类型getPriority()default优先级默认 0数值越大越先被选中getName()必须实现人类可读的唯一名称用于注册表去重两个容易忽略的细节流式转换是选择性加入的convert(InputStream, ...)的默认实现会抛出Stream-based conversion is not supported by ...异常转换器只有在明确支持时才需要覆写它配合supportsStreaming()返回true。优先级机制当多个转换器声明支持同一个 MIME 类型时getPriority()数值大者胜出。三、ConverterRegistry线程安全的转换器注册表 注册表源码ConverterRegistry.java注册表内部只有两个ConcurrentHashMap见 L35-L36nameToConverter转换器名称 → 实例保证名称唯一mimeTypeToConvertersMIME 类型 → 排序后的转换器列表惰性缓存3.1 注册名称冲突直接拒绝registerConverter()L53-L65是synchronized方法重复注册同名转换器会立即抛出IllegalArgumentException: Converter with name ... is already registered——这让名字冲突这种低级错误在启动阶段就暴露。3.2 查找按优先级排序 MIME 缓存getConverter(mimeType)L91-L113的查找逻辑先查 MIME 缓存命中直接取列表第 0 个未命中则遍历所有已注册转换器用supports(mimeType)过滤按getPriority()降序排序取第一个排序结果写入缓存后续同 MIME 的查找零开销此外还有配套方法getAllConverters(mimeType)返回全部匹配项供批量场景、getConverterByName(name)按名查找、getSupportedMimeTypes()基于 FileTypeDetector.java 的已知 MIME 集合推断支持范围。 注意unregisterConverter()移除转换器后会清空整个 MIME 缓存L73-L81避免读到过期结果——这是缓存一致性的关键细节。四、12 个内置转换器一览 转换器目录converters/所有转换器都实现DocumentConverter接口各自声明名称、优先级和 MIME 支持转换器优先级流式支持的 MIME 类型源码PdfConverter100✗application/pdfPdfConverter.javaDocxConverter100✗OOXML document、application/mswordDocxConverter.javaDocConverter100✗application/mswordDocConverter.javaPptxConverter100✗OOXML presentation、application/vnd.ms-powerpointPptxConverter.javaPptConverter100✗application/vnd.ms-powerpointPptConverter.javaXlsxConverter100✗OOXML sheet、application/vnd.ms-excel等 3 种XlsxConverter.javaXlsConverter100✗application/vnd.ms-excelXlsConverter.javaHtmlConverter100✗text/html、application/xhtmlxmlHtmlConverter.javaImageConverter80✗image/*前缀匹配ImageConverter.javaTextConverter50✓text/plain、text/markdown、text/csv、application/json、XML 等 6 种TextConverter.javaZipConverter50✗application/zip、application/x-zip-compressedZipConverter.javaAudioConverter30✗audio/*前缀匹配AudioConverter.java三个值得注意的设计MIME 重叠 优先级竞争如application/msword同时被 DocxConverter 和 DocConverter 声明此时靠优先级同为 100 时按注册表内部顺序决定image/*、audio/*则用前缀匹配一次覆盖整族格式。TextConverter 是唯一支持流式转换的内置转换器它一个类就覆盖了纯文本、Markdown、CSV、JSON、XML 六种 MIME 类型。优先级体现取舍PDF/Office 类给 100核心格式图片 80文本与压缩包 50音频 30依赖外部转写能力相对次要。五、注册流程createDefaultRegistry 如何装配 12 个转换器 注册入口MarkItDownEngine.javaMarkItDownEngine的无参构造默认调用createDefaultRegistry()它依次注册 11 个普通转换器registry.registerConverter(new PdfConverter()); registry.registerConverter(new DocxConverter()); // ... 共 11 个最后注册 ZipConverter 时源码展示了一个很有意思的委托模式L474-L488ZipConverter zipConverter new ZipConverter(); zipConverter.setDelegate(new ZipConverter.DocumentConverterDelegate() { ... }); registry.registerConverter(zipConverter);Zip 压缩包里的成员文件如a.zip/doc.pdf需要被解开再转一次。这里没有写死任何格式逻辑而是通过 ZipConverter.java 中的DocumentConverterDelegate函数式接口把解压后每个成员如何转换委托给一个复用同一注册表的新引擎实例——本质上实现了递归转换外层 zip 转成内部各文件 Markdown 的合集 摘要。六、一次转换的完整调用链把前面的知识串起来看doConvert()MarkItDownEngine.java#L182-L235的核心决策converterRegistry.getConverter(mimeType)查不到转换器时不会抛异常而是返回一个带警告信息的失败结果No converter found for MIME type ...并附上当前支持的全部类型拿到转换器后输入是流且supportsStreaming() true→convert(InputStream, ...)输入是文件 →convert(Path, ...)流输入但转换器不支持流式 → 抛ConversionException结果统一封装为 ConversionResult.java包含markdownContent、metadata、warnings、fileSize、originalFileName异步与批量场景下convertAsync()/convertParallel()只是把同步流程丢进ForkJoinPool选型逻辑完全相同——注册表是唯一的路由中枢。七、如何自定义一个新转换器得益于接口 注册表设计扩展只需两步// 1. 实现接口声明名称、优先级、MIME 支持实现 convert(Path, ...) // 2. 注册进引擎 markItDownEngine.registerConverter(new MyConverter());需要遵守的约定只有 3 条名称唯一重复注册会直接抛异常supports()声明尽量精确MIME 重叠时靠getPriority()分出先后仅当你确实能脱离文件系统工作时才覆写convert(InputStream, ...)并让supportsStreaming()返回true更多背景可参考项目文档development.md软件设计与模块职责、configuration.md配置项说明、markitdown.example.yml配置示例。小结markitdown4j 用最小接口 注册表就搭出了一个可扩展的文档转换框架DocumentConverter6 个方法定义契约default 方法让流式、优先级成为可选能力ConverterRegistry双 Map 结构名称唯一性检查 MIME 优先级排序 惰性缓存线程安全createDefaultRegistry()一处集中装配 12 个转换器Zip 委托模式优雅解决递归转换MarkItDownEngine校验 → 探测 → 路由 → 转换五步走完全链路这套策略 注册表 委托的组合值得任何需要按类型分发处理器的 Java 项目借鉴。赞分享【免费下载链接】markitdownmarkitdownCliLib; Java项目地址https://gitcode.com/gh_mirrors/mark/markitdown点击查看免费下载相关推荐Docling 架构解析DocumentConverter、Backend 与 Pipeline 如何协同完成文档转换Docling 架构解析DocumentConverter、Backend 与 Pipeline 如何协同完成文档转换 本篇围绕 Docling 官方架构文档人工智能计算机视觉OCRRAG学术论文 AI 流水线实战academic-research-skills 从文献到定稿学术论文 AI 流水线实战academic research skills 从文献到定稿 你一定遇到过这个瞬间打开 AI 帮你写的参考文献发现有一条引用根AI 技能科研AI 应用AI 评测markitdown4j 支持格式完整清单PDF、DOCX、XLSX、HTML 等 13 种文档转 Markdown 一次转换到位markitdown4j 支持格式完整清单PDF、DOCX、XLSX、HTML 等 13 种文档转 Markdown 一次转换到位 markitdown4j创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考