# BarcodeReader1D

**Repository Path**: sushile/barcode-reader1-d

## Basic Information

- **Project Name**: BarcodeReader1D
- **Description**: 一维码识别
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-05
- **Last Updated**: 2025-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 一维码识别API（FastAPI + pyzbar）

## 项目简介
- 基于 `FastAPI` 构建的RESTful服务，整合 `OpenCV` 进行图片读取与 `pyzbar` 的一维码识别。
- 支持常见图片格式（`PNG`/`JPG`），提供结构化识别结果、错误处理与日志记录。
- 性能优化：单次识别目标500ms以内，并发友好（ASGI），内存使用控制在仅保留所需数据。

## 运行环境
- 操作系统：Windows（已适配）
- Python：3.9+（推荐）

## 快速开始
1. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```
2. 启动服务：
   ```bash
   uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 2
   ```
3. 打开文档：
   - Swagger UI: `http://localhost:8000/docs`
   - ReDoc: `http://localhost:8000/redoc`

## API说明
- 健康检查：
  - `GET /healthz`
  - 返回：`{"status": "ok"}`

- 上传识别：
  - `POST /api/v1/barcode/decode`
  - Form-Data参数：
    - `files`: 多个图片文件（`image/png`、`image/jpeg`）
  - 响应示例：
    ```json
    {
      "status": "success",
      "processing_time_ms": 123.45,
      "results": [
        {
          "status": "success",
          "time_ms": 87.12,
          "image": {
            "filename": "50060c773f013e999d513dc9cf89fad1.png",
            "content_type": "image/png",
            "width": 1024,
            "height": 720,
            "size_bytes": 345678
          },
          "barcodes": [
            {"type": "CODE128", "data": "1234567890"}
          ]
        },
        {
          "status": "failure",
          "time_ms": 92.33,
          "image": {
            "filename": "535bb47ce90bbd9cb6abb7ec8c171d01.png",
            "content_type": "image/png",
            "width": 2048,
            "height": 1200,
            "size_bytes": 789012
          },
          "barcodes": [],
          "error": "未识别到一维码"
        }
      ]
    }
    ```

## 使用示例
- cURL（多文件上传）：
  ```bash
  curl -X POST "http://localhost:8000/api/v1/barcode/decode" \
    -F "files=@c:/Users/ASUS/Desktop/one_code/50060c773f013e999d513dc9cf89fad1.png" \
    -F "files=@c:/Users/ASUS/Desktop/one_code/535bb47ce90bbd9cb6abb7ec8c171d01.png"
  ```

## 性能与并发建议
- 启动参数：`--workers 2`（根据CPU核数调整；pyzbar为CPU密集型）
- 预处理优化：大图下采样、灰度转换在识别失败时进行，兼顾精度与时延。
- I/O与CPU分离：识别在专用线程执行，不阻塞事件循环，提升并发能力。

## 日志与错误处理
- 日志文件位于 `logs/app.log`，滚动存储，便于问题排查。
- 返回结构中提供 `error` 字段，失败时可快速定位原因。

## 测试
- 运行测试：
  ```bash
  pytest -q
  ```
- 测试内容：
  - 上传两张示例图片进行识别与结构验证；
  - 保证接口稳定与响应结构完整；

## 目录结构
```
one_code/
├── app/
│   ├── main.py           # FastAPI主应用与接口
│   ├── barcode.py        # 识别服务实现（OpenCV读取 + pyzbar识别）
│   └── schemas.py        # Pydantic模型定义
├── tests/
│   └── test_api.py       # 接口测试用例
├── requirements.txt      # 依赖清单
├── README.md             # 使用说明与API文档
├── 50060c773f013e999d513dc9cf89fad1.png
└── 535bb47ce90bbd9cb6abb7ec8c171d01.png
```

## 备注
- 若Windows环境下安装`pyzbar`遇到问题，请确保已安装可用的ZBar库版本；多数情况下`pyzbar`的Windows轮子已内置所需依赖。