# jetifier转换工具

**Repository Path**: meda/jetfier-tool

## Basic Information

- **Project Name**: jetifier转换工具
- **Description**: jetifier转换小工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-22
- **Last Updated**: 2025-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Jetifier转换工具项目说明文档

---

## 1. 项目概述

### 1.1 项目名称及背景
**项目名称**：Jetifier转换工具  
**背景**：本项目旨在为 Android 开发者提供一个自动化的支持库到 AndroidX 的迁移服务。通过后端服务，用户可上传 jar/aar/zip 文件，自动完成兼容性转换，并支持批量处理和高并发场景。

### 1.2 项目目标和价值
- 自动化完成 Android 支持库到 AndroidX 的迁移，减少人工操作。
- 支持多种文件格式和批量处理，提升开发效率。
- 提供限流排队、动态预计时间、超时处理等高可用特性，保障服务稳定性。

### 1.3 项目范围和边界
- 范围：文件上传、转换、下载、批量处理、任务状态查询。
- 边界：仅处理 Android 支持库相关文件，不涉及业务代码迁移；任务数据仅临时存储于内存。

---

## 2. 功能需求

### 2.1 核心功能模块描述
- **文件上传模块**（`upload`、`batch_upload`）：支持单文件和批量上传，自动识别格式并处理。
- **转换处理模块**：调用 Jetifier Java 工具进行 AndroidX 迁移，异步任务执行。
- **下载模块**（`download`、`download_batch`）：支持单文件和批量下载，自动打包 zip。
- **任务管理模块**：任务状态跟踪、限流排队、动态预计时间、超时处理。
- **限流与排队模块**：最大并发限制、自动排队、队列状态反馈。

### 2.2 各功能点的详细逻辑说明

#### 上传流程
- 接口：`POST /upload`，`POST /batch_upload`
- 支持 jar/aar/zip 格式，zip 自动解包并逐个处理。
- 每个文件生成唯一任务ID，状态可查询。
- 并发受限时自动排队，返回队列状态 JSON（包含排队序号、队列长度、预计等待时间等）。

#### 下载流程
- 接口：`GET /download/{job_id}`，`GET /download_batch?ids=...`
- 支持单文件和批量下载，自动打包 zip。
- 并发受限时自动排队，返回队列状态 JSON。

#### 排队与限流
- 最大并发数通过信号量控制（如 `user_semaphore` 字段）。
- 排队队列通过 Mutex 保护，保证线程安全和 FIFO 公平。
- 动态预计时间通过 `TimeWindow` 结构体滑动窗口统计。
- 超时自动移除队列（如 `cleanup_queue` 方法），返回 429/503 错误。
- 任务完成后自动唤醒队首请求（如 `wakeup_next` 方法）。

### 2.3 输入/输出参数定义

#### 上传接口
- 输入：`multipart/form-data`，字段 `file` 或 `files[]`
- 输出：JSON `{ job_id, status, download_url }`

#### 下载接口
- 输入：`GET /download/{job_id}` 或 `GET /download_batch?ids=...`
- 输出：文件流或 zip 包，失败返回 JSON 错误信息。

#### 状态查询
- 输入：`GET /status/{job_id}`
- 输出：JSON `{ job_id, status, progress, error }`

### 2.4 业务规则和约束条件
- 文件大小限制（如 100MB）。
- 任务超时自动清理（如 10分钟，`QUEUE_TIMEOUT_SECONDS`）。
- 并发数和队列长度可配置（如 `WINDOW_SIZE`）。
- 仅支持 Android 支持库相关文件。

---

## 3. 系统架构

### 3.1 技术栈说明
- 后端：Rust + Axum
- Jetifier核心：Java（通过命令行调用 jar 包）
- 并发控制：tokio + 信号量 + Mutex
- 数据结构：任务队列（VecDeque）、滑动窗口统计（`TimeWindow`）

### 3.2 系统组件图
```mermaid
graph TD
    Client -->|HTTP| API[Jetifier Server API]
    API -->|上传| Upload[上传模块]
    API -->|下载| Download[下载模块]
    API -->|状态| Status[任务管理模块]
    Upload -->|调用| Jetifier[Jetifier核心]
    Download -->|文件| FS[文件系统]
    Status -->|队列| Queue[限流排队模块]
```

