基于 LangChain 与 Java 框架构建 GitHub Actions 智能代码审查服务

在真实项目中，静态代码分析工具（如Checkstyle、PMD）是保障代码规范的第一道防线，但它们的能力边界非常明确。它们能检查出格式错误、未使用的变量或固定的坏味道（Bad Smells），却无法理解代码的业务意图、设计模式的合理性或是否遵循了团队在文档中约定的高级架构原则。这些深层次的审查工作，至今仍高度依赖资深工程师投入大量时间进行人工Code Review，这个过程不仅是研发流程中的瓶颈，其效果也因人而异。

问题的核心是，如何自动化那些需要“理解力”的审查任务？这引出了我们的技术挑战：构建一个能够理解团队内部编码规范、安全指南和最佳实践文档，并基于此对Pull Request中的代码变更提出具体、上下文感知建议的自动化系统。

定义复杂技术问题

我们的目标是创建一个无人值守的Code Review服务，它作为CI/CD流程的一部分，在每次提交Pull Request时自动运行。该服务需要具备以下核心能力：

1. 上下文感知：它不仅仅是分析代码本身，还需要结合我们内部知识库（例如，Markdown格式的《XX系统安全编码手册》、《API设计规范》）进行分析。
2. 深度分析：能够识别出逻辑漏洞、潜在的性能陷阱、不符合推荐设计模式的代码，而不仅仅是语法层面的问题。
3. 无缝集成：必须与GitHub Actions无缝集成，将审查意见以评论（Comment）的形式直接反馈到Pull Request中。
4. 可维护与可扩展：核心审查逻辑应独立于CI工具，易于本地测试、迭代和扩展，避免将复杂的业务逻辑硬编码在CI的YAML脚本中。

方案A：纯脚本化GitHub Action与LLM API直连

第一种思路是尽可能保持简单，将所有逻辑都放在GitHub Actions的Workflow脚本中。

• 实现路径：

  1. 在Workflow YAML文件中，增加一个job。
  2. 使用actions/checkout检出代码。
  3. 通过执行git diff命令，提取出本次PR的代码变更部分。
  4. 将代码变更和预设的、硬编码在脚本中的审查指令（Prompt）拼接成一个大的文本块。
  5. 使用curl命令，直接调用大语言模型（如OpenAI的API），并将上一步的文本作为请求体发送。
  6. 解析返回的JSON，提取审查意见。
  7. 使用actions/github-script或类似的action，调用GitHub API将意见发布为PR评论。

• 优势分析：

  • 部署简单：所有逻辑都在一个.yml文件中，无需额外部署和维护服务。
  • 无基础设施成本：除了LLM的API调用费用，没有服务器或容器的固定开销。

• 劣势分析：

  • 逻辑脆弱且难以维护：复杂的Prompt工程、数据处理和API交互逻辑用Shell脚本或curl参数来表达，会变得极其混乱和脆弱。在真实项目中，一个好的Prompt可能长达数百行，包含复杂的指令和示例，这在YAML中难以管理。
  • 上下文处理能力弱：最致命的缺陷在于，它无法有效实现检索增强生成（RAG）。我们无法在Action运行时动态地从一个向量数据库中检索与代码变更最相关的知识库片段。最多只能将少量静态规则塞进Prompt，但这远远达不到“理解”内部文档的要求。
  • 安全风险：将LLM的API密钥作为GitHub Secrets暴露给CI runner，增加了密钥泄露的风险。任何有权限修改Workflow的人都可能接触到它。
  • 测试困难：对脚本的调试和测试非常痛苦，必须通过一次次提交和运行Action来验证，效率极低。

方案B：GitHub Action + 外部Java微服务（集成LangChain）

第二种方案是将CI流程与核心审查逻辑解耦。GitHub Action只负责触发和通信，而真正的智能分析由一个独立的、用Java框架构建的微服务来完成。

• 实现路径：

  1. Java微服务：
     • 使用Spring Boot构建一个RESTful服务。
     • 集成LangChain4j库来处理与LLM的交互、Prompt模板和RAG流程。
     • 在服务启动时，加载内部知识库文档（.md文件），通过Embedding模型将其向量化，并存入一个向量数据库（可以是内存中的InMemoryEmbeddingStore用于快速原型，或生产中的Weaviate、Pinecone等）。
     • 提供一个API端点，例如/api/v1/review，接收代码变更作为输入。
     • API内部实现RAG流程：首先将代码变更向量化，从向量数据库中检索最相关的N个知识库片段，然后将代码变更和这些片段一起填充到精心设计的Prompt模板中，最后调用LLM生成审查意见。
  2. GitHub Action：
     • Workflow的逻辑变得非常简单。
     • 提取git diff。
     • 使用curl向部署好的Java微服务发送一个POST请求，请求体中包含代码变更。
     • 接收服务返回的审查意见，并将其发布到PR评论。

