1. 从零搭建代码评审工具：为什么我要造这个轮子
代码评审这件事，做过团队协作开发的人都懂——它既是保证代码质量最有效的手段，也是最容易流于形式的环节。我待过几个不同规模的研发团队，从五六人的小作坊到几十人的中型团队，代码评审的落地情况千差万别。有的团队用商业化的代码托管平台自带评审功能，有的团队靠邮件来回发diff文件，还有的团队干脆就是口头说一句“你帮我看看这段代码有没有问题”。
这些方式各有各的问题。平台自带的评审工具往往绑定在特定生态里，换个仓库就得重新适应；邮件方式效率极低，版本一多就乱套；口头评审就更不用说了，连个记录都留不下来。我一直在想，能不能有一个轻量的、不依赖特定平台的、可以自己掌控的代码评审工具？这就是我做 open-code-review 这个项目的出发点。
先把这个项目的定位说清楚。open-code-review 是一个开源的代码评审辅助工具，它的核心目标是：让开发者可以在本地或者自建的代码仓库环境中，快速发起、参与和管理代码评审流程。它不绑定任何特定的代码托管平台，不依赖云端服务，所有的评审数据都保存在你自己的环境里。适合谁用？我觉得有三类人特别需要：一是中小型研发团队，没有预算买商业化工具有没有精力自建完整DevOps平台；二是对代码隐私有要求的团队，不希望评审数据经过第三方服务器；三是个人开发者，想在自己的开源项目或者个人项目里引入规范的评审流程。
这个项目的关键词是“open-code-review”，拆开来看就是“开放”“代码”“评审”三个核心概念。“开放”意味着开源、可定制、不锁定；“代码”明确了它的作用对象是源代码；“评审”则定义了它的核心功能场景。我后面会围绕这三个维度，把这个工具的设计思路、核心实现、实操步骤和踩坑经验完整地展开。
2. 代码评审工具的核心能力拆解
2.1 评审流程的四个关键阶段
在动手写代码之前，我花了大概两周时间梳理代码评审的完整流程。不管用什么工具，一次完整的代码评审基本上都会经历四个阶段：发起评审、查看变更、提出意见、合入或打回。
发起评审这个环节，核心要解决的问题是“让评审人知道要看什么”。一个合格的评审请求应该包含：变更的代码范围、变更的目的说明、相关的上下文信息（比如关联的任务编号或者需求文档链接）。很多团队在这一步做得不够好，发起人只丢一个diff出来，评审人完全不知道背景，只能从代码本身去猜意图，效率很低。
查看变更阶段，工具需要提供清晰的diff展示。这里有个细节容易被忽略：diff的展示方式直接影响评审效率。行内diff适合看小改动，并排diff适合看大段重写，折叠未变更区域能帮助评审人聚焦在真正改动的部分。我在open-code-review里把diff展示做成了可配置的，用户可以根据自己的习惯切换视图模式。
提出意见阶段是评审的核心。一条好的评审意见应该包含：问题所在的文件和行号、问题的严重程度（阻塞、建议、疑问）、具体的修改建议。我见过太多评审意见就是一句“这里有问题”，评审人看了也不知道该怎么改。工具应该引导评审人给出结构化的反馈，而不是让评审变成聊天。
合入或打回阶段，需要有一个明确的决策机制。是所有人都同意才能合入，还是只要没有阻塞性意见就可以合入？这些策略应该可以在工具里配置，而不是靠口头约定。
2.2 为什么选择本地优先的架构
市面上不缺代码评审工具，从重量级的DevOps平台到轻量的Git插件都有。我选择做本地优先的架构，主要基于三个考虑。
第一是数据隐私。代码是团队最核心的资产之一，评审过程中产生的讨论、批注、决策记录，同样包含大量敏感信息。把这些数据放在第三方服务器上，对于很多团队来说是不可接受的。本地优先意味着所有数据都在你自己的机器或者你控制的服务器上，没有数据外泄的风险。
第二是灵活性。本地优先的架构不依赖任何外部服务，你可以在离线环境下使用，可以在内网环境部署，也可以把它集成到现有的工作流里。我见过一些团队因为用了某个云端评审工具，结果该服务调整了免费额度或者改变了计费策略，整个团队的评审流程就瘫痪了。本地优先的工具没有这个问题。
第三是可定制性。每个团队的评审流程都不一样，有的团队要求至少两个人同意才能合入，有的团队只需要一个人审核。本地优先的架构让这些规则都可以通过配置文件来定义，不需要去适应工具预设的流程。
当然，本地优先也有代价。最大的代价是协作的便利性不如云端工具。云端工具天然支持多人实时协作，而本地工具需要你自己解决数据同步的问题。我的做法是：评审数据以文件形式存储在项目仓库的一个隐藏目录里，通过Git本身来同步。这样既保持了本地优先的特性，又借助Git实现了协作。
2.3 与现有工具链的边界划分
做工具最怕的就是什么都想做，最后什么都做不好。open-code-review在设计之初就明确了自己的边界：它只做代码评审这一件事，不试图替代代码托管平台，不试图替代CI/CD流水线，不试图替代项目管理工具。
具体来说，它不负责代码的存储和版本管理，这部分交给Git；它不负责自动化测试和构建，这部分交给CI工具；它不负责任务的分配和追踪，这部分交给项目管理工具。open-code-review只做一件事：在代码变更发生之后、合入之前，提供一个结构化的评审环境。
这个边界划分很重要。我见过一些工具试图把评审和CI绑在一起，结果就是配置极其复杂，小团队根本用不起来。open-code-review的定位是“评审层”，它可以和任何代码托管平台配合使用，也可以和任何CI工具配合使用，只要它们都围绕Git仓库工作就行。
3. 环境准备与项目初始化实操
3.1 基础环境要求与依赖选择
open-code-review的运行环境要求不高，这是刻意为之的。核心依赖只有两个：一个是运行时环境，我选择了Node.js，因为它的生态最丰富，跨平台支持最好；另一个是Git，因为评审的对象就是Git仓库里的代码变更。
为什么选Node.js而不是Python或者Go？这里说一下我的考虑。Python的生态也很丰富，但在处理文件系统操作和子进程调用时，Node.js的异步模型更自然。Go的性能更好，但开发效率不如Node.js，而且对于这个工具的使用场景来说，性能不是瓶颈。Node.js还有一个优势是npm生态里有大量现成的库可以用，比如解析diff的库、操作Git的库、生成终端界面的库，这些都能大幅缩短开发周期。
Node.js的版本要求是16以上，因为用到了一些较新的API。Git的版本要求是2.20以上，因为需要用到一些较新的diff特性。这两个要求都不高，基本上最近两三年的开发环境都能满足。
安装方式我提供了两种：一种是通过npm全局安装，适合个人开发者快速上手；另一种是克隆仓库后本地构建，适合需要定制或者参与开发的用户。npm安装的命令很简单：
npm install -g open-code-review安装完成后，在任意Git仓库目录下执行ocr init就可以初始化评审环境。这个命令会在当前仓库的.ocr目录下创建配置文件和评审数据存储目录。
3.2 初始化配置文件的字段说明
ocr init生成的配置文件是.ocr/config.json，这个文件控制着评审工具的所有行为。我把配置项分成了几个大类，下面逐一说明。
基础配置类包含projectName、defaultBranch、reviewers三个字段。projectName是项目名称，用于在评审记录里标识项目；defaultBranch是默认的目标分支，通常是main或者master；reviewers是默认的评审人列表，发起评审时会自动带上这些人。
流程配置类包含approvalRule、blockingLevel、autoAssign三个字段。approvalRule定义合入条件，可选值有any（任意一人同意）、all（所有人同意）、majority（多数同意）；blockingLevel定义什么级别的意见会阻塞合入，可选值有blocker（只有阻塞级意见才阻塞）、suggestion（建议级及以上都阻塞）；autoAssign是一个布尔值，控制是否自动分配评审人。
存储配置类包含storageType、storagePath两个字段。storageType目前支持file和sqlite两种，file模式把评审数据存成JSON文件，适合小团队；sqlite模式把数据存在SQLite数据库里，适合评审记录较多的项目。storagePath指定存储路径，默认是.ocr/data。
这里有个经验之谈：配置文件不要提交到主分支的版本控制里，因为不同开发者的本地配置可能不一样。我的做法是把.ocr/config.json加入.gitignore，然后提供一个.ocr/config.example.json作为模板。这样每个开发者可以有自己的配置，同时新加入的成员也能快速了解有哪些配置项。
3.3 首次评审的完整操作链路
配置好之后，就可以发起第一次评审了。完整的操作链路是这样的：
第一步，确保你在一个Git仓库里，并且有未合入的变更。可以是当前分支相对于目标分支的差异，也可以是暂存区里的变更。open-code-review会自动检测这些变更。
第二步，执行ocr review create命令发起评审。这个命令会打开一个交互式界面，让你填写评审标题、描述、选择评审人。标题和描述是必填的，因为它们是评审人理解变更背景的关键信息。
第三步，评审创建成功后，会生成一个评审ID，比如REV-001。评审人可以通过ocr review list查看待评审的列表，通过ocr review show REV-001查看具体评审内容。
第四步，评审人在查看diff的过程中，可以通过ocr comment add命令在特定文件的特定行添加意见。意见需要指定级别（blocker、suggestion、question）和具体内容。
第五步，所有评审人完成评审后，发起人可以通过ocr review status REV-001查看评审状态。如果满足合入条件，执行ocr review merge REV-001完成合入；如果不满足，根据评审意见修改代码后重新发起评审。
这个链路看起来步骤不少，但实际操作起来很快。我实测下来，一个中等规模的变更（大概两三百行代码），从发起到完成评审，熟练之后十分钟以内就能搞定。
4. 核心功能模块的实现思路
4.1 diff解析引擎的设计与优化
diff解析是代码评审工具最基础也最核心的功能。Git本身提供了diff命令，但它的输出格式是给人看的，不是给程序解析的。我需要一个能把diff解析成结构化数据的引擎，这样才能在界面上灵活展示，也才能支持在特定行上添加评论。
我选择用diff这个npm包来做基础解析，然后在它之上做了一层封装。基础解析把diff拆成一个个hunk（变更块），每个hunk包含起始行号、行数、具体的增删行。封装层则负责把hunk和文件路径关联起来，并且计算出每个变更行在原始文件和新文件中的行号映射。
这里有个坑我踩过：Git的diff输出里，行号是从1开始的，但很多编程语言的数组索引是从0开始的。如果在解析的时候不统一，后面做行号映射的时候就会各种off-by-one错误。我的做法是在解析层统一转成0-based索引，在展示层再转回1-based。这样内部逻辑用0-based，用户看到的是1-based，两边都不容易出错。
另一个优化点是diff的懒加载。一个大的变更可能涉及几十个文件、上千行代码，如果一次性全部解析并渲染，界面会卡顿。我的做法是只解析文件列表和每个文件的变更统计，具体的hunk内容在用户展开某个文件时才解析。这样首屏加载时间从原来的两三秒降到了两百毫秒以内。
4.2 评论系统的数据模型
评论系统的数据模型设计直接影响到评审的可用性。我设计的数据模型包含以下几个核心实体：
Review（评审）实体包含：id、title、description、author、reviewers、sourceBranch、targetBranch、status、createdAt、updatedAt。status有四个状态：open（进行中）、approved（已通过）、rejected（已打回）、merged（已合入）。
Comment（评论）实体包含：id、reviewId、filePath、lineNumber、lineType（added/removed/context）、level（blocker/suggestion/question）、content、author、createdAt、resolved（是否已解决）、resolvedBy、resolvedAt。
ReviewComment关联表用于支持一条评论关联多个评审，虽然目前主要是一对一的关系，但预留了这个扩展能力。
这个数据模型的关键设计点是评论和代码行的绑定方式。我用的是文件路径加行号的组合来定位，而不是用diff的hunk索引。原因是hunk索引在代码变更后会失效，而文件路径加行号在大多数情况下是稳定的。当然，如果代码行本身被删除了，评论就会变成“孤儿评论”，我在界面上会把这类评论单独展示，提醒用户注意。
还有一个细节是评论的级别设计。我一开始只设计了blocker和suggestion两个级别，后来发现很多评审人想提问但又不想阻塞合入，于是加了question级别。question级别的评论不参与合入条件的判断，纯粹是提问和讨论。
4.3 评审状态的流转逻辑
评审状态的流转逻辑是保证评审流程规范化的关键。我定义的状态机是这样的：
初始状态是open。在open状态下，评审人可以添加评论、解决评论、修改评审状态。当所有阻塞性评论都被解决，并且满足approvalRule定义的合入条件时，评审状态可以转为approved。如果评审人认为变更有问题需要打回，状态转为rejected。approved状态的评审可以执行合入操作，状态转为merged。
这里有个容易忽略的细节：评论的解决和评审的通过是两回事。一条评论被标记为已解决，不代表评审就可以通过了，还需要满足合入条件。我在实现的时候把这两个逻辑分开，评论的解决只影响阻塞性评论的计数，评审的通过还需要检查approvalRule。
另一个细节是状态回退。如果评审已经approved了，但有人又添加了一条blocker级别的评论，状态应该自动回退到open。这个逻辑我是在添加评论的时候做的检查：如果评审当前是approved状态，且新添加的评论是blocker级别，就把状态改回open。这样避免了“已经通过的评审被新评论阻塞但状态没更新”的问题。
5. 实操中遇到的典型问题与排查过程
5.1 大文件diff导致的内存溢出
项目刚上线内部试用的时候，有个同事提交了一个包含大量自动生成代码的变更，涉及一个上万行的JSON文件。他发起评审后，工具直接卡死了，终端没有任何响应。我一开始以为是死循环，加了日志后发现是内存溢出。
排查过程是这样的：我先用--max-old-space-size参数把Node.js的内存限制调大，发现能跑但还是很慢。然后用--inspect参数启动调试，用Chrome DevTools连上去看内存快照，发现diff解析阶段创建了大量的临时对象，这些对象在解析完成后没有被及时释放。
根本原因是我的解析逻辑是一次性把所有hunk都解析成对象数组，对于大文件来说，这个数组会非常大。修复方案是改成流式解析：读一行解析一行，解析完的hunk如果不在当前展示范围内就释放掉。同时加了一个文件大小阈值，超过阈值的文件默认折叠，用户手动展开时才解析。
这个问题的教训是：不要假设用户只会提交小变更。代码评审工具必须能处理各种规模的变更，从一行修改到上万行的重构都要能扛住。
5.2 行号映射在代码变更后的错位
另一个比较隐蔽的问题是行号映射错位。场景是这样的：评审人在某个文件的第50行添加了一条评论，然后发起人根据其他评论修改了代码，在第30行插入了几行新代码。这时候评审人再看那条评论，发现它指向的行已经不是原来的内容了。
这个问题的本质是：评论绑定的行号是相对于某个版本的代码的，代码变更后行号就失效了。我尝试了几种方案：一种是用代码内容的哈希来定位，但代码修改后哈希也会变；另一种是用上下文匹配来重新定位，但实现复杂度很高。
最后我采用的方案是：在评论里同时记录行号和该行的代码内容。当代码变更后，先尝试用行号定位，如果行号对应的内容不匹配，就在附近搜索匹配的内容。如果还是找不到，就把评论标记为“可能已失效”，在界面上用特殊样式展示，提醒用户手动确认。
这个方案不是完美的，但能解决大部分场景。对于代码评审这种场景来说，完全自动化的行号追踪是不现实的，因为代码变更的意图只有人才能理解。工具能做的是尽量减少人工确认的成本。
5.3 多人同时评审的冲突处理
第三个问题是多人同时评审时的数据冲突。open-code-review的数据存储是基于文件的，多个评审人同时添加评论时，后写入的会覆盖先写入的。这个问题在单人使用时不会出现，但团队试用时就暴露了。
我一开始想用文件锁来解决，但文件锁在跨平台场景下行为不一致，而且如果进程崩溃锁没释放，会导致后续操作全部失败。后来改用乐观锁的方案：每次写入前先检查文件的修改时间，如果和读取时不一致，就重新读取、合并、再写入。合并策略是：对于评论列表，按ID去重后合并；对于评审状态，以最新的为准。
这个方案在大多数情况下能正常工作，但在高并发场景下还是可能丢数据。对于代码评审这个场景来说，高并发写入的情况很少见，所以这个方案够用了。如果将来真的需要支持高并发，可能得换成数据库存储。
6. 提升评审效率的进阶配置与技巧
6.1 自定义评审规则模板
每个团队的评审规则都不一样，open-code-review支持通过模板来定义评审规则。模板文件放在.ocr/templates目录下，每个模板是一个JSON文件，定义了评审的默认配置。
比如，可以定义一个“紧急修复”模板，审批规则设为any，阻塞级别设为blocker，这样紧急修复只需要一个人同意就能合入。再定义一个“常规变更”模板，审批规则设为all，阻塞级别设为suggestion，这样常规变更需要所有人同意，且任何建议级别的意见都会阻塞合入。
使用模板的方式是在发起评审时指定模板名称：
ocr review create --template hotfix这个功能看起来简单，但实际用起来能大幅提升效率。我所在的团队定义了四个模板：hotfix、feature、refactor、docs，分别对应紧急修复、新功能、重构、文档变更。发起评审时选一下模板，评审规则就自动配好了，不需要每次手动设置。
6.2 与CI流水线的集成方式
虽然open-code-review不负责CI，但它可以和CI流水线集成，实现更自动化的评审流程。集成的思路是：在CI流水线里加一个检查步骤，调用open-code-review的命令行接口检查评审状态。
比如，在合并请求的CI检查里加这样一段：
ocr review check --branch $CI_MERGE_REQUEST_SOURCE_BRANCH --require-approved这个命令会检查指定分支的评审是否已经通过。如果没通过，命令返回非零退出码，CI检查失败，合并请求就无法合入。这样就实现了“评审不通过就不能合入”的强制约束。
集成的关键是CI环境里要有open-code-review的运行环境。我的做法是在CI的构建镜像里预装open-code-review，或者在CI脚本里动态安装。前者更快，后者更灵活，可以根据团队的情况选择。
6.3 评审数据的统计与回顾
评审数据积累多了之后，可以做很多有价值的统计。open-code-review提供了一个ocr stats命令，可以生成评审数据的统计报告。
报告包含几个维度的数据：评审数量趋势（按天、周、月统计）、平均评审时长（从发起到合入的时间）、评审意见分布（按级别统计）、评审人活跃度（每个人参与评审的次数和提出的意见数）。
这些数据可以用来做团队回顾。比如，如果发现平均评审时长在变长，可能是评审人太少或者变更太大；如果发现blocker级别的意见占比很高，可能是代码质量在下降；如果发现某个评审人的意见数远高于其他人，可能是评审任务分配不均。
我在团队里每个季度会用这些数据做一次评审流程的回顾，看看哪些地方可以改进。这个习惯坚持了半年多，评审效率确实有提升。
7. 我对代码评审工具的一些个人体会
做这个项目一年多，从最初的个人自用到后来团队内部推广，再到开源出去收到一些外部用户的反馈，我对代码评审这件事的理解也在不断变化。
最开始我觉得代码评审工具的核心是diff展示，只要diff展示得清楚，评审效率就高。后来发现不是这样。diff展示只是基础，真正影响评审效率的是评审流程的设计。一个结构化的评审流程，能让评审人知道该看什么、该说什么、什么时候可以结束，这比diff展示重要得多。
另一个体会是，工具不能试图解决所有问题。代码评审的本质是人和人的沟通，工具能做的是降低沟通的成本，但不能替代沟通。我见过一些团队试图用工具来强制评审流程，结果就是评审变成了走过场，大家为了满足工具的要求而评审，而不是为了发现问题而评审。open-code-review的设计哲学是“辅助而非强制”，工具提供结构和便利，但最终的决定权还是在人手里。
还有一个我觉得值得分享的经验是：评审的粒度很重要。太大的变更没人愿意认真评审，太小的变更又不值得走评审流程。我的经验是，一个评审请求涉及的代码变更控制在200到400行之间比较合适。超过这个范围，评审质量会明显下降。open-code-review在发起评审时会提示变更的行数，如果超过阈值会建议拆分，这个功能在实际使用中很受欢迎。
最后说一个技术上的体会：本地优先的架构虽然牺牲了一些协作便利性，但换来的数据掌控感和灵活性是值得的。特别是对于中小团队来说，不需要为了用一个评审工具而去搭建一套完整的DevOps平台，这种轻量化的方案更务实。当然，如果团队规模继续扩大，可能还是需要更重量级的方案，但那是另一个阶段的事情了。
