《智能代码审查系统》需求设计-第03节：智能代码审查系统功能拆解与需求梳理

作者：冰河
星球：http://m6z.cn/6aeFbs
博客：https://binghe.site
文章汇总：https://binghe.site/md/all/all.html
源码获取地址：https://t.zsxq.com/UIr1U

沉淀，成长，突破，帮助他人，成就自我。

大家好，我是冰河~~

我们在做一套 AI 代码审查工具，先把需求理清楚，免得后面跑偏。

一、背景：传统代码审查的烦恼

先说说我们为什么想做这个系统。搞软件开发的朋友都知道，代码审查（Code Review）是保证质量的关键一环，但真正做起来，到处都是坑。

1.1 时间永远不够用

  • 慢：找资深开发看代码，少则半天，多则几天，MR 排着队等。
  • 漏：项目一大，几百个文件改动，人工根本看不过来。
  • 重复劳动：新人总犯同样的低级错误，每次都得人肉指出，心累。
  • 冲突：多个 MR 同时需要审查，负责人就那几个，谁先谁后都得罪人。

结果呢？MR 合并一拖再拖，团队交付速度被拖慢；日常审查只能看个大概，深层次问题基本忽略。

1.2 质量全靠“看谁审”

  • 标准不统一：有人死磕命名规范，有人只看逻辑，有人说“我觉得这里不好”，没个准。
  • 深度不够：表面 bug 能发现，但边界条件、并发安全、SQL 注入这种，真不一定。
  • 前后不一致：同一段代码，今天 A 审给 85 分，明天 B 审给 70 分，开发一脸懵。

没有统一的衡量体系，代码质量就像玄学。

1.3 新人难带，经验留不住

  • 知识传递靠嘴：审查意见里写“这里不对”，新人问“为什么不对”，来回扯。
  • 成长慢：新人得不到系统性的指导，同样的错误反复犯。
  • 经验沉淀难：每次发现的问题，审完就没了，下次别人还会踩。

团队越大，这些毛病越明显。

1.4 我们想要的目标

基于上面这些痛点，我们希望智能审查系统能做到三件事：

兜住质量底线：从功能、安全、性能、规范、可维护性几个维度全面扫描，不依赖人的状态，标准统一。

把效率提上去：代码提交后几秒内给出反馈，自动处理大部分重复性检查，让资深开发从繁琐的初审中解放出来。

顺便培养人：审查意见不是简单判对错，而是解释为什么、怎么改，附带参考资料。看得多了，新人自然就懂了。

下面这张图是我们对系统功能的整体设想，先有个印象。

二、功能需求：到底要做哪些事？

2.1 代码审查的核心流程

整个流程从 Git 平台收到 Webhook 开始，到发布审查结果结束。中间涉及代码获取、解析、AI 调用、结果解析、评分、评论发布等步骤。

2.1.1 接收代码变更

系统需要能接收 Git 平台的 Webhook 事件，主要是 MR/PR 创建、更新、重新打开，以及 Push 事件。

几个关键点：

  • 要能区分不同事件类型（创建、更新、重开、合并、Push）
  • 从事件里抽取出项目名、作者、分支、diff、提交信息、URL 等
  • 无效事件要过滤掉，比如不是我们关注的分支
  • Webhook 响应必须快（<100ms），审查过程放后台异步处理，别把 Git 平台卡住

验收标准（我们内部用 checklist 来卡）：

  • 支持 GitLab、GitHub、Gitea 的 Webhook
  • 能正确提取所有必要信息
  • 事件处理延迟 < 100ms
  • 异步不阻塞

2.1.2 解析代码 diff

从 Git 平台 API 拿到 diff 后，要统一格式、过滤掉不需要审查的文件、识别编程语言、适当截断。

具体做法：

  • 通过 GitLab/GitHub/Gitea 的 API 拿 diff
  • 把不同平台的 diff 格式转成内部统一格式
  • 按文件扩展名过滤，默认支持 .java、.py、.js、.ts、.vue、.go 等，也允许用户自定义黑/白名单
  • 根据扩展名识别语言，必要时通过代码内容二次确认
  • 保留修改前后各 30 行代码作为上下文，方便 AI 理解
  • 如果 diff 太大（超过 20KB），智能截断，保留关键逻辑

