小白也能跑通华为云OCR：手把手整合 Hutool 与华为云签名 SDK 并解决依赖难题

小白也能跑通华为云OCR：手把手整合 Hutool 与华为云签名 SDK 并解决依赖难题

如果你喜欢我的回答或想获取更多有趣、有用的内容，
欢迎关注微信公众号：云技纵横 ，
这样就能及时看到我的更新啦～ 😊 你的支持是我前进的动力！

一、两种调用方式总览

• 方式A 官方通用 SDK（推荐，长期可维护）
  • 使用华为云官方Java SDK（huaweicloud-sdk-ocr），通过AK/SK认证，支持设置Region/Endpoint、代理、超时、SSL 等，异常体系完善，适合生产环境。
• 方式B 签名 SDK + Hutool（你当前写法）
  • 使用华为云网关签名 SDK 的Client.sign对请求签名，配合Hutool/HttpClient发送表单请求，灵活可控，但需自行解决签名 JAR 的依赖托管。

二、方式A 官方通用 SDK 完整示例（推荐）

• 适用场景：通用 OCR、表格、票据、证件等；依赖少、升级方便、可维护性强。
• Maven 依赖（示例版本，可按需升级）

<dependencies><!-- 华为云 OCR SDK --><dependency><groupId>com.huaweicloud</groupId><artifactId>huaweicloud-sdk-ocr</artifactId><version>3.1.12</version></dependency><!-- JSON 工具（可选） --><dependency><groupId>cn.hutool</groupId><artifactId>hutool-json</artifactId><version>5.8.22</version></dependency></dependencies>

• 读取图片为 Base64 的工具方法

publicclassBase64Util{publicstaticStringimageToBase64(StringimgPath)throwsException{byte[]bytes=Files.readAllBytes(Paths.get(imgPath));returnBase64.getEncoder().encodeToString(bytes);}}

• 调用通用 OCR 表格识别（RecognizeGeneralTable），并抽取关键字段

