使用Knative和Kotlin构建事件驱动的LLM自动化代码审查服务

团队的代码审查（Code Review）流程总是卡在同一个瓶颈上：资深工程师的时间。初级成员提交的合并请求（Pull Request）常常堆积如山，等待着寥寥无几的架构师或资深开发过目。传统的静态分析工具（Linter）能捕捉语法错误和风格问题，但对于逻辑漏洞、设计模式滥用或潜在的性能陷阱却无能为力。这个过程不仅拖慢了交付速度，也让资深工程师疲于应付琐碎的审查，无法聚焦于更复杂的架构问题。

我们的目标是构建一个自动化的代码审查代理（Agent），它必须足够“聪明”，能提供超越 Linter 的深度见解；同时，它的运行成本必须极低，因为代码提交是突发性、非连续性的工作负载。让一个服务长期空转等待 PR，在云原生时代是不可接受的资源浪费。

初步的技术构想是：利用大语言模型（LLM）的深度代码理解能力，结合一个能够按需伸缩的无服务器（Serverless）平台。当开发者推送代码时，一个事件会触发我们的审查服务，该服务按需启动、执行审查、提交评论，然后自动缩容至零，不产生任何闲置成本。

技术选型决策如下：

1. 核心智能 - LLM: 我们需要一个能够接收代码片段并提供高质量分析的 LLM。这里不限定具体模型，重点是构建一个能与任何 LLM API 交互的健壮客户端。
2. 应用框架 - Kotlin + Spring Boot: Kotlin 的简洁性和空安全特性非常适合构建可维护的业务逻辑。Spring Boot 提供了成熟的生态系统，能快速搭建生产级的 Web 服务，并且其响应式编程模型（WebFlux）非常适合处理 I/O 密集型的 API 调用。
3. 运行平台 - Knative: Knative 是这个架构的关键。它的 Serving 组件能将任何容器化应用部署为“无服务器”服务，实现基于请求的自动扩缩容，包括缩容至零（scale-to-zero）。它的 Eventing 组件则能可靠地接收来自代码仓库（如 GitHub）的 Webhook 事件，并将其路由到我们的服务，完美契合事件驱动的场景。

整个系统的流程将是事件驱动的。

sequenceDiagram
    participant Dev as 开发者
    participant GitHub as 代码仓库 (GitHub)
    participant KnativeBroker as Knative Eventing Broker
    participant ReviewService as LLM Review Service (Knative Serving)
    participant LLM_API as 大语言模型 API

    Dev->>+GitHub: 推送代码, 创建 Pull Request
    GitHub->>+KnativeBroker: 发送 Webhook (CloudEvent)
    KnativeBroker->>+ReviewService: 触发服务, 传递事件
    Note right of ReviewService: Knative 按需从 0 启动实例
    ReviewService->>+GitHub: API: 获取 PR 的 diff 内容
    GitHub-->>-ReviewService: 返回 diff 文本
    ReviewService->>+LLM_API: 构造 Prompt, 发送 diff 进行分析
    LLM_API-->>-ReviewService: 返回审查建议 (JSON 格式)
    ReviewService->>+GitHub: API: 将建议作为评论发布到 PR
    GitHub-->>-ReviewService: 确认评论发布
    Note right of ReviewService: 处理完毕, 若无新请求, Knative 将缩容至 0

第一步：构建核心审查服务

我们的核心是一个 Spring Boot 应用。它需要一个 REST 端点来接收 Knative Eventing 转发过来的 CloudEvents 事件。

项目依赖 (build.gradle.kts):

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
    id("org.springframework.boot") version "3.2.0"
    id("io.spring.dependency-management") version "1.1.4"
    kotlin("jvm") version "1.9.20"
    kotlin("plugin.spring") version "1.9.20"
}

group = "io.tech.nomad"
version = "0.0.1-SNAPSHOT"

java {
    sourceCompatibility = JavaVersion.VERSION_17
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-webflux")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    implementation("io.projectreactor.kotlin:reactor-kotlin-extensions")
    // CloudEvents SDK 用于规范化事件处理
    implementation("io.cloudevents:cloudevents-spring:2.5.0")
    
    // 日志
    implementation("io.github.microutils:kotlin-logging-jvm:3.0.5")

    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testImplementation("io.projectreactor:reactor-test")
}