• 优势分析：

  • 关注点分离：CI流程（GitHub Actions）和业务逻辑（Java服务）清晰分离。CI专家可以专注于优化Workflow，而AI和后端工程师可以专注于审查服务的算法和性能。
  • 强大的上下文处理能力：Java服务可以轻松实现成熟的RAG架构。我们可以管理一个持久化的、可动态更新的向量数据库，这是实现高质量、上下文感知审查的关键。
  • 可维护性与可测试性：Java服务是一个标准的Spring Boot应用，我们可以为其编写单元测试、集成测试，并且可以在本地轻松调试。逻辑的迭代和重构遵循标准的软件工程实践。
  • 安全性更高：LLM的API密钥被安全地存储在后端服务的配置中（例如，通过KMS加密或云平台的Secrets Manager），绝不会暴露给CI环境。
  • 健壮性与扩展性：可以利用Java生态的优势，例如使用Resilience4j处理对LLM API的调用失败（重试、熔断），使用Micrometer进行监控，并且服务本身可以水平扩展以应对高并发的审查请求。

• 劣劣分析：

  • 架构复杂性增加：需要额外部署和维护一个微服务，这涉及到容器化、服务发现、日志收集等一系列运维工作。
  • 引入网络延迟：CI runner与审查服务之间的网络调用会增加整个流程的执行时间。

最终选择与理由

对于一个严肃的、期望在团队中长期使用的工具而言，方案B是唯一可行的选择。方案A的简单性是一种假象，一旦需求变得复杂（例如，需要支持多种审查策略、管理多个知识库），它将迅速演变成一个无法维护的“脚本泥潭”。

选择方案B，本质上是选择了一个专业、可持续演进的架构。前期增加的部署复杂性，将会在后期的功能迭代、问题排查和系统稳定性上获得百倍的回报。在真实项目中，可维护性和可测试性永远是比初期部署速度更重要的考量因素。

核心实现概览

以下是方案B的核心代码实现和架构概览。

整体架构流程

sequenceDiagram
    participant User
    participant GitHub
    participant GitHub Action Runner
    participant ReviewService as Java (Spring Boot + LangChain4j)
    participant VectorDB
    participant LLM_API as Large Language Model (e.g., OpenAI)

    User->>+GitHub: Push commit & Create Pull Request
    GitHub->>+GitHub Action Runner: Trigger workflow
    GitHub Action Runner->>GitHub Action Runner: git diff --unified=0 HEAD~1
    GitHub Action Runner->>+ReviewService: POST /api/v1/review (body: {diffContent: "..."})
    ReviewService->>+VectorDB: Search relevant documents based on diffContent
    VectorDB-->>-ReviewService: Return top-K document chunks
    ReviewService->>ReviewService: Construct final prompt with diff & documents
    ReviewService->>+LLM_API: Send chat completion request
    LLM_API-->>-ReviewService: Return review suggestions
    ReviewService-->>-GitHub Action Runner: 200 OK (body: {review: "..."})
    GitHub Action Runner->>+GitHub: Post comment to Pull Request via API
    GitHub-->>-User: Show AI-generated comment on PR

1. GitHub Actions Workflow (.github/workflows/ai-code-review.yml)

这个文件负责编排整个流程。

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 2 # Need at least 2 commits to diff

      - name: Get code changes
        id: get_diff
        run: |
          # The diff is generated against the base of the pull request
          # Using environment variables provided by GitHub Actions
          git fetch origin ${{ github.base_ref }}
          DIFF=$(git diff --unified=0 origin/${{ github.base_ref }} ${{ github.sha }})
          # Escape characters for JSON and limit size
          DIFF=$(echo "$DIFF" | jq -sRr @json)
          echo "diff_content=${DIFF}" >> $GITHUB_OUTPUT

      - name: Call AI Review Service
        id: call_review_api
        run: |
          API_URL="${{ secrets.REVIEW_SERVICE_ENDPOINT }}"
          API_KEY="${{ secrets.REVIEW_SERVICE_API_KEY }}"
          
          # Prepare the JSON payload
          JSON_PAYLOAD=$(jq -n --arg diff "${{ steps.get_diff.outputs.diff_content }}" '{codeDiff: $diff}')

          # Call the service and capture response
          # We add a timeout and retry logic for robustness
          RESPONSE=$(curl -s -X POST "$API_URL" \
               -H "Content-Type: application/json" \
               -H "X-API-Key: $API_KEY" \
               --data "$JSON_PAYLOAD" \
               --connect-timeout 10 \
               --max-time 180) # 3 minutes timeout for LLM generation

          # Check for empty response or errors
          if [ -z "$RESPONSE" ]; then
            echo "::error::API response was empty."
            exit 1
          fi

          # The response content is passed to the next step
          echo "api_response=${RESPONSE}" >> $GITHUB_OUTPUT
        
      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const apiResponse = JSON.parse('${{ steps.call_review_api.outputs.api_response }}');
            const reviewComment = `### 🤖 AI Code Review\n\n${apiResponse.reviewText}`;
            
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: reviewComment
            });

