掌握 Pull Request 技艺：开发者高效代码审查指南

在快速变化的软件开发领域中，版本控制工具如Git已成为组织项目和促进团队协作不可或缺的工具。作为开发者，我们经常并行工作，创建新功能、修复错误和更新的分支。但当需要将这些更改合并回主代码库时，拉取请求（PR）就成了从孤立开发到团队协作的桥梁。

我们都有过这样的挫败感，PR被拒绝或者退回修改。很容易在某个功能上花上好几个小时，却发现我们的实现与团队的愿景不符。然而，随着时间的推移，我们逐渐明白，有效的PR不仅仅在于代码本身，更在于我们如何沟通我们的改动。

本文将介绍如何发起拉取请求，让审核过程对所有人来说更高效、更快捷、更顺畅。

写一个完美的拉取请求：

一. 从一个信息丰富的标题开始

第一印象很重要，即使在代码的世界里也不例外。拉取请求的标题是向他人立即传达更改核心的机会。可以把它想象成文章的标题；应当简短、清晰并具有信息量。尽量不要使用以下类型的标题：

• "更新代码,"
• "解决了bug"
• "昨天的变化"

相反地，使用描述性的标题，比如说：
比如说后面加冒号以匹配英文句子的结构并提高流畅度。

• feat: 添加 OAuth2 认证以支持 API 端点
• fix: 修复用户会话处理中的竞态条件
• refactor: 重构用户搜索数据库查询以提高性能

一个好的标题有助于我们的评审人员不用打开 PR 就能了解变更的内容。它为整个审查过程奠定了基础。

2. 别假设每个人都知道这个问题（设定背景）

在动手写代码之前，提供一些背景信息是很重要的。并不是每个人都知道我们要解决的特定问题，解释这些更改背后的原因是必不可少的。一份详尽的PR描述可以让审阅更加容易和快捷。下面提供了一个结构良好的PR描述模板：

    ## 问题
    当前用户注册过程中遇到障碍，因为用户认证系统不支持社交登录。我们发现有40%的用户在注册过程中流失。
    相关工单：AUTH-123

    ## 解决方案
    实现了通过Google的OAuth2认证流程：
    - 添加了用于处理Google认证的OAuth2中间件
    - 创建了新的用户资料映射规则
    - 实现了社交登录的会话控制

    ## 技术细节
    - 使用passport-google-oauth20进行认证
    - 添加了新的数据库字段：googleId，socialProfile
    - 修改用户模型以支持多种认证方式

    ## 测试

1. 点击“用Google登录”按钮

2. 授权测试应用程序

3. 验证成功跳转到仪表板

4. 检查用户资料中包含Google的数据

    ## 配置
    需要新增的环境变量：
    - GOOGLE_CLIENT_ID
    - GOOGLE_CLIENT_SECRET
    - OAUTH_CALLBACK_URL

全屏模式，退出全屏

这个流程确保审核人员能够理解问题、我们的方式以及如何确认解决方案是否有效。缺少上下文的代码提交可能会明显拖慢进度，因此请确保提供足够的信息，以便团队明白我们做了哪些修改。

3. 让公关保持焦点

我们都遇到过这种情况：想要在一个拉取请求中处理多个问题。但这通常会导致拉取请求过大，让审阅者感到不知所措。相反，我们应该尝试将我们的工作拆分成更小、更专注的拉取请求。每个拉取请求应该只专注一个特定任务。比如，如果我们正在开发一个用户管理系统，我们可以将其分解成更小的任务，例如：

1. 第一个PR：feat: 添加基本用户模型和迁移
2. 第二个PR：feat: 实现用户认证接口
3. 第三个PR：feat: 添加用户资料管理UI
4. 第四个PR：feat: 集成电子邮件验证功能

每个PR应该专注于单一的功能改进或修复，这使得审查过程对每个人来说更加简单。这样可以加快审查速度并减少反复修改。

4. 提交信息：保持清晰

一个好的提交信息不仅解释代码，还让大家明白为什么要进行这改动以及它怎样融入整体图景中。

为什么提交消息很重要，：

（注：此处的冒号建议移除或调整，以符合中文习惯，但根据原文结构保留。）根据中文的常见表达习惯，更自然的版本可能是“为什么提交消息很重要？”或“提交消息为什么很重要？”不过，为了更贴近原文结构，此处保留冒号，并在后面加上逗号。