tasks.withType<KotlinCompile> {
    kotlinOptions {
        freeCompilerArgs += "-Xjsr305=strict"
        jvmTarget = "17"
    }
}

tasks.withType<Test> {
    useJUnitPlatform()
}

接下来，我们定义接收 GitHub Webhook 事件的数据结构。我们只关心 pull_request 事件中的关键信息。

dto/GitHubEvent.kt:

package io.tech.nomad.review.dto

import com.fasterxml.jackson.annotation.JsonProperty

// 定义我们需要从 GitHub Webhook Payload 中提取的数据结构
data class GitHubPullRequestEvent(
    val action: String, // e.g., "opened", "synchronize"
    @JsonProperty("pull_request")
    val pullRequest: PullRequest,
    val repository: Repository
)

data class PullRequest(
    val url: String, // API URL for this PR
    @JsonProperty("diff_url")
    val diffUrl: String, // URL to get the .diff content
    val number: Int,
    val user: User
)

data class Repository(
    @JsonProperty("full_name")
    val fullName: String // "owner/repo"
)

data class User(
    val login: String
)

我们的控制器需要监听一个特定的路径，并接收 CloudEvent 格式的 POST 请求。Knative Eventing 会将原始的 HTTP Webhook 包装成 CloudEvent。

controller/ReviewController.kt:

package io.tech.nomad.review.controller

import io.cloudevents.CloudEvent
import io.cloudevents.spring.webflux.CloudEventHttpMessageReader
import io.cloudevents.spring.webflux.CloudEventHttpMessageWriter
import io.tech.nomad.review.dto.GitHubPullRequestEvent
import io.tech.nomad.review.service.CodeReviewService
import mu.KotlinLogging
import org.springframework.boot.web.codec.CodecCustomizer
import org.springframework.context.annotation.Configuration
import org.springframework.http.ResponseEntity
import org.springframework.http.codec.CodecConfigurer
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RestController
import reactor.core.publisher.Mono

private val logger = KotlinLogging.logger {}

@RestController
class ReviewController(private val codeReviewService: CodeReviewService) {

    @PostMapping("/")
    fun handleReviewEvent(@RequestBody cloudEvent: Mono<CloudEvent>): Mono<ResponseEntity<Void>> {
        return cloudEvent
            .doOnNext { event -> logger.info { "Received CloudEvent: id=${event.id}, type=${event.type}" } }
            .flatMap { event ->
                // 这里我们假设事件数据是 GitHub PR 事件的 JSON
                codeReviewService.processPullRequestEvent(event)
            }
            .thenReturn(ResponseEntity.ok().build<Void>())
            .onErrorResume { e ->
                logger.error(e) { "Failed to process CloudEvent" }
                // 返回 2xx 避免事件源重试无法处理的事件
                Mono.just(ResponseEntity.ok().build())
            }
    }
}

// 注册 CloudEvent 的 HTTP Message Reader 和 Writer
@Configuration
class CloudEventConfig : CodecCustomizer {
    override fun customize(configurer: CodecConfigurer) {
        configurer.customCodecs().register(CloudEventHttpMessageReader())
        configurer.customCodecs().register(CloudEventHttpMessageWriter())
    }
}

核心逻辑在 CodeReviewService 中。它负责解析事件、获取代码 diff、调用 LLM、最后将结果评论回 PR。

service/CodeReviewService.kt:

package io.tech.nomad.review.service

import com.fasterxml.jackson.databind.ObjectMapper
import com.fasterxml.jackson.module.kotlin.readValue
import io.cloudevents.CloudEvent
import io.tech.nomad.review.client.GitHubClient
import io.tech.nomad.review.client.LLMClient
import io.tech.nomad.review.dto.GitHubPullRequestEvent
import mu.KotlinLogging
import org.springframework.stereotype.Service
import reactor.core.publisher.Mono
import java.nio.charset.StandardCharsets

private val logger = KotlinLogging.logger {}

