216 lines
6.4 KiB
Markdown
216 lines
6.4 KiB
Markdown
# 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 |