验收标准：

  • 能从所有支持的平台正确获取 diff
  • 文件过滤可配置
  • 语言识别准确
  • 大小控制不超限

2.1.3 执行代码审查

这是核心中的核心。把 diff 喂给 AI 模型，让它按照我们设定好的提示词来审查。

提示词设计：我们做了分层模板。基础模板（功能、安全、性能、规范、可维护性）是所有语言共用的，然后每种语言再叠加自己的专项要求（比如 Python 要检查 PEP 8 和类型提示）。审查风格也支持切换：专业、讽刺、温和、幽默，让开发者自己选顺眼的。

LLM 选择：支持 OpenAI、DeepSeek、智谱 GLM、通义千问。可以根据场景切换，日常 MR 用便宜快速的模型，核心模块用更强但慢一点的模型。

结果解析：AI 返回的是 Markdown 格式，我们要从中提取出评分、问题列表、每个问题的文件位置和行号、优先级。

缓存：相同的 diff 直接返回缓存结果，缓存 24 小时，命中率大概 30% 左右，省不少钱。

验收标准：

  • 支持多语言
  • 提示词可配置
  • 能切换 LLM 提供商
  • 缓存有效

2.1.4 评分系统

光说“有问题”不够，要量化。我们搞了个五维评分模型。

具体的分值和扣分规则：

维度分值考核点扣分规则
功能正确性40分逻辑正确、边界处理、异常处理每个 bug 扣 2-10 分
安全性30分输入验证、SQL注入、XSS、权限、敏感信息严重问题扣 20 分
最佳实践20分代码规范、设计模式、注释每处违规扣 1-5 分
性能效率5分算法效率、资源管理性能问题扣 1-5 分
提交质量5分提交信息清晰度信息不清扣 2-5 分

评分不是拍脑袋。我们做了几层校验：

  • 分数必须在 0-100 之间
  • 如果没发现问题但没得满分，需要解释为什么扣分
  • 如果分数很高但问题列表却有很多条，说明有问题，触发人工复核
  • 定期分析历史评分分布，如果某个项目平均分突然大幅波动，自动告警

验收标准：

  • 评分模型清晰可理解
  • 扣分规则明确
  • 历史对比和趋势分析

2.1.5 发布审查意见

结果要发回 Git 平台，让开发者能看到。

评论内容：标题行显示总分和总评，下面列出每个问题的文件位置、行号、描述、修改建议、优先级。Markdown 格式，带代码块对比。

发布策略：避免重复评论（同一个 MR 多次 push，只更新不追加）。发布失败自动重试 3 次。

验收标准：

  • 所有平台能正确发布
  • 评论格式清晰
  • 发布成功率 > 95%

2.2 平台集成

我们不打算绑定某一，家 Git 平台，所以做了适配器模式。

三个平台都要支持：

  • GitLab：merge_request 和 push 事件，用 private token 认证
  • GitHub：pull_request 和 push 事件，用 GitHub App 或 token
  • Gitea：pull_request 和 push，用 token

Token 要加密存储，支持定期续期。每个项目的 token 可以单独配置。

验收标准：

  • 三个平台都能用
  • Webhook 正确解析
  • 代码获取和评论发布都正常
  • 认证安全

2.3 通知系统

审查结果除了发到 MR 评论区，最好还能推送到钉钉、企微、飞书等渠道，让相关人及时看到。

每个渠道的支持程度：

  • 钉钉：webhook、Markdown、@人、文件
  • 企业微信：机器人、Markdown、@人、文件
  • 飞书：机器人、Markdown、@人、文件
  • 自定义 Webhook：任意 HTTP 接口，可自定义请求头和 body

通知内容：审查类型（MR/Push）、项目名、分支、评分、问题数量和类型、审查链接、变更统计。

配置灵活性：可以全局开关某个渠道，也可以按项目单独配置。通知模板支持自定义变量替换。

验收标准：

  • 所有渠道能成功发消息
  • 格式美观
  • 成功率 > 95%

2.4 报告生成

每天自动生成日报，定时推送到群里，让团队了解整体的代码质量状况。

