code-review

代码审查

全面审查 GitLab 合并请求，就代码质量、安全性、性能和最佳实践提供可执行的反馈。

前置条件

• glab（GitLab CLI）：所有 MR 和流水线操作都需要它——请从 https://gitlab.com/gitlab-org/cli 安装，或运行 brew install glab

GitLab 实例配置

此技能针对自托管的 GitLab 实例进行配置：

• GitLab URL： https://gitlab-erp-pas.dedalus.lan
• 所有项目标识符、URL 和引用都应使用此自托管实例
• 确保已配置适用于此 GitLab 服务器的访问凭据

何时使用此技能

在以下情况下启用此技能：

• 用户输入“review”或“code review”（带或不带斜杠命令）
• 用户输入“review MR-123”或“review !123”以审查特定合并请求
• 用户输入“review ISSUE-ID”（例如，“review #456”）以审查与 GitLab 问题相关联的 MR
• 用户要求审查合并请求
• 合并前分析代码更改
• 评估代码质量
• 检查安全漏洞或性能问题
• 审查合并请求差异

关键规则

重要：审查合并请求前，务必确认 project_id

务必以提问的方式提供建设性反馈，而非直接指示

只审查合并请求引入的更改，不审查无关代码

工作流

1. 确认合并请求

已提供合并请求 IID

如果已提供合并请求 IID（例如，“review !123”或“review MR 123”）：

1. 从用户输入中提取 MR IID
2. 确认项目上下文（如果不明确，请询问用户）
3. 使用 glab mr view <iid> 获取合并请求详情

已提供 GitLab 问题 ID

如果已提供 GitLab 问题 ID（例如，“review #456”）：

1. 使用 glab issue view <iid> 获取问题详情，了解上下文
2. 使用 glab mr list --search "<issue reference>" 查找相关合并请求
3. 如果找到多个 MR，请用户选择要审查的对象
4. 继续审查选定的 MR

未指定特定 MR

如果未指定 MR（例如，只输入“review”）：

1. 使用 glab mr list --state opened 列出最近打开的合并请求
2. 向用户展示列表
3. 询问用户要审查哪个 MR

2. 收集合并请求上下文

自托管 GitLab 实例： https://gitlab-erp-pas.dedalus.lan

使用 glab mr view <iid> 获取：

• 标题和描述
• 源分支和目标分支
• 作者信息
• 状态（打开、已合并、已关闭）
• 标签和里程碑
• 审批状态
• 流水线状态
• 用于准确比较差异的 diff_refs（base_sha、head_sha、start_sha）

提取关键信息：

Project: namespace/project
MR: !123 - "Feature: Add user authentication"
Author: @username
Source: feature/auth -> Target: main
Status: Open | Pipeline: Passed | Approvals: 1/2

3. 分析更改

获取文件更改

使用 glab mr diff <iid> 获取：

• 更改文件列表
• 每个文件的新增和删除内容
• 每个文件的差异内容

分页：如果更改的文件很多，差异输出可能很大——请分段审查。

获取详细文件内容

对于复杂更改，使用 git show <ref>:<file_path> 来：

• 查看完整的文件上下文
• 了解周围的代码
• 检查与现有模式的一致性

参数：

• <ref>：使用源分支或 diff_refs 中的 head_sha
• <file_path>：文件路径

分析提交

使用 git log --oneline <source_branch> 列出提交，然后使用 git show <sha> 来：

• 了解提交历史
• 审查单个提交的更改
• 检查提交消息质量

4. 检查现有讨论

使用 glab api /projects/:id/merge_requests/:iid/discussions 来：

• 查看现有反馈和讨论
• 避免重复评论
• 了解进行中的讨论
• 检查是否存在未解决的讨论串

5. 检查流水线状态

使用 glab ci list 和 glab ci view <pipeline_id> 来：

• 验证 CI/CD 流水线状态
• 检查失败的作业
• 查看测试结果

如果流水线失败，使用 glab ci trace <job_id> 了解失败原因。

6. 执行全面代码审查

全面审查仅此合并请求引入的更改。

代码质量评估

• 代码风格和格式的一致性
• 变量和函数的命名规范
• 代码组织和结构
• 是否遵循 DRY（不要重复自己）原则
• 抽象层级是否恰当

技术审查

• 逻辑正确性和边界情况
• 错误处理和验证
• 性能影响
• 安全考量（输入验证、SQL 注入、XSS 等）
• 资源管理（内存泄漏、连接处理）
• 如适用，检查并发问题

最佳实践检查

• 设计模式的使用
• 是否遵循 SOLID 原则
• 对测试覆盖率的影响
• 文档是否完整
• API 是否一致
• 向后兼容性

依赖项和集成

• 新增的依赖项
• 对现有接口的破坏性更改
• 对系统其他部分的影响
• 数据库迁移需求

7. 生成审查报告

创建结构化的代码审查报告，包含：

