OCR 识别接口文档

接口概述

本接口提供阿里云 OCR（Optical Character Recognition，光学字符识别）服务，支持多种证件和文档的智能识别，包括身份证、营业执照、食品经营许可证等。

接口路径: POST /ali/ocrRequestUrl
接口描述: 调用阿里云 OCR 识别服务，支持批量图片识别
请求方式: POST
Content-Type: application/json
登录验证: ✅ 需要

请求参数

请求体 (JSON)

参数名	类型	必填	说明	示例值
imageUrls	String	是	图片URL地址，多个用逗号分隔	`https://example.com/image1.jpg,https://example.com/image2.jpg`
ocrType	String	是	OCR识别类型	`idCard`, `businessLicense`, `foodLicense`
storeId	String	否	店铺ID（用于记录识别来源）	`103`
userId	String	否	用户ID（用于记录识别来源）	`12345`
storeUserId	String	否	店铺用户ID（用于记录识别来源）	`67890`

OCR 类型说明

ocrType 值	识别类型	说明
`idCard`	身份证识别	识别身份证正反面信息
`businessLicense`	营业执照识别	识别营业执照信息
`foodLicense`	食品经营许可证识别	识别食品经营许可证信息

请求示例

示例 1: 身份证识别（单张）

POST /ali/ocrRequestUrl
Content-Type: application/json

{
    "imageUrls": "https://example.com/idcard-front.jpg",
    "ocrType": "idCard",
    "storeId": "103",
    "userId": "12345",
    "storeUserId": "67890"
}

curl -X POST "http://localhost:8080/ali/ocrRequestUrl" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "imageUrls": "https://example.com/idcard-front.jpg",
    "ocrType": "idCard",
    "storeId": "103"
  }'

示例 2: 营业执照识别（批量）

POST /ali/ocrRequestUrl
Content-Type: application/json

{
    "imageUrls": "https://example.com/license1.jpg,https://example.com/license2.jpg",
    "ocrType": "businessLicense",
    "storeId": "103",
    "storeUserId": "67890"
}

示例 3: 食品经营许可证识别

POST /ali/ocrRequestUrl
Content-Type: application/json

{
    "imageUrls": "https://example.com/food-license.jpg",
    "ocrType": "foodLicense",
    "storeId": "103"
}

响应参数

成功响应

响应结构

{
    "code": 200,
    "success": true,
    "data": [
        {
            // OCR识别结果（根据不同类型返回不同字段）
        }
    ],
    "msg": "操作成功"
}

身份证识别响应字段

{
    "code": 200,
    "success": true,
    "data": [
        {
            "name": "张三",
            "gender": "男",
            "nationality": "汉",
            "birthDate": "19900101",
            "address": "北京市朝阳区XX街道XX号",
            "idNumber": "110101199001011234",
            "issueAuthority": "北京市公安局朝阳分局",
            "validDate": "2020.01.01-2030.01.01"
        }
    ],
    "msg": "操作成功"
}

字段说明

字段名	类型	说明
name	String	姓名
gender	String	性别
nationality	String	民族
birthDate	String	出生日期（格式：yyyyMMdd）
address	String	地址
idNumber	String	身份证号码
issueAuthority	String	签发机关（反面）
validDate	String	有效期限（反面）

营业执照识别响应字段

{
    "code": 200,
    "success": true,
    "data": [
        {
            "name": "北京XX科技有限公司",
            "creditCode": "91110000MA01ABC123",
            "legalPerson": "李四",
            "address": "北京市海淀区XX路XX号",
            "registerDate": "2020-01-01",
            "registerCapital": "100万元人民币",
            "businessScope": "技术开发、技术咨询...",
            "validPeriod": "2020-01-01至2040-01-01",
            "type": "有限责任公司",
            "establishDate": "2020-01-01"
        }
    ],
    "msg": "操作成功"
}

字段说明

字段名	类型	说明
name	String	企业名称
creditCode	String	统一社会信用代码
legalPerson	String	法定代表人
address	String	注册地址
registerDate	String	注册日期
registerCapital	String	注册资本
businessScope	String	经营范围
validPeriod	String	营业期限
type	String	企业类型
establishDate	String	成立日期