日报内容：今日审查总数、平均分、分数分布、最常见的问题类型、各项目排名、重点问题摘录。

统计分析：除了日报，还可以按项目、按人、按时间段做深度分析。比如某位开发者的评分趋势图、某类问题的发生频率变化等。

验收标准：

  • 数据准确
  • 支持定时发送和手动查询
  • 图表可视化（可选）

2.5 代码质量评估的其他细节

除了评分，还要对发现的问题进行分类和定级，方便开发者按优先级处理。

问题类型：功能性、安全性、性能、规范、代码重复、复杂度过高。

优先级：

  • P0：致命错误，必须改才能合并
  • P1：严重问题，强烈建议修复
  • P2：一般问题，建议修复
  • P3：优化建议，可选

最佳实践检查：比如命名规范、注释规范、设计模式使用、SOLID 原则等。这些规则做成可配置的，允许项目组自己启用/禁用。

验收标准：

  • 分类准确
  • 优先级合理
  • 规则可配置

2.6 用户反馈

AI 不是万能的，肯定会有误报或漏报。所以需要让开发者能给每个审查结果打标：“这个评论有用/无用”。收集到的反馈用来优化提示词。

反馈类型：问题是否属实、建议是否合理、评分是否合理、其他意见。

反馈后的动作：系统定期分析反馈，如果某类误报反复出现，就调整提示词，加入反例。调整后可以在小范围做 A/B 测试，确认有效再全量。

验收标准：

  • 反馈入口方便
  • 数据准确
  • 优化闭环有效

2.7 辅助功能

审查历史：所有审查记录可查，按项目、作者、时间筛选，分页展示。支持导出。

配置管理：LLM 提供商、平台参数、通知规则、审查规则等，都可以通过配置文件或管理界面修改。修改前有验证，防止配错导致系统不可用。

日志监控：记录操作日志、错误日志、性能日志。监控指标包括审查数量、平均耗时、成功率、LLM 调用次数、错误率等。超过阈值自动告警。

验收标准：

  • 历史查询方便
  • 配置管理完善
  • 日志和监控完备

三、非功能需求

光有功能不够，还得满足一些“看不见但很重要”的要求。

3.1 性能

  • MR 审查：90% 的请求在 30 秒内返回
  • Push 审查：90% 在 10 秒内
  • Webhook 接收：<100ms 响应
  • 并发：同时处理至少 10 个 MR 和 20 个 Push
  • 容量：支持 100+ 仓库、100 万条审查记录

3.2 可靠性

  • 系统可用性 99.9%
  • 审查成功率 >95%
  • 通知发送成功率 >95%
  • LLM 调用失败自动重试 3 次
  • 数据一致性 100%

3.3 安全

  • Token 用 AES-256 加密存储
  • 所有外部通信走 HTTPS
  • 敏感代码数据不落盘（只存审查结果，不存原始 diff）
  • Webhook 签名验证，防止伪造
  • API 限流，防止滥用

3.4 可用性与可维护性

  • 配置尽量简单，最好能一键部署
  • 提供 Web 管理界面（可选）
  • 日志详细，方便排查问题
  • 代码模块化，方便二次开发
  • 接口标准化，方便扩展新的 Git 平台或 LLM

四、需求优先级

资源有限，不可能一下子全做。我们按 P0/P1/P2 分了优先级。

P0（必须做）：

  • 代码审查核心流程（接收、解析、执行、评分、发布）
  • GitLab 集成
  • 至少两个 LLM 提供商
  • 至少一个通知渠道

P1（重要）：

  • GitHub、Gitea 集成
  • 所有通知渠道
  • 审查历史、配置管理、日志监控
  • 问题分类和分级

P2（可选，有时间再做）：

  • 用户反馈和提示词优化
  • 日报和统计分析
  • 代码截断和缓存等性能优化

五、怎么验证做对了

我们定了一些验收标准，测试通过了才算完。

功能测试：单元测试覆盖率 80% 以上，集成测试覆盖主要流程，端到端测试跑通完整的 MR 审查流程。

性能测试：压力测试验证并发能力，延迟测试看 P95 响应时间，容量测试看能撑多少数据。