• 关键点：
  • fetch-depth: 2 确保我们能获取到前一个commit来进行比较。
  • git diff 的目标是PR的基准分支，这比HEAD~1更可靠。
  • 使用jq来正确地将多行diff内容转义为单行JSON字符串，这是脚本中最容易出错的地方。
  • API的URL和认证密钥都通过GitHub Secrets管理，而不是硬编码。
  • actions/github-script 提供了一个便捷的方式来调用GitHub API，比手动curl更优雅。

2. Java审查服务 (Spring Boot)

这是系统的“大脑”。

Maven依赖 (pom.xml)

<dependencies>
    <!-- Spring Boot -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>

    <!-- LangChain4j -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j</artifactId>
        <version>0.25.0</version>
    </dependency>
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-open-ai</artifactId>
        <version>0.25.0</version>
    </dependency>
    
    <!-- In-memory vector store for demonstration -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-embeddings-all-minilm-l6-v2</artifactId>
        <version>0.25.0</version>
    </dependency>
</dependencies>

配置 (application.yml)

langchain4j:
  openai:
    chat-model:
      api-key: ${OPENAI_API_KEY} # Use environment variable for security
      model-name: gpt-4-turbo-preview
      temperature: 0.2
      max-tokens: 1500
      log-requests: true
      log-responses: true

knowledge:
  base:
    path: "classpath:knowledge-base/*.md" # Load all markdown files from resources

server:
  port: 8080

知识库加载与向量化

服务启动时，需要将文档加载到向量数据库。

import dev.langchain4j.data.document.Document;
import dev.langchain4j.data.document.DocumentSplitter;
import dev.langchain4j.data.document.loader.FileSystemDocumentLoader;
import dev.langchain4j.data.document.parser.TextDocumentParser;
import dev.langchain4j.data.document.splitter.DocumentSplitters;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.store.embedding.EmbeddingStoreIngestor;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.Resource;
import org.springframework.core.io.support.PathMatchingResourcePatternResolver;

import java.io.IOException;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;

@Configuration
public class KnowledgeBaseConfig {

    @Value("${knowledge.base.path}")
    private String knowledgeBasePath;

    @Bean
    public EmbeddingStoreIngestor embeddingStoreIngestor(EmbeddingStore<TextSegment> embeddingStore, EmbeddingModel embeddingModel) throws IOException {
        // 1. Define document splitter for chunking
        DocumentSplitter splitter = DocumentSplitters.recursive(300, 50);
        
        // 2. Create ingestor
        EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
                .documentSplitter(splitter)
                .embeddingModel(embeddingModel)
                .embeddingStore(embeddingStore)
                .build();
        
        // 3. Load documents from classpath
        PathMatchingResourcePatternResolver resolver = new PathMatchingResourcePatternResolver();
        Resource[] resources = resolver.getResources(knowledgeBasePath);
        List<Document> documents = Stream.of(resources)
                .map(resource -> {
                    try {
                        return FileSystemDocumentLoader.loadDocument(resource.getFile().toPath(), new TextDocumentParser());
                    } catch (IOException e) {
                        // In a real app, use a proper logger
                        System.err.println("Failed to load resource: " + resource.getFilename());
                        return null;
                    }
                })
                .filter(Objects::nonNull)
                .collect(Collectors.toList());

        // 4. Ingest documents into the store
        ingestor.ingest(documents);
        System.out.println("Knowledge base ingested successfully. Number of segments: " + embeddingStore.size());
        
        return ingestor;
    }
}

核心审查服务与AI Agent接口

使用LangChain4j的AiServices可以非常声明式地定义一个Agent。

// DTOs for API
public record ReviewRequest(@NotBlank String codeDiff) {}
public record ReviewResponse(String reviewText) {}