食品经营许可证识别响应字段

{
    "code": 200,
    "success": true,
    "data": [
        {
            "licenseName": "食品经营许可证",
            "businessLicenseName": "北京XX餐饮有限公司",
            "businessAddress": "北京市朝阳区XX街XX号",
            "legalPerson": "王五",
            "creditCode": "91110000MA01XYZ456",
            "businessItem": "热食类食品制售",
            "licenseNumber": "JY11234567890123",
            "validPeriod": "2020-01-01至2025-01-01",
            "issueDate": "2020-01-01",
            "issueAuthority": "北京市朝阳区市场监督管理局"
        }
    ],
    "msg": "操作成功"
}

字段说明

字段名	类型	说明
licenseName	String	许可证名称
businessLicenseName	String	经营者名称
businessAddress	String	经营场所
legalPerson	String	法定代表人（负责人）
creditCode	String	社会信用代码
businessItem	String	经营项目
licenseNumber	String	许可证编号
validPeriod	String	有效期限
issueDate	String	发证日期
issueAuthority	String	发证机关

失败响应

{
    "code": 500,
    "success": false,
    "data": null,
    "msg": "身份证识别失败" // 或其他错误信息
}

常见错误信息

错误信息	原因	解决方案
OCR识别返回结果为空	图片质量差或格式错误	上传清晰的图片
身份证识别失败	图片不是身份证或无法识别	检查图片内容
营业执照识别失败	图片不是营业执照或无法识别	检查图片内容
图片URL无法访问	图片链接失效或网络问题	检查图片URL
OCR识别异常	系统异常或参数错误	检查请求参数

业务流程

识别流程图

用户上传图片 
    ↓
前端获取图片URL
    ↓
调用 /ali/ocrRequestUrl 接口
    ↓
根据 ocrType 选择识别策略
    ↓
调用阿里云OCR服务
    ↓
解析识别结果
    ↓
保存识别记录到数据库
    ↓
返回识别结果

核心业务逻辑

参数接收: 接收图片URL列表和识别类型
策略选择: 根据 ocrType 选择对应的识别策略
批量识别: 遍历图片URL列表，逐一调用阿里云OCR
结果解析: 解析阿里云返回的JSON数据
数据存储: 保存识别结果到 ocr_image_upload 表
结果返回: 返回识别结果数组

技术实现

技术架构

Controller层 (AliController)
    ↓
Service层 (AliApi)
    ↓
策略模式 (OcrStrategy)
    ├── IdCardOcrStrategy (身份证识别)
    ├── BusinessLicenseOcrStrategy (营业执照识别)
    └── FoodManageLicenseOcrStrategy (食品许可证识别)
    ↓
阿里云OCR API

关键类说明

类名	说明	路径
AliController	控制器，接收请求	`shop.alien.store.controller.AliController`
AliApi	服务类，业务逻辑	`shop.alien.store.util.ali.AliApi`
OcrStrategy	策略接口	`shop.alien.store.util.ali.ocr.OcrStrategy`
AbstractOcrStrategy	策略抽象类	`shop.alien.store.util.ali.ocr.AbstractOcrStrategy`
IdCardOcrStrategy	身份证识别策略	`shop.alien.store.util.ali.ocr.strategy.IdCardOcrStrategy`
BusinessLicenseOcrStrategy	营业执照识别策略	`shop.alien.store.util.ali.ocr.strategy.BusinessLicenseOcrStrategy`
FoodManageLicenseOcrStrategy	食品许可证识别策略	`shop.alien.store.util.ali.ocr.strategy.FoodManageLicenseOcrStrategy`

核心代码

Controller 层

@ApiOperation("调用OCR识别接口")
@PostMapping("/ocrRequestUrl")
public R ocrRequestUrl(@RequestBody Map<String, String> params) {
    try {
        return aliApi.ocrRequestParams(params);
    } catch (Exception e) {
        return R.fail(e.getMessage());
    }
}

Service 层

