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 安装

pip install gradle-zap

从源码安装

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

开发环境设置

# 克隆项目
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 .

🚀 快速开始

基本用法

# 添加依赖（自动搜索最新版本）
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

镜像源管理

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

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

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

Spring Boot 项目支持

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

Ktor 项目支持

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

📋 命令详解

添加依赖 (add)

zap add <target> [options]

参数说明：

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

选项：

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

示例：

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)

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

zap try-add <target> [options]

搜索依赖 (search)

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

删除依赖 (rm)

zap rm <key> [--force]

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

列出依赖 (list)

zap list

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

同步依赖 (sync)

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 文件存储项目级配置：

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 文件了解详情。

🙏 致谢

• Typer - 现代化 CLI 框架
• Rich - 终端富文本库
• tomlkit - TOML 文件处理
• Maven Central - 依赖搜索 API

🔗 相关链接

• 项目主页
• 问题反馈
• 发布日志

---

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