publicclassOcrOfficialSdkDemo{// 建议通过环境变量读取：HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SKprivatestaticfinalStringAK=System.getenv("HUAWEICLOUD_SDK_AK");privatestaticfinalStringSK=System.getenv("HUAWEICLOUD_SDK_SK");// 区域：如 cn-north-4；也可改为 endpoint 方式privatestaticfinalStringREGION="cn-north-4";publicstaticvoidmain(String[]args){try{// 1) 读取图片 Base64StringimgBase64=Base64Util.imageToBase64("D:/tmp/demo.png");// 2) 认证与客户端BasicCredentialscred=newBasicCredentials().withAk(AK).withSk(SK);// 如使用永久 AK/SK，部分场景需填写 projectId（按控制台指引获取）// cred.withProjectId("your-project-id");HttpConfigconfig=HttpConfig.getDefaultHttpConfig().withTimeout(60);// 可按需调整OcrClientclient=OcrClient.newBuilder().withHttpConfig(config).withCredential(cred).withRegion(OcrRegion.valueOf(REGION)).build();// 3) 组装请求（以表格识别为例，支持图片URL或Base64）RecognizeGeneralTableRequestreq=newRecognizeGeneralTableRequest();GeneralTableRequestBodybody=newGeneralTableRequestBody()// .withUrl("https://your-obs-url/xxx.png") // 也可传 URL.withImageBase64(imgBase64);req.withBody(body);// 4) 发送请求RecognizeGeneralTableResponseresp=client.recognizeGeneralTable(req);System.out.println("OCR 调用成功：\n"+resp.toString());// 5) 业务字段抽取示例（按实际接口返回结构调整）// 通用表格接口返回结构不同，请参考控制台 API 文档解析// Map<String, Object> result = resp.getResult();// String tableStr = JSONUtil.toJsonStr(result);// System.out.println("抽取结果：\n" + tableStr);}catch(ConnectionException|RequestTimeoutExceptione){System.err.println("网络类异常："+e.getMessage());}catch(ServiceResponseExceptione){System.err.println("服务响应异常：");System.err.println("HTTP状态码="+e.getHttpStatusCode());System.err.println("错误码="+e.getErrorCode());System.err.println("错误信息="+e.getErrorMsg());}}}

• 说明
  • 认证支持永久 AK/SK或临时 AK/SK + SecurityToken；客户端可指定Region或Endpoint；可配置代理/超时/SSL；异常分为连接类与响应类，便于定位问题。

三、方式B 签名 SDK + Hutool 完整示例（当前写法，含依赖安装脚本）

• 适用场景：必须使用网关签名 SDK（如某些联营/专享环境）。
• 安装签名 SDK 到本地或私有仓库（只需一次）

# 将 java-sdk-core-3.2.4.jar 放到当前目录后执行mvn install:install-file\-Dfile=java-sdk-core-3.2.4.jar\-DgroupId=com.huaweicloud.apigateway\-DartifactId=java-sdk-core\-Dversion=3.2.4\-Dpackaging=jar

• Maven 依赖（示例）

<dependencies><!-- Hutool 工具 --><dependency><groupId>cn.hutool</groupId><artifactId>hutool-all</artifactId><version>5.8.22</version></dependency><!-- Apache HttpClient --><dependency><groupId>org.apache.httpcomponents</groupId><artifactId>httpclient</artifactId><version>4.5.14</version></dependency><!-- 华为云网关签名 SDK（已本地安装或私有仓库托管） --><dependency><groupId>com.huaweicloud.apigateway</groupId><artifactId>java-sdk-core</artifactId><version>3.2.4</version></dependency></dependencies>

• 工具类

publicclassHuaweiCloudOcr{publicHashMap<String,String>identifyWaybill(StringimgBase64)throwsException{Requestrequest=newRequest();request.setKey(appKey);request.setSecret(appSecret);request.setMethod("POST");request.setUrl("https://jmexpressbill.apistore.huaweicloud.com/ocr/express-bill");request.addHeader("Content-Type","application/x-www-form-urlencoded");Stringencode=URLUtil.encodeAll(imgBase64);request.setBody("base64="+encode);HttpRequestBasesignedRequest=Client.sign(request);// 发送请求try(CloseableHttpClientclient=HttpClients.createDefault();CloseableHttpResponseresp=client.execute(signedRequest)){intstatus=resp.getStatusLine().getStatusCode();if(status!=200){Stringbody=resp.getEntity()==null?"":EntityUtils.toString(resp.getEntity(),"UTF-8");log.error("OCR识别失败，HTTP状态码={}，响应={}",status,body);thrownewRuntimeException("OCR识别运单失败，HTTP "+status);}HttpEntityentity=resp.getEntity();if(entity==null)thrownewRuntimeException("OCR响应体为空");StringrespStr=EntityUtils.toString(entity,"UTF-8");JSONObjectjson=JSONUtil.parseObj(respStr);intcode=json.getInt("code",-1);Stringmsg=json.getStr("msg","未知错误");}}}

• 说明
  • 表单字段名必须为base64；对 Base64 做URL 编码更稳妥；签名前后请求方法、URL、Headers、Body 必须保持一致；建议统一用UTF-8解析响应。

四、常见问题与排查清单

• 依赖找不到
  • 签名 SDK 未发布到公共仓库时，先本地安装（install:install-file）或上传到私有仓库；确保groupId/artifactId/version与代码一致；必要时清理~/.m2/repository后重试。
• 403/签名失败
  • 核对appKey/appSecret；确认请求方法、URL、Headers、Body 与签名前完全一致；确认Base64 已 URL 编码；检查系统时间偏差（部分签名算法依赖时间）。
• 返回非 200
  • 打印完整请求与响应（含 Headers/Body）；核对Content-Type: application/x-www-form-urlencoded；确认字段名为base64；图片过大时按接口限制压缩或改用 URL 传图（若支持）。
• 图片过大或格式不符
  • 优先压缩至接口支持范围；确认格式为常见类型（如 JPG/PNG）；必要时先上传到OBS获取临时 URL 再识别（部分接口支持 URL 方式）。