1. 执行摘要：高层概述更改内容和总体评估

2. 统计信息：

   • 更改的文件数、增加/删除的行数
   • 审查的提交数
   • 发现的严重问题

3. 优点：做得好的地方

4. 按优先级分类的问题：

   • 🔴 严重：合并前必须修复（错误、安全问题）
   • 🟡 重要：应当处理（性能、可维护性）
   • 🟢 建议：可改进之处

5. 详细发现：每个问题都应包含：

   • 文件和行号
   • 以问题形式表述的疑虑
   • 说明提问原因的背景
   • 如有帮助，可提供代码示例

6. 安全审查：具体的安全考量

7. 性能审查：性能影响

8. 测试建议：应添加哪些测试

9. 文档需求：应更新哪些文档

8. 在合并请求中添加评论（可选）

重要：在添加评论到 MR 之前，先询问用户

如果用户想要直接在 MR 中添加反馈：

一般评论

使用 glab mr note <iid> --message "<comment>" 添加一般评论：

• <iid>：MR 内部 ID
• <comment>：Markdown 格式的评论内容

行级讨论

使用 glab api POST /projects/:id/merge_requests/:iid/discussions 添加针对代码的反馈，参数包括：

• body：讨论内容
• position：包含差异位置信息的对象：
  • base_sha：来自 diff_refs
  • head_sha：来自 diff_refs
  • start_sha：来自 diff_refs
  • new_path：文件路径
  • new_line：新增代码的行号
  • old_path：文件路径（适用于修改）
  • old_line：删除代码的行号

反馈风格：提问，而非直接指示

所有反馈都应以问题的形式提出，而不是命令。 这样可以鼓励对话，并尊重作者的上下文。

示例

❌ 不要这样写：

• “这里应该使用提前返回”
• “这里需要错误处理”
• “将其提取到单独的函数中”
• “添加空值检查”

✅ 应这样写：

• “这里是否可以通过提前返回来简化？”
• “如果这个 API 调用失败会发生什么？在这里添加错误处理会有帮助吗？”
• “将其提取为独立函数以便复用，是否合适？”
• “有没有可能出现空值？如果有，我们应该如何处理？”

为什么提问效果更好

• 作者可能掌握你不了解的背景信息
• 提问能邀请对方解释，而非引发抵触
• 提问承认审查者可能尚未充分理解
• 提问能开启对话，而不是列出检查项

审查报告模板

# Code Review: !{MR_IID} - {MR_TITLE}

## Executive Summary
{Brief overview of changes and overall assessment}

## Merge Request Details
- **Project**: {project_path}
- **Author**: @{author}
- **Source Branch**: {source_branch} → **Target**: {target_branch}
- **Pipeline Status**: {status}
- **Approvals**: {current}/{required}

## Statistics
| Metric | Count |
|--------|-------|
| Files Changed | {count} |
| Lines Added | +{additions} |
| Lines Removed | -{deletions} |
| Commits | {commit_count} |

## Strengths
- {strength_1}
- {strength_2}

## Issues Found

### 🔴 Critical
{critical_issues_or_none}

### 🟡 Important
{important_issues_or_none}

### 🟢 Suggestions
{suggestions_or_none}

## Security Review
{security_findings}

## Performance Review
{performance_findings}

## Testing Recommendations
- {test_recommendation_1}
- {test_recommendation_2}

## Documentation Needs
- {doc_need_1}

## Verdict
{APPROVED | CHANGES_REQUESTED | NEEDS_DISCUSSION}

示例

示例 1：审查特定合并请求

User: Review !42 in namespace/project

Assistant actions:
1. glab mr view 42 — fetch MR details
2. glab mr diff 42 — get file changes
3. glab api /projects/:id/merge_requests/42/discussions — check existing feedback
4. glab ci list — check CI status
5. Analyze changes and generate report
6. Present review to user
7. Ask if user wants comments added to the MR

示例 2：审查与某个问题相关的 MR

User: Review the MR for issue #123

Assistant actions:
1. glab issue view 123 — fetch issue details
2. glab mr list --search "#123" — find related MRs
3. Present found MRs and ask user to confirm
4. Proceed with code review workflow

示例 3：列出待审查的开放 MR

User: Show me open merge requests to review

Assistant actions:
1. glab mr list --state opened — list open MRs
2. Present list with key details (title, author, pipeline status)
3. Ask user which MR to review

重要注意事项

• 仅审查此合并请求中的更改——不要评论未更改的代码
• 以提问的方式提出反馈，促进交流
• 提供具有建设性且具体的反馈
• 为改进建议提供代码示例
• 肯定良好的实践和改进
• 明确问题优先级（严重 > 重要 > 建议）
• 考虑更改的背景和目的
• 结束审查前检查流水线状态
• 查看现有讨论，避免重复反馈
• 向合并请求添加评论前务必先征求同意
• 如果链接了问题单，请确认审查涵盖验收标准