简介这是一份 Spring Boot 集成 OCR 功能的演示工程面向需要为 Java Web 应用快速接入文字识别能力的开发者解决从依赖引入、服务配置到 API 接口编写的完整落地问题。rar 压缩包共 7 个文件体积约 9KB以 3 个 Java 源码文件为主配合构建配置、属性配置等资源文件以及 Maven 包装器相关的启动脚本目录结构清晰适合直接对照学习或改造复用。资源内容涵盖两种主流集成方式一是通过 tess4j 调用本机 Tesseract 开源引擎二是使用 RestTemplate/WebClient 请求阿里云、腾讯云等 OCR 接口同时给出图片上传、Base64 传参、JSON 响应解析等编码要点并延伸到图片安全检查、Async 异步识别、消息队列解耦和缓存复用等进阶处理思路。已有 409 人浏览/学习适合正在做 Spring Boot 项目、希望引入 OCR 功能并了解接口封装与配置方式的开发者也可作为 RESTful API 调用、文件上传处理及 Java Web 微服务实践的综合参考。1. SpringBoot集成OCR demo把一张图片变成可检索的文本之前帮朋友改毕业设计需求是“上传合同照片抽出里面的编号和日期”。他一开始打算自己写图像识别我直接拦住了SpringBoot集成OCR这件事真正的难点从来不是OCR算法而是怎么把“上传图片、调用识别、返回文本”这条链路在一个Web工程里跑通。所以最务实的做法就是找一个能跑的OCR demo把离线识别、在线识别两条路都打通再根据场景换引擎。这篇笔记就是围绕这样一个SpringBoot集成OCR的demo展开适合两类人一是后端开发想快速给系统加上OCR能力二是做毕设或小工具需要“能跑、能讲清楚”的示例工程。思路很简单先离线Tesseract兜底再在线百度OCR兜底最后用PDF转图把使用范围扩大。2. 离线路线怎么落地Tesseract Tess4J把第一个中英文识别请求发出去2.1 离线还是在线先把选择边界画清楚选OCR方案之前必须回答三个问题图片会不会出网、调用频率有多高、识别质量要求到什么程度。这三个问题直接决定你是用Tesseract这种本地引擎还是接百度、腾讯这类在线API。我见过不少项目一上来就接在线OCR结果图片涉及客户隐私合规那边直接打回也见过坚持本地识别结果中文识别率惨不忍睹上线一周被投诉十几次。这里把两条路线放在一张表里对比方便按实际场景选型。对比项离线 TesseractTess4J在线百度 OCR部署环境依赖本地动态库需安装 tesseract-ocr只需HTTP调用无本地依赖成本免费但语言包和算力自备按调用次数计费有免费额度中文识别率干净印刷体还行复杂版面较差明显更稳支持表格、手写数据隐私图片不出服务器适合敏感数据图片需要发送到第三方接口集成工期半天能跑通调优耗时申请密钥后几小时能通我的一般做法是demo阶段先走离线因为离线链路不依赖外网排错路径短等真实业务验证识别率不够再切在线API做兜底。这样哪怕在线接口临时不可用系统也不至于全挂。毕竟说到底一个可复现的demo最重要的是把主流程跑顺而不是一上来就追求最先进的技术栈。2.2 Tess4J依赖、语言包与第一个识别Service先说依赖。SpringBoot工程里集成Tesseract最省事的是用Tess4J这个封装库。在pom.xml里加一个依赖即可dependency groupIdnet.sourceforge.tess4j/groupId artifactIdtess4j/artifactId version4.5.4/version /dependency依赖引入之后还要准备语言包。Tesseract默认只能识别英文要支持中文必须把chi_sim.traineddata放到识别引擎能找到的位置。常见做法是在src/main/resources下建一个tessdata目录把语言包丢进去路径交给类加载器去解析避免写死Windows或Linux的绝对路径。下面是我常用的OCR Service实现核心代码很短Service public class OcrService { public String recognize(MultipartFile file) throws Exception { // 1. 用ImageIO把上传的图片读成BufferedImage BufferedImage image ImageIO.read(file.getInputStream()); if (image null) { throw new IllegalArgumentException(无法解析图片格式请检查文件是否损坏); } // 2. 初始化Tesseract实例 Tesseract tesseract new Tesseract(); // 3. 指向语言包目录这里直接读取classpath下的tessdata String dataPath Objects.requireNonNull( getClass().getClassLoader().getResource(tessdata) ).getPath(); tesseract.setDatapath(dataPath); // 4. 中英文一起识别chi_sim在前 tesseract.setLanguage(chi_simeng); tesseract.setOcrEngineMode(TessOcrEngineMode.OEM_LSTM_ONLY); // 5. 执行识别 return tesseract.doOCR(image); } }这段逻辑有四个关键点第一步必须判空因为ImageIO.read对损坏文件会静默返回null不判空会直接炸出奇怪的NPE第二步到第四步是固定配置过程chi_simeng表示中文为主、英文辅助顺序会影响识别优先级很多人会漏掉setOcrEngineModeLSTM模式对现代印刷体识别效果明显好于传统引擎最后doOCR可以直接接收BufferedImage不需要先把上传文件落盘省掉了临时文件清理的麻烦。2.3 用Controller暴露成上传接口顺便把参数说清楚Service写好后还需要一个HTTP入口。我用一个简单的Controller接收MultipartFile并在配置里把端口和上传大小限制一并调好RestController RequestMapping(/ocr) public class OcrController { private final OcrService ocrService; public OcrController(OcrService ocrService) { this.ocrService ocrService; } PostMapping(/extract) public String extract(RequestParam(file) MultipartFile file) throws Exception { if (file.isEmpty()) { return 上传文件不能为空; } return ocrService.recognize(file); } }对应的application.yml里有两处配置最容易忽略一个是服务端口另一个是Spring MVC的multipart大小限制。server: port: 8090 spring: servlet: multipart: max-file-size: 5MB max-request-size: 6MB端口这个事看起来小实际上团队里多个SpringBoot demo同时跑的时候默认8080冲突特别常见。你本地起一个、前端起一个不换端口就会报端口占用。至于max-file-size默认只有1MB手机拍出来的照片动不动三四MB不调这个限制接口会直接报MaxUploadSizeExceededException而且是请求还没到Controller就被Spring拦掉了排查起来很容易懵。启动工程后用Postman或者curl试一发能返回文字说明离线链路已经通了。到这里SpringBoot集成OCR这事的骨架就算立住了。3. 在线路线怎么兜底接入百度OCR用Base64和RestTemplate处理图片上传3.1 什么时候切在线一个真实触发场景离线链路跑通之后你先别急着庆祝。拿一张稍微带点倾斜角度、或者背景有印章的照片去测Tesseract的识别结果大概率会翻车。这时候就得启动备选方案在线OCR。我在实际项目里遇到最典型的情况是识别快递面单面单上同时有中文、数字、条形码而且背景是网格纸Tesseract识别出来的地址断词严重完全没法直接用。换百度通用文字识别之后准确率能拉回九成以上。接百度OCR前需要先准备凭证。登录百度智能云控制台在“文字识别”产品下创建一个应用拿到API Key和Secret Key。这两个值不要硬编码在代码里放配置文件就行。但注意调用OCR接口时不能直接拿API Key去请求要先换取access_tokencurl -X POST \ https://aip.baidubce.com/oauth/2.0/token?grant_typeclient_credentialsclient_id你的APIKeyclient_secret你的SecretKey返回的JSON里有一个access_token字段这个token有效期默认30天。我一般会在OcrService里把token做一次内存缓存而不是每个请求都去换取既省流量又能避免触发鉴权接口的QPS限制。3.2 Base64上传还是multipartRestTemplate这样写才不翻车很多人第一次调百度OCR时脑子里还停留在“用RestTemplate传multipart文件”这个套路结果踩了一个很常见的坑百度通用文字识别的接口要求参数格式是application/x-www-form-urlencodedimage字段要把图片做Base64编码后放进表单。直接传multipart的ByteArrayResource服务端会一脸茫然地返回参数错误。这也是搜索热词里“springboot中mutipart如何用resttemplate传”出现频率高的原因。正确写法是把图片字节码转Base64字符串再用LinkedMultiValueMap封装public OcrResult recognizeWithBaidu(byte[] imageBytes, String accessToken) { // 1. 图片转Base64 String base64Image Base64.getEncoder().encodeToString(imageBytes); // 2. 构造表单参数 MultiValueMapString, String body new LinkedMultiValueMap(); body.add(image, base64Image); HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED); HttpEntityMultiValueMapString, String request new HttpEntity(body, headers); // 3. 拼接URL并发送 String url https://aip.baidubce.com/rest/2.0/ocr/v1/general_basic?access_token accessToken; ResponseEntityString response restTemplate.postForEntity(url, request, String.class); // 4. 解析返回结果 return parseBaiduResponse(response.getBody()); }这里有三处细节值得展开第一body.add(image, base64Image)字段名必须是image写成file或pic都会被百度接口判为参数错误第二HttpHeaders必须显式设置Content-Type为APPLICATION_FORM_URLENCODED不设置的话RestTemplate会用默认的application/json请求直接失败第三Base64编码后不要把、/、这些特殊字符再做一层URLEncoder百度这个接口接受原始Base64值画蛇添足反而可能出现未对齐的报错。解析返回结果时我对返回的JSON用Jackson解析只取words_result数组里每个元素的words字段拼接成文本。注意words_result可能为空数组不要假设它一定有值。3.3 返回数据与错误码看懂words_result和log_id百度OCR的返回结构比较固定正常响应长这样{ log_id: 2104391514326391551, words_result: [ { words: 金额10000元 }, { words: 日期2024-01-15 } ], words_result_num: 2 }words_result_num是识别出来的字段数可以用它做基本校验如果返回0说明图片里可能没有文字或者图片质量太差log_id是本次请求的唯一标识出问题找百度工单时人家第一句话就是问log_id习惯性把log_id存到日志里能省不少沟通成本。真正要警惕的是错误返回。搜索热词里出现过这样一条真实报错{log_id: 2104391514326391551, error_msg: file format error}。这个错误我在联调时也遇到过原因基本集中在图片格式上比如PNG图片被改了后缀名伪装成JPG上传、图片体积超过限制、或者Base64编码没有正确去除换行符。遇到这种报错别急着怀疑代码逻辑先用图片处理库把图片统一转成标准JPG格式把体积压缩到2MB以内重试一次通常就好。这个处理思路在下一章的避坑部分还会细讲。4. 常见问题与避坑排查语言包缺失、版本冲突、图片格式错误逐个拆开4.1 现象中文全部变成方框和乱码第一次跑通离线识别时英文识别一切正常但中文输出全是???或者方框看起来就像编码问题实际跟编码半毛钱关系没有。原因基本只有一个Tesseract的语言包里没有chi_sim.traineddata或者设置了chi_sim但语言包路径根本没指对。Tesseract的英文训练数据是随引擎自带的中文则需要单独下载。所以很多人把资源文件放到了随便一个目录但代码里setDatapath指向了别处。解决的思路很直接确认语言包在classpath下并且代码里用getClass().getClassLoader().getResource(tessdata)获取路径而不是写死/usr/local/share/tessdata这种绝对路径。这里有个隐蔽的坑SpringBoot打成Jar包后资源文件在Jar内部getResource().getPath()拿到的是一个file:/path/app.jar!/tessdata这样的路径Tesseract这种本地库不一定认得。我一般在开发环境用这个方法没问题但打成可执行Jar部署后就得把tessdata目录复制到外部再通过配置项传入路径tesseract.setDatapath(ocrConfig.getTessdataPath());把路径交给application.yml里的一个自定义配置项管理部署时根据环境改配置就好。从那以后我再也没有在语言包路径上翻过车。4.2 现象百度OCR返回 file format error接口返回error_msg: file format error但你的图片明明是JPG用浏览器打开也能正常显示。原因通常是三个一是文件后缀名和实际编码格式不一致比如把PNG直接改名成JPG二是图片体积超过百度接口限制通用文字识别要求Base64编码后不大于4MB三是图片本身有破损或者从网络上下载时缺少了文件头信息。解决办法是在调用百度接口前先做一次格式统一和压缩。我习惯写一个工具方法public byte[] normalizeImage(byte[] source) throws IOException { BufferedImage image ImageIO.read(new ByteArrayInputStream(source)); if (image null) { throw new IllegalArgumentException(无法从字节流中解析出图片); } ByteArrayOutputStream output new ByteArrayOutputStream(); // 统一输出为JPG质量参数设为0.85能有效控制体积 ImageIO.write(image, jpg, output); return output.toByteArray(); }这段代码的作用是借助ImageIO.write把图片重新编码成标准JPG字节流输出产物通常比原图小不少。我记得到4MB这个红线原因在于手机上传的原图分辨率太高一张照片可能要8MB以上Base64之后体积还会膨胀约三分之一。压缩后再调用百度接口被识别的图片虽然质量损失一点但OCR本身对JPEG压缩并不敏感识别率影响很小。4.3 现象SpringBoot版本太高导致SDK启动或调用报错很多人下载demo时会顺手选最新版SpringBoot结果一启动就遇到ClassNotFoundException: javax.servlet.*或者Tess4J内部抛出的LinkError。原因很明确从SpringBoot 3.x开始JavaEE规范迁移到了Jakarta EE原来的javax.servlet全部换成了jakarta.servlet。Tess4J 4.5.4以及不少在线OCR的旧版SDK内部还是基于javax编译的两者撞在一起就会导致类加载失败。解决方向有三条我按优先级排序。第一条如果你的目标是快速验证demo能跑直接把SpringBoot降级到2.7.xJava 8或者11都兼容这也是目前网上大多数OCR demo的默认配置。第二条如果项目必须用SpringBoot 3.x那就换一个兼容Jakarta的方案比如直接用okhttp或Spring的RestClient发起HTTP调用绕开旧SDK。第三条用mvn dependency:tree排查依赖冲突看看是谁把旧版javax.servlet-api传递进来的然后用exclusion排除掉。我实际干活时更倾向于降级SpringBoot因为OCR这个场景本身对SpringBoot新特性依赖不强没必要为了版本新而给自己挖坑。搜索热词里“springboot版本太高”能成为高频问题说明这不是个例踩坑的人比想象中多。4.4 现象识别率低数字和字母粘连成一片识别结果里明明有字但3识别成8或者O和0混在一起看起来是引擎不行其实是输入图片质量太差。OCR引擎对图片质量非常敏感尤其是手机拍的照片光照不均、背景复杂、分辨率忽高忽低都会直接把识别率打下来。Tesseract对干净的黑底白字印刷体识别率能到95%但顺手拍的模糊照片可能连60%都不到。在线API虽然抗噪能力强一些但同样不是万能。这里最直接有效的手段是做图像预处理核心是先灰度化再二值化。用Java自带的ImageIO就能实现灰度化public BufferedImage toGray(BufferedImage source) { BufferedImage gray new BufferedImage( source.getWidth(), source.getHeight(), BufferedImage.TYPE_BYTE_GRAY ); Graphics2D g gray.createGraphics(); g.drawImage(source, 0, 0, null); g.dispose(); return gray; }灰度化在很多教程里被一笔带过但它在整个OCR链路里至关重要。Tesseract内部虽然也会做预处理但自己先把图片转成灰度图等于帮引擎扫清了一部分干扰。如果灰度化之后识别率还是不理想再考虑用OpenCV做自适应阈值二值化不过那样需要在工程里引入opencv原生库复杂度会上一个台阶。4.5 现象在线OCR返回超时或限流还有一个大家容易忽略的问题是QPS限流。百度OCR免费额度是每天若干次风控比较严格你用Postman手动测试没问题但用JMeter并发跑20个请求很快会看到类似invalid access_token或者limit exceeded的报错。原因并不神秘在线接口按资源和频率计费超出配额自然会拒掉。解决思路是先确认自己用的是哪个API版本、配额是多少然后在代码里加一个简单的限流比如用RateLimiter控制每秒请求数不超过1次RateLimiter limiter RateLimiter.create(1.0); // 在调用百度接口前执行 limiter.acquire();这段代码来自我之前的实践对于小规模工具类应用刚刚好。那之后我再也没有因为超限被临时冻结过账号。识别率的问题可以调参解决但接口被限流只能等配额恢复属于那种“看着是小问题、实际能卡死整个项目”的坑。5. 进阶用法PDF转图片再识别加上curl回归才算闭环5.1 PDF转图片把识别范围从单张图片扩展到文档很多实际场景需要识别的是PDF扫描件而不是单张图片。Tesseract和百度OCR都不能直接吃PDF所以要先转成图片。这步我用pdfbox实现Maven依赖如下dependency groupIdorg.apache.pdfbox/groupId artifactIdpdfbox/artifactId version2.0.27/version /dependency转换逻辑并不复杂每页渲染成一张BufferedImage再逐页调用之前的OCR识别方法public ListString recognizePdf(InputStream pdfStream) throws IOException { ListString results new ArrayList(); try (PDDocument document PDDocument.load(pdfStream)) { PDFRenderer renderer new PDFRenderer(document); for (int page 0; page document.getNumberOfPages(); page) { BufferedImage image renderer.renderImageWithDPI(page, 200); results.add(ocrService.recognize(image)); } } return results; }注意renderImageWithDPI的DPI参数我一般设200。设太低图片模糊识别率崩设太高比如300以上内存占用会成倍增长多页PDF很容易触发OutOfMemoryError。200是一个在识别率和资源消耗之间比较平衡的值。5.2 用curl做一轮回归验证demo做完后一定要建立一套可重复的回归验证方式。我自己的习惯是保留一批固定测试图每次调整代码后跑一遍同样的curl命令对比识别结果curl -X POST \ -F file./testdata/idcard.jpg \ http://localhost:8090/ocr/extract测试图片至少有三张一张干净的印刷体截图、一张手机实拍图、一张PDF转出的首页。这三张代表了主流使用场景。如果都通过了再放真实业务图进去验证。这样能快速定位到底是我改坏了代码还是图片本身太特殊。5.3 我坚持的测试习惯刚做出OCR demo那会儿我犯过一个低级错误只拿一张清晰图片验证没问题就以为大功告成了。结果部署到测试环境第一张实际业务图就扑街——图片带背景色识别结果完全不可用。后来我养成了习惯每次接手OCR相关功能强制自己走一遍完整流程先跑离线Tesseract看基线再切在线API对比识别率最后处理图片格式和PDF场景每改一次代码就用curl回归一遍。这个习惯帮我挡住过不少低级事故也希望帮到你。本文还有配套的精品资源点击获取