内容
# Java 代码索引器
> JVM AST 级别的代码索引器（Java/Kotlin/Scala），使用 SQLite 存储，作为 [MCP](https://modelcontextprotocol.io/) 服务器，为 AI 编程助手提供服务。
[中文](README.zh-CN.md) | 英文
---
## 为什么
今天，AI 编程助手探索不熟悉的 JVM 项目：
| 任务 | 没有 Java 代码索引器 | 有 Java 代码索引器 |
|------|--------------------------|----------------------|
| 查找 `UserService` 的定义位置 | 在 100+ 文件中搜索（~15k tokens） | `find_symbol("UserService")` （~200 tokens） |
| 了解所有调用 `saveOrder()` 的方法 | 逐一阅读文件（~8k tokens） | `get_call_graph("saveOrder", "callers")` （~500 tokens） |
| 在 YAML/properties 中查找配置值 | 查找并读取多个配置文件（~5k tokens） | `search_config("spring.datasource.url")` （~200 tokens） |
| 查找所有依赖项 | 打开 pom.xml + 传递依赖（~3k tokens） | `find_dependencies("spring-boot-starter")` （~300 tokens） |
| 查找所有 `@RestController` 类 | 在整个代码库中搜索（~8k tokens） | `find_by_annotation("RestController")` （~200 tokens） |
| 了解接口实现 | 阅读多个文件（~5k tokens） | `find_implementations("UserService")` （~300 tokens） |
---
## 功能
### 多语言支持
| 语言 | 状态 | 解析器 |
|----------|--------|--------|
| Java | ✅ 完整支持 | JavaParser AST |
| Kotlin | ✅ 完整支持 | KotlinParserAdapter （正则表达式） |
| Scala | ✅ 完整支持 | ScalaParserAdapter （正则表达式） |
### 注解识别
支持 30+ 种注解，涵盖主要框架：
| 框架 | 注解 |
|-----------|-------------|
| Spring Boot | `@RestController`、`@Service`、`@Repository`、`@Component` |
| Spring MVC | `@RequestMapping`、`@GetMapping`、`@PostMapping`、`@DeleteMapping` |
| JPA | `@Entity`、`@Table`、`@Column`、`@Id`、`@GeneratedValue` |
| Lombok | `@Data`、`@Builder`、`@Getter`、`@Setter`、`@NoArgsConstructor` |
| 验证 | `@NotNull`、`@Size`、`@Min`、`@Max`、`@Email` |
| MyBatis | `@Mapper`、`@Select`、`@Insert`、`@Update`、`@Delete` |
| Swagger | `@Api`、`@ApiOperation`、`@ApiParam` |
| 安全 | `@EnableWebSecurity`、`@PreAuthorize`、`@Secured` |
| 缓存 | `@EnableCaching`、`@Cacheable`、`@CacheEvict`、`@CachePut` |
| 异步 | `@EnableAsync`、`@Async` |
| 调度 | `@EnableScheduling`、`@Scheduled` |
---
## 安装
需要 **Java 21+** （JRE 或 JDK）。Docker 和 Native Image 选项包含运行时。
**选项 1：从 GitHub Releases 下载（推荐）**
```bash
# Fat JAR（所有平台）
curl -LO https://github.com/Lincoln-cn/JCodeIndexer/releases/latest/download/java-code-indexer-1.5.1.jar
# Native Image（Linux）
curl -LO https://github.com/Lincoln-cn/JCodeIndexer/releases/latest/download/java-code-indexer-1.5.1-linux-amd64.tar.gz
# Native Image（macOS）
curl -LO https://github.com/Lincoln-cn/JCodeIndexer/releases/latest/download/java-code-indexer-1.5.1-darwin-arm64.tar.gz
# Native Image（Windows）
curl -LO https://github.com/Lincoln-cn/JCodeIndexer/releases/latest/download/java-code-indexer-1.5.1-windows-amd64.zip
```
**选项 2：从源代码构建** （需要 Java 21+ 和 Maven 3.8+）
```bash
git clone https://github.com/Lincoln-cn/JCodeIndexer.git
cd JCodeIndexer
mvn package -q -DskipTests
# 输出：target/java-code-indexer-*-shaded.jar
```
**选项 3：Docker**
```bash
docker pull sodlinken/jcodeindexer:latest
```
---
## 快速开始
```bash
# 1. 索引您的 JVM 项目（Java/Kotlin/Scala）
java -jar java-code-indexer-1.5.1.jar --project-root /path/to/your/project --index
# 2. 启动 MCP 服务器（stdio，用于 Claude Code / Qwen Code / Cursor）
java -jar java-code-indexer-1.5.1.jar --project-root /path/to/your/project
```
就这样。您的 AI 助手现在可以查询您的代码库结构，而不是读取文件。
---
## CLI 参考
```
java -jar java-code-indexer-VERSION.jar [选项]
选项：
--project-root <path> JVM 项目根目录（默认：当前目录）
--data-dir <path> 索引数据目录（默认：.jindexer）
--init 仅初始化数据库模式
--index 运行索引器（提取符号/引用/调用）
--status 显示索引统计信息
--search <query> 直接搜索（不需要 MCP 服务器）
--export <file> 将索引数据导出到 JSON 文件
--version 显示版本号
--help, -h 显示帮助
无标志 → 通过 stdio 启动 MCP 服务器。
```
---
## MCP 工具（15 种工具）
当作为 MCP 服务器运行时，Java 代码索引器会暴露这些工具：
| 工具 | 描述 |
|------|-------------|
| `find_symbol` | 按名称查找符号（类/方法/字段），支持 `*` 通配符 |
| `find_references` | 查找符号的所有引用位置 |
| `get_call_graph` | 方法调用图 — 调用者、被调用者或两者 |
| `search_code` | 搜索符号名称和代码内容（FTS5 全文检索） |
| `get_file_info` | 文件详细信息：符号、代码块、调用关系 |
| `search_config` | 搜索配置文件（YAML / 属性文件 / .env） |
| `find_dependencies` | 搜索项目依赖项（Maven / Gradle） |
| `health` | 服务器健康检查，包含状态和统计信息 |
| `list_projects` | 列出索引项目（仅多项目模式） |
| `search_all_projects` | 跨所有项目搜索（多项目模式） |
| `find_implementations` | 查找实现接口的所有类 |
| `find_overrides` | 查找子类中的所有方法重写 |
| `find_usages` | 查找字段/变量的所有用法 |
| `find_annotations` | 查找符号上的所有注解 |
| `find_by_annotation` | 查找具有特定注解的符号 |
---
## 配置
在项目根目录创建 `.jindexer/config.yaml` （可选）：
```yaml
# 项目根目录（CLI --project-root 覆盖此设置）
project_root: /path/to/project
# 数据目录
data_dir: .jindexer
# 索引线程数
indexing_threads: 4
# 最大文件大小（KB）
max_file_size_kb: 512
# 排除目录
exclude_dirs:
- "**/target/**"
- "**/build/**"
- "**/node_modules/**"
# 多项目模式
projects:
- name: backend
root: /path/to/backend
- name: frontend
root: /path/to/frontend
```
### 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `INDEXER_THREADS` | 索引线程数 | `4` |
| `INDEXER_LOG_LEVEL` | 日志级别 | `INFO` |
优先级：CLI 标志 → 环境变量 → 配置文件 → 默认值。
---
## AI 助手集成
### Claude Code / Cursor / Qwen Code
添加到您的 MCP 配置中：
```json
{
"mcpServers": {
"java-code-indexer": {
"command": "java",
"args": ["-jar", "/path/to/java-code-indexer-1.5.1.jar", "--project-root", "/path/to/project"]
}
}
}
```
### Docker 集成
```json
{
"mcpServers": {
"java-code-indexer": {
"command": "docker",
"args": ["run", "--rm", "-i", "-v", "/path/to/project:/project", "sodlinken/jcodeindexer:latest", "--project-root", "/project"]
}
}
}
```
---
## 工作原理
```
┌──────────────┐ MCP（stdio） ┌──────────────────────┐
│ AI 助手 │ ◄─────────────────► │ Java 代码索引器 │
│ （Qwen/Claude）│ JSON-RPC │ │
└──────────────┘ │ ┌────────────────┐ │
│ │ 解析器： │ │
│ │ JavaParser │ │
│ │ KotlinParser │ │
│ │ ScalaParser │ │
│ └───────┬────────┘ │
│ ▼ │
│ ┌────────────────┐ │
│ │ SQLite（WAL） │ │
│ │ 符号 │ │
│ │ 引用 │ │
│ │ 调用图 │ │
│ │ 注解 │ │
│ │ 配置文件 │ │
│ │ 依赖项 │ │
│ └────────────────┘ │
└──────────────────────┘
```
### 索引策略
1. 通过文件系统遍历遍历 JVM 源文件（Java/Kotlin/Scala）
2. SHA-1 内容哈希跳过未更改的文件（增量）
3. 解析器提取符号、引用、调用关系和注解
4. POM/Gradle 解析器提取依赖信息
5. 配置文件解析器提取 YAML/属性文件/.env 条目
6. 所有数据插入嵌入式 SQLite（WAL 模式）
7. FTS5 全文搜索索引通过触发器自动同步
### 数据库模式
八个核心表：
- **`symbols`** — 类、方法、字段，包含位置和签名
- **`references`** — 代码库中符号的使用位置
- **`calls`** — 方法调用关系（调用者 → 被调用者）
- **`annotations`** — 符号注解，包含属性
- **`chunks`** — 类/方法级别的代码块
- **`file_meta`** — 增量索引的 SHA-1 哈希
- **`config_entries`** — YAML/属性文件/.env 键值对
- **`dependencies`** — Maven/Gradle 依赖声明
另外还有 FTS5 全文搜索表（`symbols_fts`、`chunks_fts`）和自动同步触发器。
---
## 架构
```
src/main/java/com/sodlinken/jindexer/
├── cli/ # CLI 入口点
├── mcp/ # MCP 服务器（JSON-RPC over stdio）
├── config/ # YAML 配置加载器
├── storage/ # SQLite 模式和 StorageService（包括 FTS5）
├── indexer/ # 增量索引引擎
├── parser/ # Java、Kotlin、Scala、POM、Gradle、配置文件解析器
├── chunker/ # 代码块（类/方法切片）
├── search/ # 结构化搜索（FTS5 全文检索）
├── model/ # 数据模型（Symbol、Call、Chunk、Annotation 等）
└── util/ # SHA-1 哈希实用工具
```
---
## 分发
### GitHub 发布
发布工作流通过 GitHub Actions 自动执行：
| 工件 | 描述 |
|----------|-------------|
| `java-code-indexer-VERSION.jar` | Fat JAR，需要 Java 21+ |
| `java-code-indexer-VERSION-linux-amd64.tar.gz` | Linux amd64 原生镜像 |
| `java-code-indexer-VERSION-darwin-arm64.tar.gz` | macOS arm64 原生镜像 |
| `java-code-indexer-VERSION-windows-amd64.zip` | Windows amd64 原生镜像 |
| `docker-image-VERSION.tar.gz` | Docker 离线镜像 |
| `checksums-VERSION.sha256` | SHA-256 校验和 |
---
## 开发
```bash
# 克隆并构建
git clone https://github.com/Lincoln-cn/JCodeIndexer.git
cd JCodeIndexer
mvn package -q -DskipTests
# 运行测试
mvn test
# 索引该项目本身
java -jar target/java-code-indexer-*-shaded.jar --project-root . --index
# 启动 MCP 服务器
java -jar target/java-code-indexer-*-shaded.jar --project-root .
```
### 发布工作流
GitHub Actions 自动发布流程：
1. 推送 `v*` 标签或手动触发
2. 构建 Fat JAR
3. 构建原生镜像（Linux amd64、macOS arm64、Windows amd64）
4. 构建 Docker 镜像
5. 创建 GitHub 发布并上传工件
```bash
# 创建发布标签
git tag v1.5.1
git push origin v1.5.1
```
---
## 测试
```bash
# 运行所有测试（246+ 测试）
mvn test
# 运行特定测试类
mvn test -Dtest=JavaParserAdapterTest
# 运行性能基准测试
mvn test -Dtest=PerformanceBenchmarkTest
```
---
## 它不是什么
- 不是代码执行沙盒
- 不是测试运行器或校验器
- 不是 LSP/IDE 功能的替代品
- 不是 AI 生成的摘要（符号提取是确定性的）
## 许可证
[Apache License 2.0](LICENSE)
