gradle-zap 0.1.0
轻量级 Gradle 依赖管理 CLI
Requires Python: >=3.10

# Zap - 轻量级 Gradle 依赖管理 CLI

Zap 是一个现代化的 Gradle 依赖管理工具，旨在简化 Java/Kotlin 项目中的依赖添加、搜索和管理流程。它通过智能化的版本目录（Version Catalog）管理和 Maven Central 搜索集成，为开发者提供流畅的依赖管理体验。

## ✨ 特性

- 🚀 **智能依赖搜索** - 集成 Maven Central 搜索，支持模糊匹配和版本推荐
- 📋 **版本目录管理** - 自动生成和维护 `gradle/libs.versions.toml` 文件
- 🔧 **Gradle 构建文件集成** - 自动更新 `build.gradle(.kts)` 文件
- 🎯 **内置别名映射** - 常用库的智能别名（Jackson、Gson、OkHttp、Retrofit 等）
- 🌐 **镜像源支持** - 支持 Maven Central 和阿里云镜像
- 🎨 **现代化 CLI** - 基于 Typer 的友好命令行界面，支持富文本输出
- 🔍 **模糊搜索匹配** - 支持 artifact 名称和 group 的智能搜索
- 📦 **版本管理** - 支持版本引用和集中版本管理

## 📦 安装

### 使用 pip 安装

```bash
pip install gradle-zap
```

### 从源码安装

```bash
git clone <repository-url>
cd zap
pip install -e .
```

### 开发环境设置

```bash
# 克隆项目
git clone <repository-url>
cd zap

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或
.venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 安装项目
pip install -e .
```

## 🚀 快速开始

### 基本用法

```bash
# 添加依赖（自动搜索最新版本）
zap add com.fasterxml.jackson.core:jackson-databind

# 使用内置别名快速添加
zap add jackson

# 指定版本添加
zap add com.squareup.okhttp3:okhttp:4.12.0

# 自定义别名
zap add com.google.code.gson:gson --alias google_json

# 搜索依赖
zap search retrofit

# 列出所有依赖
zap list

# 删除依赖
zap rm jackson
```

### 镜像源管理

```bash
# 查看可用镜像
zap search-mirror list

# 切换到阿里云镜像
zap search-mirror use aliyun

# 恢复默认镜像
zap search-mirror reset
```

### Spring Boot 项目支持

```bash
# 添加 Spring Boot 相关依赖
zap spring add web
zap spring add data-jpa
zap spring add security
```

### Ktor 项目支持

```bash
# 添加 Ktor 相关依赖
zap ktor add server-core
zap ktor add serialization
zap ktor add auth
```

## 📋 命令详解

### 添加依赖 (`add`)

```bash
zap add <target> [options]
```

**参数说明：**
- `target`: 依赖标识，支持多种格式：
  - `group:artifact[:version]` - 完整的 GAV 坐标
  - `artifact[:version]` - 仅 artifact 名称（自动搜索 group）
  - `alias:version` - 已存在别名的版本覆盖

**选项：**
- `--alias, -a <name>` - 自定义别名
- `--limit, -l <num>` - 搜索结果数量限制（默认：20）
- `--force, -f` - 强制覆盖已存在的依赖

**示例：**
```bash
zap add jackson                           # 使用内置别名
zap add okhttp:4.12.0                    # 仅指定 artifact 和版本
zap add com.squareup.retrofit2:retrofit  # 完整 GAV
zap add gson --alias google_json         # 自定义别名
```

### 试运行 (`try-add`)

在不修改文件的情况下预览添加结果：

```bash
zap try-add <target> [options]
```

### 搜索依赖 (`search`)

```bash
zap search <artifact> [--limit <num>]
```

### 删除依赖 (`rm`)

```bash
zap rm <key> [--force]
```

支持模糊匹配和精确匹配，可以删除 catalog 中的依赖或直接依赖。

### 列出依赖 (`list`)

```bash
zap list
```

显示项目中所有的依赖，包括版本目录中的和直接写在构建文件中的。

### 同步依赖 (`sync`)

```bash
zap sync [--gradlew <path>] [--args <args>]
```

调用 Gradle Wrapper 触发依赖下载和同步。

## 🏗️ 项目结构

```
zap/
├── zap/
│   ├── __init__.py          # 包入口和版本信息
│   ├── cli.py               # 主要 CLI 命令实现
│   ├── catalog.py           # 版本目录管理
│   ├── gradle.py            # Gradle 构建文件操作
│   ├── maven.py             # Maven Central API 集成
│   ├── config.py            # 配置文件管理
│   ├── types.py             # 数据类型定义
│   ├── spring.py            # Spring Boot 支持
│   └── ktor.py              # Ktor 支持
├── main.py                  # 程序入口
├── pyproject.toml           # 项目配置
└── README.md               # 项目文档
```

## 🔧 核心技术

- **CLI 框架**: Typer - 现代化的 Python CLI 框架
- **构建工具**: Python 3.14+ with setuptools
- **依赖管理**: tomlkit (TOML 文件操作), requests (HTTP 请求)
- **富文本输出**: rich - 终端富文本和漂亮格式化
- **类型安全**: 完整的类型注解支持

## 🎯 内置别名

Zap 提供常用库的预置别名映射：

| 别名 | 完整坐标 | 说明 |
|------|----------|------|
| `jackson` | `com.fasterxml.jackson.core:jackson-databind` | JSON 处理库 |
| `gson` | `com.google.code.gson:gson` | Google JSON 库 |
| `okhttp` | `com.squareup.okhttp3:okhttp` | HTTP 客户端 |
| `retrofit` | `com.squareup.retrofit2:retrofit` | REST 客户端 |

## 🔍 智能搜索

Zap 的搜索功能支持：

1. **精确匹配** - 完全匹配 group、artifact 或别名
2. **模糊匹配** - 子字符串匹配，不区分大小写
3. **版本推荐** - 基于使用频率和稳定性推荐版本
4. **多源搜索** - 支持 Maven Central 和阿里云镜像

## ⚙️ 配置文件

Zap 使用 `.zaprc` 文件存储项目级配置：

```toml
search_base = "https://maven.aliyun.com/repository/central"
```

## 🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

### 开发建议

- 遵循 PEP 8 编码规范
- 添加完整的类型注解
- 编写单元测试
- 更新文档和 README

## 📝 许可证

本项目基于 MIT 许可证开源 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [Typer](https://typer.tiangolo.com/) - 现代化 CLI 框架
- [Rich](https://rich.readthedocs.io/) - 终端富文本库
- [tomlkit](https://github.com/sdispater/tomlkit) - TOML 文件处理
- Maven Central - 依赖搜索 API

## 🔗 相关链接

- [项目主页](https://github.com/your-username/zap)
- [问题反馈](https://github.com/your-username/zap/issues)
- [发布日志](https://github.com/your-username/zap/releases)

---

**Zap** - 让 Gradle 依赖管理变得简单高效！