安全测试：渗透测试找漏洞，权限测试看访问控制是否严密，数据安全测试看 Token 和敏感信息是否泄露。

兼容性测试：三个 Git 平台、四个 LLM 提供商、四个通知渠道，都要挨个测。

六、总结

这份需求分析梳理了我们做智能代码审查系统到底要做什么、做到什么程度。核心是自动化、量化、可反馈，解决人工审查的效率、质量和知识传递问题。

系统的架构是插件化的，Git 平台、LLM、通知渠道都可以灵活替换。数据流清晰，从 Webhook 到审查结果再到通知发布，闭环完整。

优先级分好了，接下来就是按 P0 → P1 → P2 的顺序，一步步实现。希望最后做出来的东西，能让团队真正用起来，而不是又一个“做完了没人用”的玩具。

写在最后

在冰河技术知识星球， 《AI智能代码审查平台》、《AI全链路短剧生成平台》 已完结，同时，《企业级微服务开放平台》 项目热更中，还有其他二十几个项目，像实战Claude Code、AI知识库系统、智流助手平台、智能成语挑战赛项目、多轮AI智能对话系统、一站式AI智能平台、AI智能客服系统、AI智能问答系统、实战AI大模型、手写高性能敏组件、手写线程池、手写高性能SQL引擎、手写高性能Polaris网关、手写高性能熔断组件、手写通用指标上报组件、手写高性能数据库路由组件、手写分布式IM即时通讯系统、手写Seckill分布式秒杀系统、手写高性能RPC、实战高并发设计模式、简易商城系统等等。

这些项目的需求、方案、架构、落地等均来自互联网真实业务场景，让你真正学到互联网大厂的业务与技术落地方案，并将其有效转化为自己的知识储备。

值得一提的是：冰河自研的Polaris高性能网关比某些开源网关项目性能更高，目前正在热更AI一体化项目，也正在实现MCP，全程带你分析原理和手撸代码。

你还在等啥？不少小伙伴经过星球硬核技术和项目的历练，早已成功跳槽加薪，实现薪资翻倍，而你，还在原地踏步，抱怨大环境不好。抛弃焦虑和抱怨，我们一起塌下心来沉淀硬核技术和项目，让自己的薪资更上一层楼。

🚀PS：目前已开通最大优惠：长按或扫码加入星球立减30，注意：随着项目和专栏的更新，星球也即将涨价！！


目前，领券加入星球就可以跟冰河一起学习《实战Claude Code》、《多轮AI智能对话系统》、《一站式AI智能平台》、《AI智能客服系统》、《AI智能问答系统》、《实战AI大模型》、《手写高性能Redis组件》、《手写高性能脱敏组件》、《手写线程池》、《手写高性能SQL引擎》、《手写高性能Polaris网关》、《手写高性能RPC项目》、《分布式Seckill秒杀系统》、《分布式IM即时通讯系统》《手写高性能通用熔断组件项目》、《手写高性能通用监控指标上报组件》、《手写高性能数据库路由组件》、《手写简易商城脚手架项目》、《Spring6核心技术与源码解析》和《实战高并发设计模式》，从零开始介绍原理、设计架构、手撸代码。

花很少的钱就能学这么多硬核技术、中间件项目和大厂秒杀系统、分布式IM即时通讯系统，AI大模型项目，比其他培训机构不知便宜多少倍，硬核多少倍，如果是我，我会买他个十年！

加入要趁早，后续还会随着项目和加入的人数涨价，而且只会涨，不会降，先加入的小伙伴就是赚到。

另外，还有一个限时福利，邀请一个小伙伴加入，冰河就会给一笔 分享有奖 ，有些小伙伴都邀请了50+人，早就回本了！

其他方式加入星球

  • 链接 ：打开链接 http://m6z.cn/6aeFbs 加入星球。
  • 回复 ：在公众号 冰河技术 回复 星球 领取优惠券加入星球。

特别提醒： 苹果用户进圈或续费，请加微信 hacker_binghe 扫二维码，或者去公众号 冰河技术 回复 星球 扫二维码加入星球。

好了，今天就到这儿吧，我是冰河，我们下期见~~