SpringBoot3使用Apache Tika实现多格式文件内容提取

更新时间：2026年03月30日 09:31:18 作者：码路星河

做后端开发久了,难免碰到这类刚需：用户上传Word、PDF、Excel、Txt各种文档,后台得自动扒出文本做内容审核、全文检索或者数据库归档,所以本文使用 Apache Tika 搞定全格式解析,需要的朋友可以参考下

一、前期准备：项目环境与核心依赖

先说明环境版本：

JDK版本：17+
SpringBoot版本：3.2.5
Tika：3.2.3

在pom.xml文件引入相关依赖：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <!-- Maven模型版本，固定4.0.0适配SpringBoot3 -->
    <modelVersion>4.0.0</modelVersion>
    <!-- SpringBoot3父依赖，统一版本管理，避免依赖冲突 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>
    <!-- 项目基础信息，可根据实际业务修改 -->
    <groupId>com.example</groupId>
    <artifactId>springboot3-tika-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot3-tika-demo</name>
    <description>SpringBoot3集成Apache Tika文件解析实战</description>
    <!-- 全局版本属性，统一管理依赖版本，方便后续升级 -->
    <properties>
        <java.version>17</java.version>
        <tika.version>3.2.3</tika.version>
    </properties>
    <dependencies>
        <!-- SpringBoot Web核心依赖，提供HTTP接口、MVC等能力 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- Tika核心依赖，提供基础文件解析API -->
        <dependency>
            <groupId>org.apache.tika</groupId>
            <artifactId>tika-core</artifactId>
            <version>${tika.version}</version>
        </dependency>
        <!-- Tika标准解析器池，覆盖Office/PDF/TXT/Excel等主流办公格式 -->
        <dependency>
            <groupId>org.apache.tika</groupId>
            <artifactId>tika-parsers-standard-pooled</artifactId>
            <version>${tika.version}</version>
            <type>pom</type>
        </dependency>
        <!-- Apache通用工具包，简化字符串、集合、IO操作 -->
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>3.20.0</version>
        </dependency>
        <!-- Lombok注解工具，省略Getter/Setter/构造器，简化代码 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <!-- FastJSON2，高性能JSON序列化/反序列化，适配接口返回 -->
        <dependency>
            <groupId>com.alibaba.fastjson2</groupId>
            <artifactId>fastjson2</artifactId>
            <version>2.0.32</version>
        </dependency>
        <!-- 单元测试依赖，本地调试、接口测试使用 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <!-- SpringBoot打包插件，打包可执行JAR -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <!-- 打包时排除lombok，减小jar包体积 -->
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

二、实战集成：三步写完核心代码

1. 单例配置：避免重复创建实例

AutoDetectParser自动解析器是线程安全的，没必要每次解析都新建实例，交给Spring托管单例最划算，既能节省内存开销，后续自定义解析规则、扩展配置也更方便。

import org.apache.tika.parser.AutoDetectParser;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
 * Tika解析器配置类
 * 作用：将AutoDetectParser交给Spring管理单例，避免重复创建消耗资源
 */
@Configuration
public class FileDetectParserConfig {
    /**
     * 注册自动解析器Bean
     * AutoDetectParser：自动识别文件格式，无需手动指定解析器
     * 线程安全，全局单例使用即可
     */
    @Bean
    public AutoDetectParser detectParser() {
        // 默认配置适配绝大多数场景，可自定义编码、超时、解析规则
        return new AutoDetectParser();
    }
}

2. 文件解析结果对象实体类封装

新建文件信息实体类，统一封装解析文本和元数据，方便接口返回和业务层调用。

import lombok.Builder;
import lombok.Data;
import java.util.Map;
/**
 * 文件解析结果实体
 * 统一封装：提取的文本内容 + 文件元数据，标准化返回格式
 */
@Data
@Builder
public class FileInfo {
    /**
     * 从文件中提取的纯文本内容
     */
    private String fileText;
    /**
     * 文件元数据集合
     * Key：元数据字段名（如Content-Type、Author、Creation-Date）
     * Value：对应字段值
     */
    private Map<String,Object> metadata;
}

3. 核心服务类：覆盖高频解析场景

封装通用文件解析方法，内置10MB缓冲区阈值，兼顾大文件解析和内存控制。