• 它们提供上下文：一篇写得好的提交信息解释了变更背后的原因。
• 它们促进协作：后续开发者可以查看项目的历史，并轻松理解每次提交的目的。
• 它们节省时间：清晰的提交信息减少了后续提问的需求，并避免了审查过程中的反复沟通。

一些糟糕的提交信息示例:

1. 已修复的内容

为什么不好：这样表述很模糊，没有具体说明修复了什么或为什么修复。我们是修复了一个 bug，提升了性能还是重构了代码？这不清楚。

更好的版本：fix(auth): 解决因 token 过期导致的用户登录问题

1. "更新文件"

为什么不好呢：这条消息没有告诉审阅者具体改了什么或为什么需要更新。

更好的版本：chore: 更新依赖以修复安全漏洞（chore: 表示维护任务）

1. "未完成"

为什么不好：这并没有描述任何具体的改变，并暗示代码是不完整的。这让代码审查变得更加困难，因为审查者无法判断他们看到的是一个完成的功能还是一个草稿。

更好版本：feat(api): 添加用户认证端点

5.\ 审查准备检查表：为什么如此重要

在提交拉取请求之前，我们应该使用一个代码审查清单来确保我们的代码达到最佳状态。这里有几个原因说明为什么使用一个清单很重要：

• 节省审阅者的时间：它减少了审阅者因基本修复请求而浪费时间的机会，使他们能够更专注于代码逻辑。
• 检查清单确保所有拉取请求都达到统一标准，从而使审阅过程更顺畅。
• 减少来回修改：通过再次检查我们的代码和测试，我们避免了反复修改的过程。

示例检查表

- [ ] 代码符合项目风格指南
- [ ] 所有测试通过 (`npm run test`)
- [ ] 代码格式检查已通过 (`npm run lint`)
- [ ] 文档已更新
- [ ] 提交中不含敏感数据
- [ ] 分支已与 `main` 保持一致

切换到全屏。退出全屏。

解决常见的代码审查请求问题

挑战一：包含太多更改的拉取请求

我们曾面临提交大型PR提交的诱惑。然而，这通常会导致混淆和漫长的审查时间，。我们这样做了：我们没有试图一次处理所有事情，而是将任务拆分为更小、更易于管理的PR。首先进行数据库模式的更改，然后进行API的修改，最后进行前端的调整。这使得审阅者可以一次专注于一件事。

学到的一课：让 PR 只关注项目的某一方面。(PR 指 Pull Request)

挑战 2：请求中缺乏足够的背景信息

在我职业生涯早期的时候，我提交的拉取请求描述非常简略，认为大家都清楚发生了什么。这导致了很多困惑，问题，还有审核的延迟。后来我意识到，开始为每个拉取请求提供详细的描述，说明变更的内容，变更的原因及如何进行测试。这样审核流程就快了很多，也更有效率了。

例如，学到的一课：在我们的PR（项目请求）描述中一定要提供背景信息。清晰的解释能节省我们的时间，减少不必要的反复沟通，减少不必要的来回。

挑战 3：提交信息不一致

我们的团队曾经为不一致的提交信息所困扰，这使得追踪更改变得更加困难。有些信息太模糊，而另一些又过于详细。为解决这个问题，我们创建了一个标准化的提交信息格式（例如，feat:，fix:，chore:），并确保大家都遵守。这使得项目历史更加易读，并提高了团队合作。

学到的经验：保持一致的提交信息格式。这样能让大家都快速理解修改内容。

结论如下：代码拉取请求是一个很好的协作平台

编写有效的拉取请求是一个可以通过实践提高的技能。按照这些指南来做，这样可以让代码审查更高效，同时也能保持代码库更整洁和易于维护。每个拉取请求都是一次学习的机会。每个审阅评论、建议或问题都能让我们作为开发者成长，并改进我们的编码习惯。

我们的目标不仅仅是让代码被接受并合并；而是要建立一个高质量且易于理解与维护的代码库。通过在我们的PR中多下功夫，我们正在为项目的成功和我们自身的成长进行投资。

了解更多:

• https://www.conventionalcommits.org/en/v1.0.0/ (链接到约定提交规范的网站，你可以在这里查看更多详细信息)