@Service
class CodeReviewService(
    private val gitHubClient: GitHubClient,
    private val llmClient: LLMClient,
    private val objectMapper: ObjectMapper // Spring Boot 自动配置
) {
    private val SUPPORTED_ACTIONS = setOf("opened", "synchronize", "reopened")

    fun processPullRequestEvent(event: CloudEvent): Mono<Void> {
        return Mono.fromCallable {
                // CloudEvent 的 data 字段是字节数组
                val payload = event.data?.toBytes() ?: return@fromCallable Mono.empty<Void>()
                val eventJson = String(payload, StandardCharsets.UTF_8)
                objectMapper.readValue<GitHubPullRequestEvent>(eventJson)
            }
            .flatMap { prEvent ->
                if (prEvent.action !in SUPPORTED_ACTIONS) {
                    logger.info { "Ignoring action '${prEvent.action}' for PR #${prEvent.pullRequest.number}" }
                    return@flatMap Mono.empty<Void>()
                }
                
                // 避免机器人自我触发
                if (prEvent.pullRequest.user.login.contains("[bot]")) {
                    logger.info { "Ignoring event from bot user '${prEvent.pullRequest.user.login}'" }
                    return@flatMap Mono.empty<Void>()
                }

                logger.info { "Processing action '${prEvent.action}' for PR #${prEvent.pullRequest.number} in repo ${prEvent.repository.fullName}" }

                // 核心流程：获取diff -> LLM分析 -> 发表评论
                gitHubClient.getDiff(prEvent.pullRequest.diffUrl)
                    .flatMap { diff -> llmClient.analyzeCode(diff) }
                    .flatMap { reviewComment ->
                        if (reviewComment.isNotBlank() && !reviewComment.contains("NO_ISSUES_FOUND")) {
                             gitHubClient.postComment(
                                repoFullName = prEvent.repository.fullName,
                                prNumber = prEvent.pullRequest.number,
                                comment = reviewComment
                            )
                        } else {
                            logger.info { "LLM found no significant issues. No comment will be posted." }
                            Mono.empty()
                        }
                    }
            }
            .then()
    }
}

第二步：与外部服务交互

我们需要 GitHubClient 和 LLMClient。在真实项目中，它们需要处理认证、错误重试等。

client/GitHubClient.kt:

package io.tech.nomad.review.client

import mu.KotlinLogging
import org.springframework.beans.factory.annotation.Value
import org.springframework.http.HttpHeaders
import org.springframework.http.MediaType
import org.springframework.stereotype.Component
import org.springframework.web.reactive.function.client.WebClient
import reactor.core.publisher.Mono
import reactor.util.retry.Retry
import java.time.Duration

private val logger = KotlinLogging.logger {}

@Component
class GitHubClient(
    webClientBuilder: WebClient.Builder,
    @Value("\${github.api.token}") private val apiToken: String,
    @Value("\${github.api.base-url:https://api.github.com}") private val baseUrl: String
) {
    private val webClient = webClientBuilder.baseUrl(baseUrl).build()

    // 获取 PR 的 diff 内容
    fun getDiff(diffUrl: String): Mono<String> {
        return WebClient.create(diffUrl) // diffUrl 是完整的 URL
            .get()
            .header(HttpHeaders.AUTHORIZATION, "Bearer $apiToken")
            .header(HttpHeaders.ACCEPT, "application/vnd.github.v3.diff")
            .retrieve()
            .bodyToMono(String::class.java)
            .retryWhen(Retry.backoff(3, Duration.ofSeconds(2)).maxBackoff(Duration.ofSeconds(10)))
            .doOnError { e -> logger.error(e) { "Failed to fetch diff from $diffUrl" } }
    }

    // 将审查意见作为评论发布到 PR
    fun postComment(repoFullName: String, prNumber: Int, comment: String): Mono<Void> {
        val commentsUrl = "/repos/$repoFullName/issues/$prNumber/comments"
        val body = mapOf("body" to comment)

        return webClient.post()
            .uri(commentsUrl)
            .header(HttpHeaders.AUTHORIZATION, "Bearer $apiToken")
            .header(HttpHeaders.ACCEPT, "application/vnd.github.v3+json")
            .contentType(MediaType.APPLICATION_JSON)
            .bodyValue(body)
            .retrieve()
            .bodyToMono(Void::class.java)
            .doOnSuccess { logger.info { "Successfully posted comment to PR #$prNumber in $repoFullName" } }
            .doOnError { e -> logger.error(e) { "Failed to post comment to PR #$prNumber" } }
            .retryWhen(Retry.backoff(2, Duration.ofSeconds(5)))
    }
}

