小白也能跑通华为云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(String imgPath)throwsException{byte[] bytes=Files.readAllBytes(Paths.get(imgPath));returnBase64.getEncoder().encodeToString(bytes);}}

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

publicclassOcrOfficialSdkDemo{// 建议通过环境变量读取：HUAWEICLOUD_SDK_AK / HUAWEICLOUD_SDK_SKprivatestaticfinalString AK=System.getenv("HUAWEICLOUD_SDK_AK");privatestaticfinalString SK=System.getenv("HUAWEICLOUD_SDK_SK");// 区域：如 cn-north-4；也可改为 endpoint 方式privatestaticfinalString REGION="cn-north-4";publicstaticvoidmain(String[] args){try{// 1) 读取图片 Base64String imgBase64=Base64Util.imageToBase64("D:/tmp/demo.png");// 2) 认证与客户端BasicCredentials cred=newBasicCredentials().withAk(AK).withSk(SK);// 如使用永久 AK/SK，部分场景需填写 projectId（按控制台指引获取）// cred.withProjectId("your-project-id");HttpConfig config=HttpConfig.getDefaultHttpConfig().withTimeout(60);// 可按需调整OcrClient client=OcrClient.newBuilder().withHttpConfig(config).withCredential(cred).withRegion(OcrRegion.valueOf(REGION)).build();// 3) 组装请求（以表格识别为例，支持图片URL或Base64）RecognizeGeneralTableRequest req=newRecognizeGeneralTableRequest();GeneralTableRequestBody body=newGeneralTableRequestBody()// .withUrl("https://your-obs-url/xxx.png") // 也可传 URL.withImageBase64(imgBase64);            req.withBody(body);// 4) 发送请求RecognizeGeneralTableResponse resp= 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|RequestTimeoutException e){System.err.println("网络类异常："+ e.getMessage());}catch(ServiceResponseException e){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(String imgBase64)throwsException{Request request=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");String encode=URLUtil.encodeAll(imgBase64);        request.setBody("base64="+ encode);HttpRequestBase signedRequest=Client.sign(request);// 发送请求try(CloseableHttpClient client=HttpClients.createDefault();CloseableHttpResponse resp= client.execute(signedRequest)){int status= resp.getStatusLine().getStatusCode();if(status!=200){String body= resp.getEntity()==null?"":EntityUtils.toString(resp.getEntity(),"UTF-8");                log.error("OCR识别失败，HTTP状态码={}，响应={}", status, body);thrownewRuntimeException("OCR识别运单失败，HTTP "+ status);}HttpEntity entity= resp.getEntity();if(entity==null)thrownewRuntimeException("OCR响应体为空");String respStr=EntityUtils.toString(entity,"UTF-8");JSONObject json=JSONUtil.parseObj(respStr);int code= json.getInt("code",-1);String msg= 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 方式）。