public R ocrRequestParams(Map<String, String> params) throws Exception {
    // 根据 ocrType 获取对应的识别策略
    OcrStrategy strategy = ocrStrategyFactory.getStrategy(params.get("ocrType"));
    // 执行识别
    return strategy.recognizeParams(params);
}

策略实现（以身份证为例）

@Override
public R recognizeParams(Map<String, String> params) throws Exception {
    String[] imageUrls = params.get("imageUrls").split(",");
    JSONArray resultArray = new JSONArray();
    
    for (String imageUrl : imageUrls) {
        // 创建阿里云OCR客户端
        Client client = createOcrClient();
        
        // 创建识别请求
        RecognizeIdcardRequest request = new RecognizeIdcardRequest()
                .setUrl(imageUrl);
        
        // 调用识别接口
        RecognizeIdcardResponse response = client.recognizeIdcardWithOptions(
                request, new RuntimeOptions());
        
        // 解析结果
        RecognizeIdcardResponseBody body = response.getBody();
        JSONObject jsonObject = JSONObject.parseObject(body.getData());
        
        // 保存识别记录
        OcrImageUpload ocrImageUpload = new OcrImageUpload();
        ocrImageUpload.setImageUrl(imageUrl);
        ocrImageUpload.setOcrResult(jsonObject.getJSONObject("data").toJSONString());
        ocrImageUpload.setOcrType(OcrTypeEnum.ID_CARD.getCode());
        saveOcrImage(ocrImageUpload);
        
        // 添加到结果集
        resultArray.add(jsonObject.getJSONObject("data"));
    }
    
    return R.data(resultArray);
}

数据库设计

ocr_image_upload 表

OCR识别记录表，用于保存每次识别的结果。

字段名	类型	说明
id	INT	主键ID
user_id	VARCHAR	用户ID
store_id	VARCHAR	店铺ID
store_user_id	VARCHAR	店铺用户ID
image_url	VARCHAR	图片URL
ocr_result	TEXT	OCR识别结果（JSON格式）
ocr_type	VARCHAR	OCR类型
create_time	DATETIME	创建时间
update_time	DATETIME	更新时间

配置说明

阿里云 OCR 配置

在 application.yml 中配置阿里云 OCR 参数：

ali:
  ocr:
    accessKeyId: YOUR_ACCESS_KEY_ID
    accessKeySecret: YOUR_ACCESS_KEY_SECRET
    endpoint: ocr-api.cn-hangzhou.aliyuncs.com

配置项说明

配置项	说明	示例值
accessKeyId	阿里云访问密钥ID	`LTAI4G...`
accessKeySecret	阿里云访问密钥Secret	`xxx...`
endpoint	OCR服务端点	`ocr-api.cn-hangzhou.aliyuncs.com`

使用限制

图片要求

项目	要求
格式	JPG、PNG、BMP、PDF
大小	不超过 4MB
分辨率	建议大于 600x600 像素
清晰度	图片清晰，无模糊、反光
完整性	证件信息完整，无遮挡

调用限制

项目	限制
QPS限制	根据阿里云账户配置
并发数	建议不超过10个并发请求
批量数量	单次请求建议不超过5张图片

注意事项

1. 图片URL要求

⚠️ 图片URL必须可公网访问

// ✅ 正确：公网可访问的URL
"imageUrls": "https://cdn.example.com/image.jpg"

// ❌ 错误：本地路径
"imageUrls": "file:///C:/Users/image.jpg"

// ❌ 错误：内网地址
"imageUrls": "http://192.168.1.100/image.jpg"

2. 批量识别建议

⚠️ 批量识别时注意错误处理

// 当前实现：遇到错误会中断整个批量
// 建议：改进为部分失败不影响其他图片识别

3. 数据隐私

⚠️ 敏感信息处理

识别结果包含个人身份信息，需妥善保存
建议加密存储敏感字段
遵守数据保护法规

4. 成本控制

⚠️ 接口调用成本

阿里云OCR按调用次数计费
建议添加调用频率限制
避免重复识别相同图片

错误处理

异常类型

异常类型	说明	处理方式
TeaException	阿里云API异常	记录日志，返回友好提示
Exception	通用异常	记录详细日志，返回错误信息
NullPointerException	空指针异常	参数校验，防止空值

