# JF-Photo2Data

**Repository Path**: YouJunDev/JF-Photo2Data

## Basic Information

- **Project Name**: JF-Photo2Data
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **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

# 照片数据转换工具 (PhotoToData)

基于 Java8 + Swing 的可视化工具，用于将接口返回的二进制照片数据转换为 Base64 并存储到数据库。

## 技术栈

- **JDK 版本**：Java 8
- **界面框架**：Swing（Java 8 内置）
- **数据库操作**：JDBC + HikariCP 连接池（达梦数据库）
- **HTTP 请求**：OkHttp3（兼容 Java 8）
- **JSON 处理**：Jackson（兼容 Java 8）
- **Base64 编码**：Java 8 原生 `java.util.Base64`

## 功能特性

1. **可视化界面**：简洁的 Swing GUI 界面，操作方便
2. **接口调用**：支持 POST 请求调用目标接口，获取照片数据
3. **数据转换**：自动将二进制照片数据转换为 Base64 编码
4. **数据库存储**：支持 UPSERT 操作（存在即更新，不存在则插入）
5. **批量处理**：支持多个身份证号批量处理，逗号分隔
6. **实时日志**：操作日志实时输出，便于跟踪执行状态
7. **异常处理**：完善的异常处理机制，确保程序稳定运行

## 项目结构

```
PhotoToData/
├── pom.xml                                    # Maven 配置文件
├── README.md                                  # 使用说明文档
└── src/
    └── main/
        └── java/
            └── com/
                └── phototodata/
                    ├── PhotoToDataApp.java    # 主程序入口（Swing 界面）
                    ├── service/
                    │   ├── HttpService.java   # HTTP 请求服务类（OkHttp3）
                    │   └── DatabaseService.java # 数据库操作服务类
                    └── util/
                        └── ResponseParser.java # 响应解析工具类
```

## 依赖清单

### Maven 依赖

项目使用 Maven 管理依赖，主要依赖如下：

```xml
<dependencies>
    <!-- 达梦数据库驱动 -->
    <!-- 注意：达梦数据库驱动通常不在 Maven 中央仓库，需要使用 system scope -->
    <dependency>
        <groupId>com.dameng</groupId>
        <artifactId>dm-jdbc-driver</artifactId>
        <version>18.0.0</version>
        <scope>system</scope>
        <systemPath>${project.basedir}/lib/dmJdbcDriver18.jar</systemPath>
    </dependency>

    <!-- HikariCP 连接池 -->
    <dependency>
        <groupId>com.zaxxer</groupId>
        <artifactId>HikariCP</artifactId>
        <version>3.4.5</version>
    </dependency>

    <!-- OkHttp3 HTTP 客户端 -->
    <dependency>
        <groupId>com.squareup.okhttp3</groupId>
        <artifactId>okhttp</artifactId>
        <version>3.14.9</version>
    </dependency>

    <!-- Jackson JSON 处理 -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.13.5</version>
    </dependency>
</dependencies>
```

### 兼容性说明

- **Java 8 兼容**：所有依赖均兼容 Java 8
- **达梦数据库驱动**：使用 DM8 JDBC 驱动（dmJdbcDriver18.jar），兼容 Java 8 和达梦数据库 8
- **HikariCP**：使用 3.4.5 版本（Java 8 兼容的最后一个版本）
- **OkHttp3**：使用 3.14.9 版本，完全兼容 Java 8
- **Jackson**：使用 2.13.5 版本，完全兼容 Java 8
- **Swing**：Java 8 内置，无需额外配置

### 达梦数据库驱动安装

达梦数据库驱动通常不在 Maven 中央仓库中，需要手动处理：

**方法一：使用 system scope（推荐）**
1. 将 `dmJdbcDriver18.jar` 文件放到项目的 `lib` 目录下
2. 确保 `pom.xml` 中的 `systemPath` 指向正确的路径

**方法二：安装到本地 Maven 仓库**
```bash
mvn install:install-file -Dfile=dmJdbcDriver18.jar -DgroupId=com.dameng -DartifactId=dm-jdbc-driver -Dversion=18.0.0 -Dpackaging=jar
```
然后修改 `pom.xml`，移除 `scope` 和 `systemPath` 配置。

