我用Java与Spring Boot构建AI代码审查器的经验总结

AI 辅助编程改变了开发者编写软件的速度。

但这又带来了另一个问题：

如何有效地审查所有生成的代码？

这个问题促使我构建了 CodeGuard AI，一个使用 Java 和 Spring Boot、面向 GitHub Pull Request 的自托管 AI 代码审查应用。

起初，架构看起来很简单：

GitHub Pull Request
        ↓
      LLM
        ↓
      审查

但在实践中，这还不够。有趣的工程工作在于模型周边的一切：收集有用的 Pull Request 上下文、定义审查指令、结构化模型响应、评估发现项，以及将结果集成回 GitHub 工作流。本文解释了我在构建该工作流时学到的东西。真正的问题不是调用 LLM。从 Spring Boot 应用调用 AI 提供商相对直接。更难的问题是：模型究竟应该接收什么，应用又应该如何处理响应？

一个 Pull Request 包含的有用信息远不止一块变更代码。

一个审查工作流可能涉及：

• Pull Request 元数据
• 变更文件
• 代码 diff
• 审查指令
• 仓库信息
• 分析规则
• 所选的 AI 提供商
• 模型响应

因此工作流变成：

GitHub PR
   ↓
获取 PR 上下文
   ↓
构建审查上下文
   ↓
应用审查指令
   ↓
AI 提供商
   ↓
解析响应
   ↓
结构化发现项
   ↓
风险 / 严重性 / 置信度
   ↓
GitHub 审查

模型只是系统的一部分。构建 GitHub 集成。第一个主要组件是 GitHub 集成。应用需要获取 Pull Request 信息以及需要审查的变更。

从概念上看，工作流如下：

仓库
    ↓
Pull Request
    ↓
变更文件
    ↓
Diff
    ↓
审查上下文

这里重要的设计决策是：审查器不应盲目地把整个仓库发送给模型。相反，应用可以从 Pull Request 中实际包含的变更开始，并围绕这些变更构建上下文。这会让审查更聚焦，并避免把整个代码库都视为与每次审查同等相关。把 diff 转化为审查上下文。原始 diff 不一定足以让 AI 给出有用的反馈。应用还需要指令，告诉模型它应执行哪种审查。

例如，审查指令可以要求模型查找：

• Bug 和逻辑问题
• 安全问题
• 性能问题
• 最佳实践违规

重要的区别在于：是把代码发送给 LLM，还是为 LLM 构建审查上下文。第二种方法让应用能更好地控制审查的执行方式。支持多个 AI 提供商。CodeGuard AI 的设计目标之一是避免工作流依赖单一的 AI 提供商。

该应用支持：

• OpenAI
• Google Gemini
• Ollama

这在审查工作流和提供商之间创建了一层抽象。

概念上：

                 ┌── OpenAI
                 │
审查工作流 ─────┼── Gemini
                 │
                 └── Ollama

因此，应用可以让 GitHub 和审查工作流相对独立于模型提供商。这也让实验更容易。不同的提供商可能产生不同结果，而当本地运行模型很重要时，像 Ollama 这样的自托管选项会很有用。原始 AI 输出还不够。这是这个项目最大的经验之一。AI 模型可以返回一段很长的文本响应，解释若干可能的问题。但审查 Pull Request 的开发者不一定想要又一大块文本。

他们需要知道：

• 发现项是什么？
• 它在哪里？
• 它有多严重？
• 分析的置信度如何？
• 可以怎么处理？

因此，审查工作流会把模型响应转换为结构化发现项。

一个简化的发现项可以看作：

发现项
├── 类型
├── 严重性
├── 置信度
├── 位置
├── 解释
└── 建议修复

这改变了 AI 响应的角色。它不再是最终产物，而是面向开发者的审查工作流的输入。为什么严重性和风险很重要。AI 模型可能识别出十个可能的问题。但这并不意味着这十个问题都应得到同等关注。因此，一个有用的审查系统需要某种区分发现项的方法。

例如：

• 严重（CRITICAL）
• 高（HIGH）
• 中（MEDIUM）
• 低（LOW）

其他信息也有帮助：

• 严重性
• 风险
• 置信度
• 发现项类型
• 代码位置

目标不是让 AI 做最终决定。目标是让开发者的审查更聚焦。

工作流变成：

10 个 AI 发现项
      ↓
结构化发现项
      ↓
风险 / 严重性 / 置信度
      ↓
按优先级审查
      ↓
人工决策