LLMClient 的实现是整个系统的智能核心。这里的关键是Prompt Engineering。一个好的 prompt 远比选择哪个特定模型更重要。

client/LLMClient.kt:

package io.tech.nomad.review.client

import mu.KotlinLogging
import org.springframework.beans.factory.annotation.Value
import org.springframework.stereotype.Component
import org.springframework.web.reactive.function.client.WebClient
import org.springframework.web.reactive.function.client.bodyToMono
import reactor.core.publisher.Mono
import java.time.Duration

private val logger = KotlinLogging.logger {}

@Component
class LLMClient(
    webClientBuilder: WebClient.Builder,
    @Value("\${llm.api.key}") private val apiKey: String,
    @Value("\${llm.api.url}") private val apiUrl: String
) {
    private val webClient = webClientBuilder.baseUrl(apiUrl).build()
    
    // 一个精心设计的系统 Prompt，用于指导 LLM 的行为
    private val systemPrompt = """
        You are an expert code reviewer specializing in Kotlin and the Spring Boot framework.
        Your task is to analyze a Git diff and provide constructive, actionable feedback.

        RULES:
        1. Focus on potential bugs, security vulnerabilities, performance issues, and deviations from best practices.
        2. Do NOT comment on code style (formatting, naming conventions) unless it severely impacts readability.
        3. Be concise and specific. Reference the file and line number if possible.
        4. If you find multiple issues, format them as a markdown list.
        5. If the code is excellent and has no issues, respond with the exact string "NO_ISSUES_FOUND".
        6. Your entire response must be a single markdown block. Do not add any conversational filler.
    """.trimIndent()

    fun analyzeCode(diff: String): Mono<String> {
        // 在真实项目中，需要处理 diff 过长超出 LLM 上下文窗口的问题
        // 简单的截断策略
        val effectiveDiff = if (diff.length > 12000) diff.substring(0, 12000) else diff
        
        val requestBody = mapOf(
            "model" to "gpt-4o", // Or any other suitable model
            "messages" to listOf(
                mapOf("role" to "system", "content" to systemPrompt),
                mapOf("role" to "user", "content" to "Review the following git diff:\n```diff\n$effectiveDiff\n```")
            ),
            "temperature" to 0.2, // 低温以获得更确定的、事实性的输出
            "max_tokens" to 1024
        )
        
        return webClient.post()
            .uri("/v1/chat/completions") // Assuming OpenAI-compatible API
            .header("Authorization", "Bearer $apiKey")
            .bodyValue(requestBody)
            .retrieve()
            .bodyToMono<OpenAIChatResponse>()
            .map { response ->
                response.choices.firstOrNull()?.message?.content ?: ""
            }
            .timeout(Duration.ofSeconds(90)) // LLM 调用可能很慢
            .doOnError { e -> logger.error(e) { "Error calling LLM API" } }
            .onErrorReturn("Error during code analysis.")
    }

    // DTO for OpenAI-compatible chat response
    data class OpenAIChatResponse(val choices: List<Choice>)
    data class Choice(val message: Message)
    data class Message(val role: String, val content: String)
}

配置文件 application.yaml:

server:
  port: 8080

# GitHub API Token, stored as a secret in Kubernetes
github:
  api:
    token: "${GITHUB_API_TOKEN}" # 从环境变量读取

# LLM API Key, also a secret
llm:
  api:
    key: "${LLM_API_KEY}"
    url: "https://api.openai.com" # 可替换为任何兼容 OpenAI 的 API

# 日志配置
logging:
  level:
    root: INFO
    io.tech.nomad: DEBUG

第三步：容器化与 Knative 部署

首先，构建一个可运行的 fat JAR 并将其打包进 Docker 镜像。

Dockerfile:

FROM eclipse-temurin:17-jre-jammy

WORKDIR /app

