Java 调用 OCR 接口指南：Spring Boot 整合实战

这为后续 Java 系统的集成奠定了坚实基础。

Spring Boot 集成实战：实现 OCR 调用全流程

步骤一：搭建 Spring Boot 项目骨架

创建 Maven 项目，引入关键依赖项：

<!-- pom.xml -->
<dependencies>
 <dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
 </dependency>
 <dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-webflux</artifactId>
 </dependency>
 <dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
 </dependency>
 <dependency>
  <groupId>org.projectlombok</groupId>
  <artifactId>lombok</artifactId>
  <scope>provided</scope>
 </dependency>
</dependencies>

📌 选型说明：
使用 WebFlux 而非传统 RestTemplate，因其支持非阻塞 IO，在高并发调用 OCR 接口时可显著降低线程开销，提升吞吐量。

步骤二：定义 OCR 请求与响应实体类

// OcrRequest.java
@Data
public class OcrRequest {
 private String image; // Base64 编码字符串
}

// OcrResult.java
@Data
public class OcrResult {
 private String text;
 private Double confidence;
 private List<Integer> box;
}

// OcrResponse.java
@Data
public class OcrResponse {
 private List<OcrResult> result;
 private String message;
 private Integer code;
}

步骤三：封装 OCR 客户端服务

利用 WebClient 实现异步 HTTP 调用，支持超时控制与错误重试：

// OcrService.java
@Service
@Slf4j
public class OcrService {
 private final WebClient webClient;

 public OcrService() {
  this.webClient = WebClient.builder()
   .baseUrl("http://localhost:8080") // OCR 服务地址
   .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
   .build();
 }

 /**
  * 将图片文件转为 Base64 字符串
  */
 public String encodeImageToBase64(String imagePath) throws IOException {
  Path path = Paths.get(imagePath);
  byte[] data = Files.readAllBytes(path);
  return Base64.getEncoder().encodeToString(data);
 }

 /**
  * 异步调用 OCR 接口
  */
 public Mono<OcrResponse> recognizeText(String base64Image) {
  OcrRequest request = new OcrRequest();
  request.setImage(base64Image);
  return webClient.post()
   .uri("/ocr")
   .bodyValue(request)
   .retrieve()
   .onStatus(HttpStatus::isError, response -> Mono.error(new RuntimeException("OCR 服务返回错误状态：" + response.statusCode())))
   .bodyToMono(OcrResponse.class)
   .timeout(Duration.ofSeconds(15)) // 设置 15 秒超时
   .retryWhen(Retry.fixedDelay(2, Duration.ofSeconds(1))) // 失败重试 2 次
   .doOnSuccess(res -> log.info("OCR 识别成功，共检测到 {} 条文本", res.getResult().size()))
   .doOnError(ex -> log.error("OCR 识别失败：", ex));
 }
}

步骤四：构建 REST 控制器对外暴露服务

// OcrController.java
@RestController
@RequestMapping("/api/ocr")
@RequiredArgsConstructor
public class OcrController {
 private final OcrService ocrService;

 @PostMapping("/upload")
 public ResponseEntity<Mono<Map<String, Object>>> uploadImage(
  @RequestParam("file") MultipartFile file) {
  if (file.isEmpty()) {
   return ResponseEntity.badRequest()
    .body(Mono.just(Collections.singletonMap("error", "文件不能为空")));
  }
  try {
   // 同步读取并编码图片
   String base64Image = Base64.getEncoder()
    .encodeToString(file.getBytes());
   // 异步调用 OCR 服务
   Mono<OcrResponse> result = ocrService.recognizeText(base64Image);
   return ResponseEntity.ok(result.map(res -> {
    Map<String, Object> response = new HashMap<>();
    response.put("success", true);
    response.put("data", res.getResult());
    return response;
   }));
  } catch (IOException e) {
   log.error("文件读取失败", e);
   return ResponseEntity.status(500).body(Mono.just(
    Collections.singletonMap("error", "文件处理失败")));
  }
 }
}

步骤五：配置异步线程池与性能调优

为避免 WebFlux 默认事件循环线程被阻塞，建议自定义 Scheduler 用于文件 IO 操作：

// AppConfig.java
@Configuration
public class AppConfig {
 @Bean
 public Scheduler jdbcScheduler() {
  return Schedulers.fromExecutor(Executors.newFixedThreadPool(10));
 }
}

并在调用链中指定执行器：

.doOnNext(...).subscribeOn(jdbcScheduler())

实际测试与调用流程演示

测试准备

1. 启动 OCR 服务容器：bash docker run -p 8080:8080 your-ocr-image:latest
2. 启动 Spring Boot 应用：bash mvn spring-boot:run
3. 使用 Postman 发送 POST 请求至：POST http://localhost:8081/api/ocr/upload Content-Type: multipart/form-data Form Data: file=[选择一张含文字的图片]

预期响应示例

{
 "success": true,
 "data": [
  {
   "text": "增值税专用发票",
   "confidence": 0.97,
   "box": [102, 35, 280, 60]
  },
  {
   "text": "购买方名称：某科技有限公司",
   "confidence": 0.95,
   "box": [98, 70, 420, 95]
  }
 ]
}

常见问题与最佳实践建议

⚠️ 常见问题排查清单

✅ 工程化最佳实践

1. 添加缓存机制
   对相同图片 MD5 值的结果进行 Redis 缓存，避免重复调用。
2. 批量识别优化
   若需处理多页文档，可使用 Flux.merge() 并发调用多个图片识别任务。
3. 日志追踪增强
   在请求头中注入 traceId，实现全链路日志跟踪。
4. 降级策略设计
   当 OCR 服务不可用时，自动切换至本地规则引擎或人工审核队列。
5. 安全性加固
   校验上传文件类型（仅允许 .jpg, .png），防止恶意文件上传。

总结：构建可落地的 OCR 集成体系

本文通过一个真实可用的 CRNN OCR 服务案例，完整展示了如何在 Spring Boot 项目中实现高效、稳定的 OCR 接口调用。我们不仅完成了基础的功能集成，更深入探讨了异步编程、超时控制、重试机制和性能优化等工程细节。

这套方案的核心优势在于：

• 🔹 轻量部署：无需 GPU，可在普通服务器运行
• 🔹 高精度识别：CRNN 模型保障中文识别质量
• 🔹 易于集成：标准 REST API + JSON 交互格式
• 🔹 可扩展性强：支持 WebUI 调试与自动化调用双模式

未来可进一步拓展方向包括：

• 结合 NLP 技术实现关键字段抽取（如发票号、金额）
• 集成到工作流引擎中实现自动化审批
• 构建分布式 OCR 集群提升整体吞吐能力

🎯 最终目标不是'调通接口'，而是打造一个可靠、可观测、可持续演进的智能文档处理管道。而这一切，始于一次精准的 OCR 调用。