## 编译与运行

### 环境要求

- JDK 8 或以上版本
- Maven 3.6+ 或以上版本
- 达梦数据库 8（DM8）或以上版本
- 达梦数据库驱动 JAR 文件（dmJdbcDriver18.jar）

### 编译项目

```bash
# 使用 Maven 编译项目
mvn clean compile

# 打包为可执行 JAR
mvn clean package
```

### 运行程序

**方式一：使用 Maven 运行**

```bash
mvn exec:java -Dexec.mainClass="com.phototodata.PhotoToDataApp"
```

**方式二：运行打包后的 JAR**

```bash
# 打包后会生成 target/PhotoToData-1.0.0.jar
java -jar target/PhotoToData-1.0.0.jar
```

**方式三：直接运行主类**

```bash
# 先编译
mvn clean compile

# 运行
java -cp "target/classes:target/dependency/*" com.phototodata.PhotoToDataApp
```

## 数据库配置

### 创建数据表

在使用工具之前，需要确保数据库中存在 `A01_EXT2` 表，表结构如下：

```sql
CREATE TABLE A01_EXT2 (
    A0184 VARCHAR(20) PRIMARY KEY,
    IMG TEXT
);
COMMENT ON TABLE A01_EXT2 IS '照片数据扩展表';
COMMENT ON COLUMN A01_EXT2.A0184 IS '身份证号（主键）';
COMMENT ON COLUMN A01_EXT2.IMG IS 'Base64 编码的照片数据';
```

**说明**：
- `A0184` 字段作为主键或唯一键，确保身份证号唯一
- `IMG` 字段使用 TEXT 或 CLOB 类型，用于存储 Base64 编码的长字符串
- 表已存在则无需创建，程序会自动执行 UPSERT 操作

### 数据库连接配置

在工具界面中配置以下信息：

- **数据源 URL**：达梦数据库连接地址
  - 格式：`jdbc:dm://主机名:端口/数据库名`
  - 示例：`jdbc:dm://localhost:5236/DAMENG`
  - 示例：`jdbc:dm://192.168.1.100:5236/SYSDBA`
  - 默认端口：5236

- **数据库账号**：达梦数据库用户名
  - 示例：`SYSDBA`（默认管理员账号）

- **数据库密码**：达梦数据库密码
  - 密码输入框会显示为 `***`
  - 默认密码：`SYSDBA`（首次安装时）

## 接口配置

### 接口地址格式

- **目标接口地址**：完整的 HTTP/HTTPS 接口 URL
  - 示例：`http://example.com/api/photo`
  - 示例：`https://api.example.com/v1/getPhoto`

### 接口请求格式

**请求方式**：POST  
**Content-Type**：`application/json`  
**请求体格式**：

```json
{
  "data": {
    "a0184": "110101199001011234,110101199001011235"
  }
}
```

**说明**：
- `a0184` 字段值为逗号分隔的身份证号字符串
- 多个身份证号直接拼接为字符串，逗号分隔

### 接口响应格式

接口必须返回以下格式的 JSON 响应：

```json
{
  "success": true,
  "code": "200",
  "message": "操作成功",
  "data": [
    {
      "a0184": "110101199001011234",
      "message": "处理成功",
      "imageDate": "二进制照片数据（字符串形式，可能为 null/空字符串/有效二进制）"
    },
    {
      "a0184": "110101199001011235",
      "message": "照片获取成功",
      "imageDate": "..."
    }
  ]
}
```

**响应处理规则**：
- 仅处理 `success=true` 且 `code="200"` 的响应
- 其他情况会在日志中输出错误信息
- `imageDate` 为 null 或空字符串时，跳过该条数据的存储
- `imageDate` 为有效二进制数据时，转换为 Base64 并存储

## 使用说明

### 操作步骤

1. **启动程序**
   - 运行主程序后，会显示 Swing 图形化界面

2. **配置接口地址**
   - 在"目标接口地址"输入框中输入接口 URL

3. **配置数据库连接**
   - 填写"数据源 URL"（如：`jdbc:dm://localhost:5236/DAMENG`）
   - 填写"数据库账号"（如：`SYSDBA`）
   - 填写"数据库密码"（密码框会自动隐藏）