异常处理代码

try {
    // OCR识别逻辑
} catch (TeaException error) {
    log.error("OCR识别失败: code={}, message={}", 
              error.getCode(), error.getMessage());
    return R.fail("身份证识别失败");
} catch (Exception error) {
    log.error("OCR识别异常", error);
    return R.fail("身份证识别异常");
}

性能优化建议

1. 图片预处理

// 建议：上传前压缩图片
- 控制图片大小在 1MB 以内
- 分辨率调整到 1200x1200 左右
- 使用 JPG 格式（压缩率更高）

2. 异步处理

// 建议：批量识别时使用异步
@Async
public CompletableFuture<R> recognizeAsync(String imageUrl) {
    // 异步识别逻辑
}

3. 缓存机制

// 建议：相同图片不重复识别
@Cacheable(value = "ocrResult", key = "#imageUrl")
public R recognizeWithCache(String imageUrl, String ocrType) {
    // 识别逻辑
}

测试建议

测试场景

测试场景	测试目的	预期结果
正常识别	验证识别准确性	返回正确的识别结果
图片模糊	验证容错能力	返回友好错误提示
批量识别	验证批量处理	所有图片都能识别
无效URL	验证参数校验	返回错误信息
并发请求	验证并发安全	结果正确，无遗漏

测试用例

# 测试1：身份证识别
curl -X POST "http://localhost:8080/ali/ocrRequestUrl" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrls": "https://example.com/idcard.jpg",
    "ocrType": "idCard",
    "storeId": "103"
  }'

# 测试2：营业执照批量识别
curl -X POST "http://localhost:8080/ali/ocrRequestUrl" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrls": "https://example.com/license1.jpg,https://example.com/license2.jpg",
    "ocrType": "businessLicense",
    "storeId": "103"
  }'

接口路径	说明	区别
GET /ali/ocrRequest	OCR识别方式一	通过图片ID识别
POST /ali/ocrRequestByBase64	OCR识别方式二	通过Base64编码识别
POST /ali/secondClient	二手委托人识别	专用于二手业务

更新日志

v1.0 (2025-11-18)

初始版本：

✅ 支持身份证识别
✅ 支持营业执照识别
✅ 支持食品经营许可证识别
✅ 支持批量图片识别
✅ 自动保存识别记录
✅ 采用策略模式设计

开发团队：lyx

v1.1 (预计)

计划功能：

🔜 增加图片缓存机制
🔜 支持异步批量识别
🔜 增加识别结果校验
🔜 优化错误处理逻辑
🔜 增加调用频率限制

联系方式

角色	负责内容	联系方式
后端开发	接口开发与维护	-
技术负责人	技术方案审核	-
产品经理	业务需求对接	-

文档版本: v1.0
最后更新: 2025-11-28
维护人员: AI Assistant
接口状态: ✅ 已上线

OCR识别接口文档.md 16 KB Історія Запис

OCR 识别接口文档

接口概述

请求参数

请求体 (JSON)

OCR 类型说明

请求示例

示例 1: 身份证识别（单张）

示例 2: 营业执照识别（批量）

示例 3: 食品经营许可证识别

响应参数

成功响应

响应结构

身份证识别响应字段

字段说明

营业执照识别响应字段

字段说明

食品经营许可证识别响应字段

字段说明

失败响应

常见错误信息

业务流程

识别流程图

核心业务逻辑

技术实现

技术架构

关键类说明

核心代码

Controller 层

Service 层

策略实现（以身份证为例）

数据库设计

ocr_image_upload 表

配置说明

阿里云 OCR 配置

配置项说明

使用限制

图片要求

调用限制

注意事项

1. 图片URL要求

2. 批量识别建议

3. 数据隐私

4. 成本控制

错误处理

异常类型

异常处理代码

性能优化建议

1. 图片预处理

2. 异步处理

3. 缓存机制

测试建议

测试场景

测试用例

相关接口

其他 OCR 接口

更新日志

v1.0 (2025-11-18)

v1.1 (预计)

相关文档

联系方式

OCR识别接口文档.md 16 KB

Історія Запис