### 3.3 数据流示意图
```mermaid
sequenceDiagram
    participant U as 用户
    participant S as Server
    participant J as Jetifier
    U->>S: 上传文件
    S->>S: 入队/限流
    S->>J: 调用 Jetifier 转换
    J-->>S: 返回转换结果
    S->>U: 返回任务ID和下载链接
    U->>S: 下载文件
    S->>S: 入队/限流
    S->>U: 返回文件/zip包
```

---

## 4. 接口规范

### 4.1 内部模块接口定义
- `AppState`：管理信号量、队列、任务状态、滑动窗口。
- `TimeWindow`：动态统计任务处理时长。
- `enqueue/dequeue`：队列操作，线程安全。
- `cleanup_queue`：超时清理。
- `wakeup_next`：自动唤醒队首。

### 4.2 外部系统接口协议

#### 上传接口
- `POST /upload`
    - Content-Type: multipart/form-data
    - 参数：file
    - 返回：JSON

#### 批量上传
- `POST /batch_upload`
    - Content-Type: multipart/form-data
    - 参数：files[]
    - 返回：JSON

#### 下载接口
- `GET /download/{job_id}`
    - 返回：文件流

#### 批量下载
- `GET /download_batch?ids=...`
    - 返回：zip包

#### 状态查询
- `GET /status/{job_id}`
    - 返回：JSON

### 4.3 API文档规范
- 所有接口均返回标准 HTTP 状态码。
- 错误信息采用统一 JSON 格式：`{ code, message }`
- 支持 CORS，方便前端集成。

---

## 5. 非功能性需求

### 5.1 性能指标
- 单节点最大并发：可配置（如 10~100，`WINDOW_SIZE` 控制滑动窗口，信号量控制并发）。
- 平均任务处理时长：< 5秒（取决于文件大小，`TimeWindow` 统计）。
- 排队预计时间动态反馈，滑动窗口统计。

### 5.2 安全要求
- 文件类型校验，防止恶意上传。
- 临时文件自动清理，防止磁盘占满。
- API鉴权（可扩展）。

### 5.3 兼容性说明
- 支持主流浏览器和 HTTP 客户端。
- 支持 jar/aar/zip 格式。
- 兼容 AndroidX 和 Support 包相关库。

---

**代码关键点说明：**
- `src/bin/server.rs` 文件实现了所有核心接口和限流排队逻辑。
- `AppState` 结构体集中管理信号量、队列、任务状态和滑动窗口。
- `TimeWindow` 用于动态预计时间反馈，`WINDOW_SIZE` 控制统计窗口长度。
- `QUEUE_TIMEOUT_SECONDS` 控制队列超时自动清理。
- 所有接口均实现了最大并发限制、自动排队、队列状态反馈、自动唤醒和超时处理，保证系统公平性和健壮性。

---

## 6. 跨平台构建

- 一键脚本：
  - 主机平台构建（默认）：
    ```bash
    bash scripts/build-all.sh --host-only
    ```
  - 全平台构建（推荐安装 cargo-zigbuild + zig，本地交叉编译）：
    ```bash
    # macOS:
    brew install zig
    cargo install cargo-zigbuild

    # Linux:
    sudo apt-get update && sudo apt-get install -y zig || true
    cargo install cargo-zigbuild

    # 运行全平台构建
    bash scripts/build-all.sh --all
    ```
- 构建产物：输出到 `dist/` 目录，形如：
  - `jetifier-x86_64-unknown-linux-gnu.tar.gz`
  - `jetifier-aarch64-apple-darwin.tar.gz`
  - `jetifier-x86_64-pc-windows-gnu.tar.gz`
- 归档内容：包含后端二进制 `jetifier`、`resources/jetifier` 资源目录、`README.md` 与 `API文档.md`。

## 7. CI 工作流

- GitHub Actions 已添加：`.github/workflows/cross-build.yml`
- 支持以下矩阵：
  - Linux: gnu + musl (x86_64 / aarch64，使用 cross)
  - macOS: x86_64 / aarch64（原生 cargo）
  - Windows: x86_64 msvc（原生 cargo）
- 触发条件：`push` 与 `workflow_dispatch`
- 产物：在 Actions 页面可下载对应归档包。