4. **输入身份证号**
   - 在"身份证号"输入框中输入要处理的身份证号
   - 多个身份证号用逗号分隔，如：`110101199001011234,110101199001011235`

5. **执行操作**
   - 点击"执行接口调用与存储"按钮
   - 程序会自动执行以下步骤：
     - 参数校验
     - 数据库连接
     - 接口请求
     - 响应解析
     - Base64 转换
     - 数据存储
     - 资源释放

6. **查看日志**
   - 在日志控制台中查看操作日志
   - 日志包含时间戳和详细操作信息
   - 自动滚动到底部显示最新日志

### 界面说明

**第一行**：目标接口地址输入区
- 左侧标签："目标接口地址："
- 右侧输入框：支持手动输入接口 URL

**第二行**：数据库连接配置区
- 数据源 URL、数据库账号、数据库密码（3 个输入框横向排列）

**第三行**：身份证号输入与执行区
- 左侧：身份证号输入框（支持多个，逗号分隔）
- 右侧：执行按钮

**第四行**：日志输出控制台
- JTextArea 组件，不可编辑，自动换行，支持滚动

### 身份证号输入规则

- **单个身份证号**：直接输入，如 `110101199001011234`
- **多个身份证号**：用逗号分隔，如 `110101199001011234,110101199001011235`
- **格式要求**：身份证号之间用英文逗号分隔，前后可以有空格（程序会自动去除）
- **示例**：
  - `110101199001011234`
  - `110101199001011234,110101199001011235`
  - `110101199001011234, 110101199001011235, 110101199001011236`

## 异常处理

程序包含完善的异常处理机制，覆盖以下场景：

1. **参数校验异常**
   - 接口地址为空
   - 数据库 URL 为空
   - 数据库账号为空
   - 身份证号为空

2. **数据库连接异常**
   - 连接失败（URL 错误、账号密码错误、数据库不存在）
   - SQL 执行异常（表不存在、字段不存在、主键冲突）

3. **接口请求异常**
   - 连接超时（30 秒）
   - 读取超时（60 秒）
   - 接口返回错误状态码
   - 响应格式错误

4. **数据转换异常**
   - Base64 编码失败
   - 二进制数据格式错误

5. **资源释放异常**
   - 数据库连接关闭失败
   - HTTP 连接关闭失败

**处理原则**：
- 异常不会导致程序崩溃
- 详细异常信息输出到日志控制台
- 明确提示用户问题所在
- 自动释放已申请的资源

## 日志说明

### 日志格式

日志输出格式：`[时间戳] 日志内容`

示例：
```
[2024-01-01 12:00:00] 程序启动成功，请配置参数后点击执行按钮。
[2024-01-01 12:00:05] ========== 开始执行任务 ==========
[2024-01-01 12:00:06] ✓ 数据库连接成功
[2024-01-01 12:00:07] 正在请求接口：http://example.com/api/photo
[2024-01-01 12:00:08] ✓ 接口请求成功，响应长度：1024 字符
```

### 日志标识

- **✓**：操作成功
- **✗**：操作失败或错误
- **⚠**：警告信息
- **==========**：任务开始/结束分隔线

### 日志内容

- **参数校验结果**：参数是否有效
- **数据库连接状态**：连接成功/失败
- **接口请求状态**：请求成功/失败，响应长度
- **响应解析结果**：解析成功/失败，数据条数
- **数据存储结果**：每条数据的存储状态（成功/失败/跳过）
- **统计信息**：总计、成功、跳过、失败数量
- **异常信息**：详细的异常堆栈信息

## 数据库操作说明

### UPSERT 操作

程序采用"存在即更新，不存在则插入"（UPSERT）策略：

- **如果身份证号（A0184）已存在**：更新 IMG 字段为新的 Base64 字符串
- **如果身份证号（A0184）不存在**：插入新记录（A0184=身份证号，IMG=Base64 字符串）

### Base64 编码说明