import com.example.springboot3tikademo.entity.FileInfo;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.apache.tika.exception.TikaException;
import org.apache.tika.metadata.Metadata;
import org.apache.tika.parser.AutoDetectParser;
import org.apache.tika.parser.ParseContext;
import org.apache.tika.sax.BodyContentHandler;
import org.springframework.stereotype.Service;
import org.xml.sax.ContentHandler;
import org.xml.sax.SAXException;
import java.io.IOException;
import java.io.InputStream;
import java.util.HashMap;
import java.util.Map;
/**
 * 文件解析核心业务类
 * 封装统一解析逻辑，处理普通/大文件、元数据转换、异常捕获
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class FileDetectService {
    /**
     * 注入自动解析器单例
     */
    private final AutoDetectParser detectParser;
    /**
     * 统一文件解析入口
     * @param inputStream 文件输入流（前端上传/本地文件均可）
     * @return FileInfo 封装后的解析结果
     */
    public FileInfo parseFile(InputStream inputStream) {
        // 入参非空校验，防止空指针
        if (inputStream == null) {
            throw new IllegalArgumentException("文件输入流不能为空，请检查文件上传状态");
        }
        try {
            // 设置10MB缓冲区，平衡解析速度与内存占用，防止OOM
            ContentHandler handler = new BodyContentHandler(10 * 1024 * 1024);
            // 元数据对象：存储文件类型、作者、创建时间等属性
            Metadata metadata = new Metadata();
            // 解析上下文：用于扩展自定义解析规则、传参
            ParseContext context = new ParseContext();
            // 执行文件解析核心逻辑
            detectParser.parse(inputStream, handler, metadata, context);
            // Metadata对象无法直接序列化，转为HashMap适配接口返回
            Map<String,Object> metadataMap = new HashMap<>();
            for (String name : metadata.names()){
                metadataMap.put(name, metadata.get(name));
            }
            // 构建结果对象返回
            return FileInfo.builder()
                    .fileText(handler.toString())
                    .metadata(metadataMap)
                    .build();
        } catch (SAXException | TikaException | IOException e) {
            // 打印详细异常日志，方便线上排查问题
            log.error("文件解析失败，异常堆栈：", e);
            return null;
        }
    }
}

4. 接口开发：场景化测试调用

编写文件上传解析接口，接收前端上传文件，调用核心服务完成解析，返回结构化JSON数据，方便自测和前端对接；后续可在此基础上扩展单独的文件类型校验接口。

import com.alibaba.fastjson2.JSONObject;
import com.example.springboot3tikademo.entity.FileInfo;
import com.example.springboot3tikademo.service.FileDetectService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
import java.io.InputStream;
/**
 * 文件解析接口控制器
 * 对外提供HTTP接口，对接前端文件上传与解析请求
 */
@Slf4j
@RestController
@RequestMapping("/api/file")
@RequiredArgsConstructor
public class FileController {
    /**
     * 注入文件解析服务
     */
    private final FileDetectService fileDetectService;
    /**
     * 文件上传 + 全量解析接口
     * @param file 前端上传的文件对象
     * @return JSONObject 标准化响应结果（状态码+提示+数据）
     */
    @PostMapping("/parse")
    public JSONObject parseFile(@RequestParam("file") MultipartFile file) {
        // 第一步：校验文件是否为空
        if (file.isEmpty()) {
            return JSONObject.of("code", 500, "msg", "上传文件不能为空，请选择文件后重试");
        }
        // try-with-resources：自动关闭输入流，避免资源泄漏
        try (InputStream inputStream = file.getInputStream()) {
            // 调用服务层执行解析
            FileInfo fileInfo = fileDetectService.parseFile(inputStream);
            // 解析失败返回友好提示
            if (fileInfo == null) {
                return JSONObject.of("code", 500, "msg", "文件解析失败，请检查文件格式是否支持或文件是否损坏");
            }
            // 封装成功响应：拼接状态码、提示、文件名、解析数据
            JSONObject result = JSONObject.from(fileInfo);
            result.put("code", 200);
            result.put("msg", "文件解析成功");
            result.put("fileName", file.getOriginalFilename());
            return result;
        } catch (Exception e) {
            // 打印异常日志，定位上传/解析流程问题
            log.error("文件上传解析异常，文件名：{}", file.getOriginalFilename(), e);
            return JSONObject.of("code", 500, "msg", "解析异常：" + e.getMessage());
        }
    }
}

三、接口测试：验证解析效果

项目启动后，用Postman或者接口测试工具调用：

请求地址：POST localhost:8080/api/file/parse
请求方式：form-data，key设为file，选择本地文档（.doc/.docx/.pdf/.txt/.xlsx）
返回结果：结构化JSON，包含文件名、响应状态、提取文本、元数据（作者、文件类型、创建时间等）

实测主流办公格式都能正常解析，元数据完整不丢失，文本提取精准，不会出现乱码、内容截断问题。

四、常见问题与调优

