72 lines
2.4 KiB
Markdown
72 lines
2.4 KiB
Markdown
# 条形码识别 API 对接文档
|
||
|
||
本文档说明与 Java 后端对接的上传识别接口，返回 EAN‑13 结果；若无法识别返回明确错误提示。
|
||
|
||
## 基本信息
|
||
- 接口地址：`/api/barcode/scan`
|
||
- 请求方式：`POST multipart/form-data`
|
||
- 参数：
|
||
- `file`：图片文件（二进制）。
|
||
- 成功响应（HTTP 200）：
|
||
```json
|
||
{ "success": true, "barcodeType": "EAN13", "barcode": "6901234567892" }
|
||
```
|
||
- 失败响应（HTTP 400）：
|
||
```json
|
||
{ "success": false, "message": "无法识别，请重新上传" }
|
||
```
|
||
|
||
## 请求示例（PowerShell）
|
||
```powershell
|
||
Invoke-RestMethod -Uri http://127.0.0.1:8000/api/barcode/scan -Method Post -Form @{ file = Get-Item .\sample.jpg }
|
||
```
|
||
|
||
## 请求示例（curl）
|
||
```bash
|
||
curl -F "file=@sample.jpg" http://127.0.0.1:8000/api/barcode/scan
|
||
```
|
||
|
||
## Java 示例（Spring WebClient）
|
||
```java
|
||
WebClient client = WebClient.create("http://127.0.0.1:8000");
|
||
MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
|
||
body.add("file", new FileSystemResource(new File("sample.jpg")));
|
||
|
||
Map res = client.post()
|
||
.uri("/api/barcode/scan")
|
||
.contentType(MediaType.MULTIPART_FORM_DATA)
|
||
.body(BodyInserters.fromMultipartData(body))
|
||
.retrieve()
|
||
.onStatus(s -> s.value() == 400, r -> r.bodyToMono(String.class).map(RuntimeException::new))
|
||
.bodyToMono(Map.class)
|
||
.block();
|
||
|
||
System.out.println(res);
|
||
```
|
||
|
||
## Java 示例（Spring RestTemplate）
|
||
```java
|
||
RestTemplate rest = new RestTemplate();
|
||
HttpHeaders headers = new HttpHeaders();
|
||
headers.setContentType(MediaType.MULTIPART_FORM_DATA);
|
||
MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
|
||
body.add("file", new FileSystemResource("sample.jpg"));
|
||
HttpEntity<MultiValueMap<String, Object>> req = new HttpEntity<>(body, headers);
|
||
|
||
ResponseEntity<String> resp = rest.postForEntity("http://127.0.0.1:8000/api/barcode/scan", req, String.class);
|
||
System.out.println(resp.getStatusCode());
|
||
System.out.println(resp.getBody());
|
||
```
|
||
|
||
## 返回字段说明
|
||
- `success`：是否识别成功。
|
||
- `barcodeType`：条码类型（当前为 `EAN13`）。
|
||
- `barcode`：条码数字串。
|
||
- `message`：失败时的人类可读说明。
|
||
|
||
## 错误码
|
||
- 400：文件为空、图片解析失败、或未识别；返回 `{ success:false, message:"无法识别，请重新上传" }`。
|
||
- 413：文件过大（受 `config/config.yaml` 中 `app.server.max_upload_mb` 限制）。
|
||
|
||
|