这种区分很重要。AI 初审并不意味着 AI 最终决策。把结果发送回 GitHub。当审查融入开发者现有的工作流时，它会变得有用得多。CodeGuard AI 无需开发者打开单独的应用并手动把发现项复制到 GitHub，而是可以把审查结果直接发布回 Pull Request。

由此产生的工作流如下：

开发者打开 PR
        ↓
CodeGuard 分析变更
        ↓
AI 生成发现项
        ↓
发现项被结构化
        ↓
审查发布到 GitHub
        ↓
开发者评估发现项

这让 GitHub 成为可以消费审查结果的地方。独立的仪表盘则可以提供额外信息，例如审查历史和趋势。Spring Boot 这一侧。Spring Boot 提供连接这些部分的应用层。

从高层看，应用承担以下职责：

GitHub 集成
       ↓
审查编排
       ↓
AI 提供商集成
       ↓
发现项处理
       ↓
持久化
       ↓
仪表盘 / API

Spring Security 处理身份验证和授权相关事项，Spring Data/JPA 提供持久层，Maven 管理 Java 项目依赖和构建生命周期。最终得到的不仅仅是一次 AI API 调用，而是围绕该 API 调用构建的完整应用工作流。应用真正有趣的地方。这个项目最有趣的部分并不是选择调用哪个 LLM，而是决定模型调用前后会发生什么。

模型之前：

GitHub
  ↓
PR 变更
  ↓
审查上下文
  ↓
指令

模型之后：

AI 响应
  ↓
结构化发现项
  ↓
严重性 / 风险 / 置信度
  ↓
GitHub 审查
  ↓
开发者决策

大部分应用工程工作正存在于这个周边工作流中。AI 代码审查仍然无法解决的问题。构建这个审查器也让我更清楚地看到了它的局限。AI 审查器可以识别许多有用的问题，但它不会自动理解系统背后的每一条业务规则。例如，一个 Pull Request 在技术上可能有效，却违反了可用上下文中未体现的、组织特有的业务需求。这意味着 AI 审查应被视为初审分析，而不是不容置疑的权威。

人工审查仍然重要，尤其是在以下方面：

• 业务关键逻辑
• 安全敏感的变更
• 财务工作流
• 架构决策
• 组织特定规则

因此，AI 审查的质量不仅取决于模型，还取决于提供给它的上下文和指令。自托管改变了设计。另一个重要的设计考虑是部署。CodeGuard AI 被设计为自托管应用，而不是托管的代码审查 SaaS。这意味着开发者可以在自己的基础设施上运行该应用，并自定义源代码。

因此架构可以是这样：

GitHub
   ↓
自托管 CodeGuard
   ↓
AI 提供商
   ↓
审查结果
   ↓
GitHub

使用 Ollama 时，模型也可以在本地运行：

GitHub
   ↓
CodeGuard
   ↓
Ollama
   ↓
本地模型
   ↓
审查发现项

这并不会自动解决所有安全或隐私问题，但它让开发者能更好地控制应用和 AI 工作流的运行位置。如果重新构建，我会改变什么。这个项目也改变了我对 AI 开发者工具的看法。如果重新开始，我会在 AI 输出与应用逻辑之间的边界上投入更多时间。模型会变，提供商会变，提示词会变。但应用仍然需要一个稳定的工作流，把不确定的模型输出转化为开发者可以检查和行动的内容。这提示我们采用一种架构：AI 提供商可替换，而审查工作流保持相对稳定。主要经验。构建 CodeGuard AI 的最大经验很简单：AI 代码审查并不只是 PR → LLM → 审查。

有用的系统更接近：

Pull Request
     ↓
上下文
     ↓
审查指令
     ↓
AI 提供商
     ↓
结构化发现项
     ↓
风险 / 严重性 / 置信度
     ↓
GitHub 工作流
     ↓
人工决策

LLM 很重要，但围绕它的工程工作才是把 AI 响应变成开发者工具的关键。这就是我用 Java 和 Spring Boot 构建 AI 代码审查器时觉得最有趣的地方。

关于 CodeGuard AI

CodeGuard AI 是一个自托管的 AI 代码审查应用，使用 Java 17+ 和 Spring Boot 构建。它支持 OpenAI、Gemini 和 Ollama，可以分析 GitHub Pull Request 中的 Bug、安全问题、性能问题和最佳实践违规。完整源代码可供希望运行、自定义和扩展该应用的开发者使用。在 Gumroad 上查看 CodeGuard AI。