# Java代码健康分析器

`Java` `代码审查` `AI` `静态分析` `安全检测`

# Java Doctor

<p align="center">
  <a href="https://github.com/ajaywadhara/java-doctor/releases/latest">
    <img src="https://img.shields.io/github/v/release/ajaywadhara/java-doctor?include_prereleases&label=version" alt="版本">
  </a>
  <a href="https://opensource.org/licenses/MIT">
    <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="许可证">
  </a>
  <a href="https://github.com/ajaywadhara/java-doctor/stargazers">
    <img src="https://img.shields.io/github/stars/ajaywadhara/java-doctor" alt="Stars">
  </a>
</p>

**AI 驱动的 Java 代码健康分析器**，扫描安全、性能、正确性和架构问题。输出 0-100 分的评分及可操作的诊断建议，自动检测涵盖 22 个类别的 280+ 条规则。

## 概述

Java Doctor 是一个 AI 驱动的代码审查技能，用于分析 Java 项目中的问题。它自动检测项目所用技术（Spring Boot、gRPC、JPA、Lombok）并按需加载相关规则。

**280+ 条规则**，覆盖 22 个类别——从安全漏洞到虚拟线程陷阱，再到深度测试检查。

支持主流 AI 编程助手：

| 助手 | 支持方式 |
|-------|---------|
| Claude Code | 原生（skills） |
| Cursor | 原生（skills） |
| KiloCode | 原生（skills） |
| GitHub Copilot | 通过自定义指令 |
| Windsurf | 原生（skills） |

## 快速开始

```bash
# 通过 skills CLI 安装（推荐）
npx skills add ajaywadhara/java-doctor

# 或手动克隆
git clone https://github.com/ajaywadhara/java-doctor.git

# 复制到 AI 助手的 skills 目录
# Claude Code / Cursor / KiloCode：
cp -r java-doctor ~/.claude/skills/
# 或
cp -r java-doctor ~/.cursor/skills/
# 或
cp -r java-doctor ~/.kilocode/skills/
```

激活技能后说：**"运行 Java Doctor"**

## 功能特性

### 280+ 条规则，覆盖 22 个类别

| 技术 | 检测条件 | 规则数 |
|-----------|----------|-------|
| 核心 | 始终 | 108 条（安全、空值安全、性能、并发等） |
| Spring Boot | `spring-boot-starter-parent` | +23 条 |
| gRPC | `grpc-java` | +26 条 |
| JPA/Hibernate | `hibernate`、`spring-data-jpa` | +15 条 |
| Lombok | `lombok` | +5 条 |
| 构建工具 | 始终 | +20 条 |
| 虚拟线程 | 检测到 Java 21+ | +10 条（synchronized 钉死、ScopedValue、StructuredTaskScope） |
| 测试深度 | 始终 | +10 条（JaCoCo、Testcontainers、Awaitility、AssertJ） |
| 死代码 | 始终 | +15 条 |
| Effective Java | 始终 | +37 条（版本感知，Java 8-25） |
| 最佳实践 | 始终 | +15 条 |
| API 设计 | 始终 | +11 条 |

### 版本检测
- **Java**：从 pom.xml/build.gradle 自动检测 8-25 版本
- **Spring Boot**：自动检测 3.x 或 4.x

### 评分标准
- **75-100**：优秀 - 可投入生产
- **50-74**：需改进 - 处理警告项
- **0-49**：危急 - 必须修复阻塞问题

### 输出格式
- Markdown（默认）
- JSON
- HTML
- SARIF（IDE 集成）
- CSV

## 使用方式

```
"运行 Java Doctor"
"检查我的 Java 代码"
"查找代码中的安全问题"
"扫描性能问题"
"分析这个 Java 项目"
```

## 触发短语

- `run java doctor`
- `scan my java code`
- `java code review`
- `find bugs in java`
- `check for security issues in java`
- `find performance problems`
- `analyze java code`

## 规则类别（280+ 条）

| 类别 | 加载时机 | 描述 |
|----------|------------|-------------|
| 安全（16条） | 始终 | 硬编码密钥、SQL 注入、OWASP Top 10 |
| 空值安全（8条） | 始终 | Optional.get()、空值返回 |
| 异常处理（8条） | 始终 | 被吞掉的异常 |
| 性能（12条） | 始终 | N+1 查询、字符串拼接 |
| 并发（12条） | 始终 | 线程安全 |
| 资源管理（7条） | 始终 | 未关闭的流、连接 |
| 架构（10条） | 始终 | 上帝类、过长方法 |
| 日志（7条） | 始终 | System.out、敏感数据 |
| 代码风格（35条） | 始终 | 格式化、命名规范 |
| Effective Java（37条） | 始终 | 版本感知（Java 8-25） |
| 最佳实践（15条） | 始终 | 魔法数字、命名、复杂度 |
| API 设计（11条） | 始终 | REST 规范、分页 |
| 测试（8条） | 始终 | 缺少测试、断言 |
| 测试深度（10条） | 始终 | JaCoCo、Testcontainers、Awaitility、AssertJ |
| 死代码（15条） | 始终 | 未使用的方法、字段、导入 |
| 虚拟线程（10条） | Java 21+ | synchronized 钉死、ScopedValue、StructuredTaskScope |
| Spring/Boot（23条） | 检测到时 | @Transactional、Boot 4.x |
| gRPC（26条） | 检测到时 | Channel 复用、TLS |
| JPA（15条） | 检测到时 | Hibernate 问题 |
| Lombok（5条） | 检测到时 | 实体上的 @Data、@Builder 默认值 |
| 构建工具（20条） | 始终 | 依赖、插件 |

## 项目结构

```
java-doctor/
├── SKILL.md              # 主技能定义（280+ 条规则）
├── CHANGELOG.md          # 版本历史
├── LICENSE               # MIT 许可证
├── README.md             # 本文件
└── references/           # 详细参考资料
    ├── bug-patterns.md
    ├── security-checklist.md
    ├── performance-antipatterns.md
    ├── spring-best-practices.md
    ├── effective-java-mapping.md
    ├── version-specific-changes.md
    ├── grpc-best-practices.md
    ├── virtual-threads-guide.md
    └── testing-depth-guide.md
```

## 面向 AI 助手开发者

### 工具要求
请根据您的助手适配以下工具：

- **Bash**：执行 git 命令、运行分析
- **Read**：读取源文件
- **Write**：生成报告
- **Glob**：查找 Java 文件
- **Grep**：搜索模式
- **question**：向用户寻求澄清

### Token 用量
- **启动**：约 100 tokens（元数据）
- **激活**：约 4,000 tokens（核心规则 + 检测到的技术）
- **参考资料**：约 20,000 tokens（按需加载）

## 输出示例

```markdown
# Java Doctor 报告

## 摘要
| 指标 | 值 |
|--------|-------|
| 评分 | 75/100 |
| 状态 | 需改进 |
| Java 版本 | 17 |
| 分析文件数 | 12 |
| 问题 | 严重: 2, 错误: 3, 警告: 8 |

## 问题
### 安全（严重）
1. AuthService.java:42 - 硬编码密码
   修复：使用 @Value 注入
```

## 贡献

1. Fork 本仓库
2. 创建功能分支
3. 提交 PR

## Skills 市场

### skills.sh

通过 CLI 安装：
```bash
npx skills add ajaywadhara/java-doctor
```

## 许可证

MIT 许可证 - 详见 LICENSE 文件

## 作者

Ajay Wadhara