// The AI Agent Interface
interface CodeReviewAgent {
    @SystemMessage("""
        You are a senior Java software architect and a security expert. Your task is to review the provided code diff.
        Be extremely precise and objective. Only raise issues that are real problems.
        Refer to the provided internal guidelines to justify your comments.
        Structure your feedback in Markdown format. If there are no issues, respond with "No issues found.".
        
        Internal Guidelines for context:
        ---
        {{guidelines}}
        ---
    """)
    String reviewCode(@UserMessage String codeDiff);
}

// The Service implementation
@Service
@RequiredArgsConstructor
public class CodeReviewService {

    private final EmbeddingStore<TextSegment> embeddingStore;
    private final EmbeddingModel embeddingModel;
    private final ChatLanguageModel chatModel;
    private static final Logger log = LoggerFactory.getLogger(CodeReviewService.class);

    public ReviewResponse performReview(ReviewRequest request) {
        try {
            // 1. Create a retriever to find relevant documents
            ContentRetriever retriever = EmbeddingStoreContentRetriever.builder()
                    .embeddingStore(embeddingStore)
                    .embeddingModel(embeddingModel)
                    .maxResults(3) // Retrieve top 3 most relevant chunks
                    .minScore(0.6) // Filter out irrelevant results
                    .build();

            // 2. Retrieve relevant context from knowledge base
            List<Content> relevantContents = retriever.retrieve(Content.from(request.codeDiff()));
            String guidelines = relevantContents.stream()
                    .map(content -> ((TextSegment) content.contents()).text())
                    .collect(Collectors.joining("\n\n---\n\n"));
            
            if(guidelines.isEmpty()) {
                log.warn("No relevant guidelines found for the provided diff.");
                guidelines = "No specific guidelines found. Please perform a general review.";
            }

            // 3. Build the agent with dynamic context
            CodeReviewAgent agent = AiServices.builder(CodeReviewAgent.class)
                    .chatLanguageModel(chatModel)
                    .tools(retriever) // Although we manually retrieve, it can be useful for the model
                    .build();
            
            // This is a simplified way to pass context. In a more complex scenario,
            // you might use a custom prompt template.
            String review = agent.reviewCode(String.format(
                "Code Diff to Review:\n```diff\n%s\n```", 
                request.codeDiff()
            ));

            return new ReviewResponse(review);

        } catch (Exception e) {
            log.error("Error during AI code review", e);
            // In a real application, you'd have more sophisticated error handling
            throw new RuntimeException("Failed to get review from AI service.", e);
        }
    }
}

• 关键设计：
  • RAG实现：CodeReviewService中的performReview方法是RAG的核心。它接收diff，使用ContentRetriever从EmbeddingStore中查找相关的文档片段。
  • 动态Prompt：@SystemMessage定义了LLM的角色和行为。我们将检索到的文档动态注入到Prompt中，为LLM提供了做出高质量判断所需的上下文。
  • 解耦：CodeReviewAgent接口清晰地定义了AI的能力，与底层的模型（OpenAI、Gemini等）和Prompt工程细节解耦。

架构的扩展性与局限性

当前方案提供了一个坚实的基础，但仍有其边界和未来迭代的方向。

扩展性:

1. 多语言支持: 通过为不同语言配置不同的知识库和Prompt模板，该服务可以扩展到支持Python、Go等其他语言。
2. 反馈回路: 可以在PR评论中加入“👍/👎”按钮。通过GitHub Webhooks捕获这些反馈，用于评估审查质量，甚至可以收集数据来微调（Fine-tune）一个专有模型。
3. 分层审查: 可以根据代码变更的模块或风险等级，动态选择不同的审查模型或知识库。例如，对于安全相关的代码，使用更严格的审查Prompt和安全知识库。

局限性:

1. 成本问题: LLM API调用是按Token计费的。在一个频繁提交代码的团队中，这可能是一笔不小的开支。需要实施缓存策略（例如，对相同的代码变更不再重复审查）或在非高峰期批量处理。
2. 延迟: 完整的RAG+LLM调用链可能会耗时30秒到数分钟，这会延长CI的整体运行时间。需要对用户有明确的预期管理，并持续优化服务性能。
3. 幻觉与不确定性: LLM的输出不是确定性的。它可能会“幻觉”出不存在的问题，或者遗漏真正的问题。因此，这个服务应被定位为“资深工程师的智能助手”，而不是完全替代人类审查。它的意见是建议，而非强制命令。
4. 上下文窗口限制: 对于涉及大量文件和代码行的巨型PR，拼接后的Prompt可能会超出模型的上下文窗口限制。需要实现更复杂的逻辑，如对diff进行分块处理、对每个文件单独审查后进行总结，或者使用具有更大上下文窗口的模型。