# 将构建好的 fat JAR 复制到镜像中
COPY build/libs/*-SNAPSHOT.jar app.jar

ENV JAVA_OPTS="-Duser.timezone=Asia/Shanghai"

# Knative 将通过 PORT 环境变量告知应用监听哪个端口
# Spring Boot 默认会识别并使用这个变量
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

构建并推送镜像到容器仓库后，我们就可以编写 Knative Service 的定义文件了。

knative-service.yaml:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: llm-code-reviewer
  namespace: default
spec:
  template:
    metadata:
      annotations:
        # 允许服务在 10 分钟无流量后缩容至零
        autoscaling.knative.dev/scale-to-zero-pod-retention-period: "10m"
    spec:
      containers:
        - image: your-registry/llm-code-reviewer:latest # 替换为你的镜像地址
          ports:
            - containerPort: 8080
          env:
            # 从 Kubernetes Secret 中注入敏感信息
            - name: GITHUB_API_TOKEN
              valueFrom:
                secretKeyRef:
                  name: github-secret
                  key: apiToken
            - name: LLM_API_KEY
              valueFrom:
                secretKeyRef:
                  name: llm-secret
                  key: apiKey
          resources:
            requests:
              memory: "512Mi"
              cpu: "250m"
            limits:
              memory: "1024Mi"
              cpu: "1000m"
      # Knative 自动伸缩配置
      containerConcurrency: 10 # 每个 Pod 实例最多同时处理 10 个请求

应用此文件 kubectl apply -f knative-service.yaml 后，Knative 将创建一个服务。初始状态下，它不会有任何 Pod 运行。

第四步：配置事件源

我们需要让 GitHub 的 Webhook 事件能够到达我们的服务。这通过 Knative Eventing 完成。首先创建一个 Broker，它是一个事件总线。

broker.yaml:

apiVersion: eventing.knative.dev/v1
kind: Broker
metadata:
  name: default
  namespace: default

然后，创建一个 Trigger，它定义了从 Broker 到我们服务的订阅关系。

trigger.yaml:

apiVersion: eventing.knative.dev/v1
kind: Trigger
metadata:
  name: github-pr-trigger
  namespace: default
spec:
  broker: default
  # 过滤事件，我们只关心 GitHub 的 pull_request 事件
  filter:
    attributes:
      type: "dev.pullrequest.event" # 这是我们自定义的事件类型
      source: "github.com"
  subscriber:
    ref:
      apiVersion: serving.knative.dev/v1
      kind: Service
      name: llm-code-reviewer

最后，我们需要一个事件源来接收 GitHub Webhook 并将其转换为 CloudEvents 发送到 Broker。虽然 Knative 有多种事件源，但最简单的方式是使用一个适配器或直接将 GitHub Webhook 指向 Broker 的 Ingress URL。GitHub Webhook 的 Content type 应设置为 application/json。

这个架构的真正威力在于，llm-code-reviewer 服务在没有 PR 提交时，Pod 数量为 0，不消耗任何计算资源。当一个 PR 被创建或更新时，GitHub Webhook 触发事件流，Knative 迅速启动一或多个 Pod 实例来处理请求。如果短时间内有大量 PR 涌入，Knative 会自动扩容以应对峰值流量，处理完毕后再次缩容，实现了极致的成本效益和弹性。

局限性与未来迭代

当前方案并非没有缺点。首先，LLM 的上下文窗口是有限的。对于包含成千上万行代码变更的巨型 PR，简单的截断策略会丢失大量上下文，导致审查质量下降。未来的优化可以实现更智能的分块（chunking）策略，或者使用具有更大上下文窗口的模型。

其次，Prompt 的健壮性是一个持续优化的过程。不同的项目、不同的团队规范可能需要微调 Prompt。一种可行的改进是允许项目在自己的仓库中定义一个 .review_config.md 文件，服务在审查前读取该文件来动态构建 Prompt，实现项目级的定制化审查规则。

最后，LLM 的响应质量存在不确定性，可能会产生“幻觉”或给出错误的建议。完全依赖自动化审查存在风险。更现实的用法是将其定位为“审查助理”，为人类审查者提供初步的分析和建议，由人类做出最终判断。这也可以通过调整 Prompt 来实现，让 LLM 的输出更侧重于提出问题和潜在风险，而非直接给出指令。