1. 大文件解析报错：Write limit exceeded

当前代码已设置10MB缓冲区，若需解析更大文件，直接调整BodyContentHandler数值即可；比如设置100MB阈值：new BodyContentHandler(100 * 1024 * 1024)，不建议设为-1无限制，避免服务器OOM。

2. PDF中文乱码

解析PDF出现中文乱码，优先排查两点：一是服务器安装对应中文字体包，二是在解析前手动指定UTF-8编码，在Metadata中添加配置：

// 解析前手动指定UTF-8编码，解决PDF中文乱码、字符集不兼容问题
metadata.set(Metadata.CONTENT_ENCODING, "UTF-8");

3. 文件类型安全校验

严禁只靠文件名后缀判断文件类型，恶意文件篡改后缀极易绕过校验。可从元数据中提取真实MIME类型，做白名单校验，拦截非法文件上传：

// 1. 从元数据获取文件真实MIME类型，不依赖文件名后缀
String mimeType = (String) metadataMap.get("Content-Type");
// 2. 定义允许上传的文件白名单，可根据业务扩展（如Excel、PPT）
List<String> allowTypes = Arrays.asList(
        "application/pdf",                      // PDF格式
        "application/msword",                  // Doc旧版Word
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document", // Docx新版Word
        "text/plain"                           // TXT纯文本
);
// 3. 白名单校验，拦截非法文件，防止恶意上传
if (!allowTypes.contains(mimeType)) {
    throw new RuntimeException("不支持该文件类型，请上传PDF/Word/TXT格式文档");
}

4. 生产性能优化

超大文件（100MB+）建议采用异步解析，避免接口超时阻塞主线程
对重复上传文件做MD5缓存，复用解析结果，减少重复计算
配置SpringBoot文件上传大小限制，防止恶意大文件攻击
文件流务必使用try-with-resources自动关闭，避免资源泄漏

五、总结

这套SpringBoot3集成方案，配置简单，代码量小、侵入性极低，通过单例注入、标准化封装、统一解析，实现了多格式文件文本提取+元数据获取一站式搞定，完美适配内容审核、文档管理、数据录入、全文检索等业务场景。

除了基础的文档解析，Apache Tika还支持音视频文件元数据提取、图片文本OCR识别、压缩包内容遍历、加密文档解密等扩展能力，后续想叠加这些高阶功能，原有代码结构无需改动，直接扩展方法即可，兼容性和扩展性拉满。

以上就是SpringBoot3使用Apache Tika实现多格式文件内容提取的详细内容，更多关于SpringBoot3多格式文件内容提取的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

SpringBoot集成Drools规则引擎的实现实例
Drools是一个开源的业务规则管理系统和复杂事件处理引擎,通常用于自动化决策和规则引擎的开发,下面就来介绍一下SpringBoot集成Drools规则引擎的实现实例,感兴趣的可以了解一下
2025-09-09
基于jenkins实现发布node.js项目
这篇文章主要介绍了基于jenkins实现发布node.js项目,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-07-07
SpringBoot加载启动的源码解析
这篇文章主要介绍了SpringBoot加载启动的源码解析,@SpringBootApplication注解是Spring Boot的核心注解,它其实是一个组合注解,本身其实也是一个IoC容器的配置类,需要的朋友可以参考下
2023-12-12
java中的三种取整函数总结
下面小编就为大家带来一篇java中的三种取整函数总结。希望对大家有所帮助。一起跟随小编过来看看吧，祝大家游戏愉快哦
2016-11-11
Java实现单链表基础操作
大家好，本篇文章主要讲的是Java实现单链表基础操作，感兴趣的同学赶快来看一看吧，对你有帮助的话记得收藏一下
2022-02-02
springBoot+dubbo+zookeeper实现分布式开发应用的项目实践
本文主要介绍了springBoot+dubbo+zookeeper实现分布式开发应用的项目实践，文中通过示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
2022-03-03
Jar包如何导入本地maven仓库
将本地jar包导入本地maven仓库,可以通过maven命令-Dfile、-DgroupId、-DartifactId、-Dversion、-Dpackaging指定jar包的详细信息,然后执行命令即可
2024-11-11
使用mybatis的typeHandler对clob进行流读写方式
这篇文章主要介绍了使用mybatis的typeHandler对clob进行流读写方式，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2022-01-01
Java IO网络模型实现解析
这篇文章主要为大家介绍了Java IO网络模型实现解析，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪
2023-03-03
Springboot Controller接口默认自动填充业务实体参数值详解
这篇文章主要介绍了Springboot Controller接口默认自动填充业务实体参数值,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
2025-05-05