- **编码工具**：使用 Java 8 原生 `java.util.Base64.getEncoder()`
- **编码规则**：将二进制照片数据（字符串形式）按 ISO-8859-1 编码转换为字节数组，再编码为 Base64
- **存储格式**：Base64 编码后的字符串存储在数据库 TEXT 字段中

### 连接池配置

使用 HikariCP 连接池，配置如下：

- **最小空闲连接数**：1
- **最大连接池大小**：5
- **连接超时时间**：30 秒
- **空闲连接超时时间**：10 分钟
- **连接最大生命周期**：30 分钟
- **连接泄漏检测阈值**：60 秒

## HTTP 请求说明

### OkHttp3 配置

- **连接超时**：30 秒
- **读取超时**：60 秒
- **写入超时**：60 秒
- **请求头**：自动设置 `Content-Type: application/json` 和 `Accept: application/json`

### 请求流程

1. 构建 JSON 请求体（包含身份证号列表）
2. 创建 POST 请求
3. 发送请求并等待响应
4. 检查 HTTP 状态码
5. 读取响应体（JSON 字符串）
6. 返回响应内容

### 异常处理

- **超时异常**：自动捕获并输出友好提示
- **连接异常**：提示无法连接到服务器
- **HTTP 错误**：输出 HTTP 状态码和错误响应
- **IO 异常**：捕获并输出详细错误信息

## 常见问题

### Q1：程序启动失败

**A**：检查以下内容：
- JDK 版本是否为 Java 8 或以上
- Maven 依赖是否正确下载
- 是否缺少必要的依赖

### Q2：数据库连接失败

**A**：检查以下内容：
- 数据库 URL 格式是否正确
- 数据库服务是否启动
- 账号密码是否正确
- 数据库是否存在
- 网络连接是否正常

### Q3：接口请求超时

**A**：默认超时时间为 30 秒（连接）/ 60 秒（读取）。如果接口响应较慢，可以修改 `HttpService.java` 中的超时配置。

### Q4：Base64 转换失败

**A**：检查接口返回的 `imageDate` 字段格式是否正确。如果已经是 Base64 字符串，程序会直接使用原始数据。

### Q5：身份证号存储失败

**A**：检查以下内容：
- 表 `A01_EXT2` 是否存在
- 表结构是否正确（A0184、IMG 字段）
- 身份证号格式是否正确
- 主键约束是否冲突

### Q6：如何修改连接池配置

**A**：编辑 `DatabaseService.java` 中的 `HikariConfig` 配置参数。

### Q7：如何修改接口超时时间

**A**：编辑 `HttpService.java` 中的 `CONNECT_TIMEOUT` 和 `READ_TIMEOUT` 常量。

### Q8：Swing 界面显示异常

**A**：确保使用 Java 8 运行，Swing 是内置的，无需额外配置。如果界面显示异常，可以尝试：
- 设置系统外观：`UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName())`
- 检查屏幕分辨率和缩放设置

## 代码说明

### 关键代码位置

1. **Base64 转换**：`PhotoToDataApp.java` 第 193-209 行
   ```java
   byte[] imageBytes = imageData.getBytes("ISO-8859-1");
   base64String = java.util.Base64.getEncoder().encodeToString(imageBytes);
   ```

2. **UPSERT 操作**：`DatabaseService.java` 第 56-111 行
   ```java
   // 先查询是否存在
   // 存在则更新，不存在则插入
   ```

3. **接口请求**：`HttpService.java` 第 46-101 行
   ```java
   // 使用 OkHttp3 发送 POST 请求
   ```

4. **响应解析**：`ResponseParser.java` 第 31-60 行
   ```java
   // 解析 JSON 响应，提取 success、code、message、data 字段
   ```

5. **Swing 界面布局**：`PhotoToDataApp.java` 第 44-118 行
   ```java
   // 使用 BoxLayout 垂直排列组件
   // 使用 FlowLayout 横向排列输入框
   ```

## 版本信息

- **版本**：1.0.0
- **发布日期**：2024-01-01
- **JDK 版本**：Java 8
- **界面框架**：Swing
- **HTTP 客户端**：OkHttp3 3.14.9
- **作者**：PhotoToData Team

## 许可证

本项目仅供学习和研究使用。

## 联系方式

如有问题或建议，请联系开发团队。