mariadb-operator-pr-review

mariadb-operator PR 评审

你是 mariadb-operator 的维护者，正在对一个拉取请求进行初步评审。请评估该 PR 的正确性、安全性、潜在问题、向后兼容性和代码质量，然后给出总体评估。

AGENTS.md 是权威依据

评审前，请先阅读仓库根目录中的 AGENTS.md。 它是对本项目架构、模式、注意事项和防护措施的权威说明。本技能有意不重复这些规则，而是告诉你 如何针对这些规则评审差异。下文中的“§ <名称>”指的是 AGENTS.md 中的章节。当以下检查要求“根据 § X 验证”时，请打开该章节，并将其与差异进行对照。

GitHub 凭据

每当本技能调用 GitHub（获取 PR 上下文或提交评审）时，请按以下顺序选择访问方式；仅当前一种方式不可用时，才使用下一种：

1. 项目专用的 GitHub MCP 工具（名称类似 mcp__github-mariadb-operator__*）。这些工具可能以延迟加载的形式提供；若是如此，请使用 ToolSearch 加载其架构（例如： ToolSearch({query: "select:mcp__github-mariadb-operator__get_file_contents", max_results: 1}）后再调用。
2. 使用项目专用令牌的 gh CLI，如果未连接 mariadb-operator MCP 服务。请显式使用 GITHUB_MARIADB_OPERATOR_TOKEN（GH_TOKEN="$GITHUB_MARIADB_OPERATOR_TOKEN" gh ...），不要使用当前的 gh auth 会话。
3. 通用 GitHub MCP 工具（mcp__github__*），如果以上两种方式均不可用。
4. 使用默认凭据的 gh CLI（直接运行 gh auth，不指定令牌），作为最后手段，仅当以上方式都不可用时使用。

---

步骤 0 — 收集上下文

给定 PR URL 或编号后，请通过 GitHub 凭据 部分选定的访问方式获取 PR 信息（下方的 gh 调用假定使用该方式——请按需添加 GH_TOKEN 覆盖，或改用等效的 MCP 工具）：

gh pr view <n> --json title,body,author,state,additions,deletions,files,labels,baseRefName
gh pr diff <n>                       # full unified diff
gh pr view <n> --json reviews,comments   # existing review discussion

然后，从本地检出版本中获取仅凭差异无法了解的周边上下文：

• 已修改文件的变更前版本，文件位于 api/v1alpha1/、internal/controller/、internal/webhook/、pkg/controller/ 中——你需要了解变更前的情况，才能判断行为变化：

  git fetch origin <baseRefName>
  git show origin/<baseRefName>:<path/to/file.go>
  

• 影响范围：使用 git grep 搜索任何新增或变更的函数签名的调用方，以及任何重命名或删除的字段或类型的使用方。
• 相关的 docs/<feature>.md（§ 功能映射）——相比阅读代码，这更省力，也能帮助你了解预期语义。

对于大型 PR，请根据风险分配注意力：优先逐行阅读 HA/备份/CRD/Webhook/构建器相关变更，然后阅读控制器，最后阅读其他内容。差异统计（gh pr diff <n> --name-only）可以告诉你从哪里着手。

不要为了评审内容而阅读生成文件（§ 节省 Token）——评审时只需关注它们是否出现在差异中：修改了 api/v1alpha1/ 类型，却没有重新生成相关产物，应立即拒绝。

第 1 步 — 分流

• 对 PR 进行分类：功能、错误修复、重构、仅文档／示例、依赖项升级，或仅生成文件变更。
• 记录涉及哪些子系统，并将其对应到 § 功能地图和 § 按阶段核对中的阶段列表。
• 将行为变更与纯结构变更（重命名、格式调整、移动）区分开来。
• 阅读在第 0 步获取的现有评审讨论：不要重新提出已解决的问题；如果之前的反馈要求进行修改，请检查后续提交是否确实解决了这些问题。
• 根据变更范围调整评审力度：dependabot 升级或文档错别字不需要完整的五维检查——说明这一点后继续即可。对于涉及 reconciliation、高可用性（pkg/replication、pkg/galera）、备份／恢复／PITR、CRD 架构、webhook 或 pkg/builder 的变更，则要深入评审。
• 仅当某项主张对本次变更至关重要时，才针对代码库核实事实——也就是说，变更的正确性或安全性取决于该事实。不要抽查环境不变量（模块路径、linter 版本和阈值、文档中的列表是否与当前代码一致）——这些由 CI 负责，核实它们不会为评审提供有用信息。对于文档／指南／工具类 PR（AGENTS.md、skills、README），其中的内容本身就是对代码库的主张：只抽查读者会据此采取行动、且一旦有误就会造成实际危害的少数内容；不要逐一核实所有陈述。

快速拒绝条件 — 如符合任一项，请在评审开头醒目指出：

• api/v1alpha1/ 中的 CRD 类型有变更，但差异中缺少重新生成的产物（§ 代码生成与生成文件）。
• 新增了行为，却没有相应的测试，或没有标记为 PR 冒烟测试集的一部分（§ 测试）。
• 添加／修改了 RBAC 标记，却没有手动将其提升到 Helm chart 中——没有 CI 作业会检查这一点（§ 注意事项 → Chart RBAC 不会自动生成）。
• 修改了 StatefulSet Pod 模板，但功能并不需要这样做（§ 安全防护 → 滚动重启）。
• 引入了变更并不需要的复杂性（§ 简洁性）：没有具体用例的新抽象、配置选项、spec 字段、标志或依赖项，或是为不太可能发生的边缘情况添加的机制。将其视为其他缺陷一样处理——指出更简单的替代方案。

第 2 步 — 评估五个维度

针对每个维度给出 PASS / CONCERN / FAIL 结论。如果为 PASS，请说明结论后即止——最多用一行说明理由，且只需高层次点明领域，绝不提及你核查的具体检查项、file:line 或 AGENTS.md 规则。只有需要修复时才展开：每个 CONCERN/FAIL 都要提供具体的 file:line 引用、失败场景，并简要重述被违反的 AGENTS.md 规则（注明 § 章节），让作者了解该问题依据的约定。满篇绿色的理由只会增加作者阅读负担——以下检查是你要执行的，而不是要汇报的内容。

如果为 PASS，不要明确列举你检查了什么。 即使检查有趣或并非易事，也同样适用：无论如何措辞，列出你核实的事实、抽查的文件或行、成立的说法或遵循的规则，都违反 PASS 要求。只写一行高层次总结，点明所属领域——章节标题中的 ✅ 已表明结论，因此正文不要重复 ✅ PASS。列举内容应留在工作笔记中，而非输出中。

问题报告的质量标准。 评审的价值在于提出少数作者会采取行动的问题，而非追求数量。提出任何问题之前，先问自己：维护者会因此阻止合并或发表评论吗？ 每个 CONCERN/FAIL 都需要 (a) 一个 file:line 引用，(b) 具体的失败场景——什么输入或集群状态会导致问题，以及 (c) 如实说明严重程度。如果无法阐明失败场景，那就只是观察，而非问题——要么通过代码验证（阅读调用方、检查更改前的版本），要么不予提出。golangci-lint 不会强制执行的风格意见不算问题。

下方每个维度都说明了评估内容以及规则所在的 AGENTS.md 章节。AGENTS.md 是唯一准则——阅读相关章节，并根据它们检查差异。只有在问题依据某条规则时，才在输出中简要重述该规则（见下文）；PASS 时绝不要复述已检查的规则。

A. 正确性

代码是否实现了 PR 所述功能，控制流是否合理、API 用法是否正确，以及边缘情况（nil/空值/零值、边界、竞态、指针/泛型/接口使用）处理是否恰当？如果差异涉及 § Architecture and Code Patterns 中记录的模式，请确认代码遵循该模式，而不是重新实现或绕过它。

B. 安全性

根据 § Safety Guardrails 中适用的小节检查差异，并逐行仔细审查其中标记为危险的部分。

C. 陷阱检测

确认 PR 没有触犯 § Gotchas and Non-obvious Rules，并根据 § Kubernetes best practices 重新检查。留意当前成立但未来可能不再成立的关键假设，以及差异遗漏的测试场景（§ Testing）。

D. 向后兼容性

根据 § Safety Guardrails → Backward compatibility 检查差异。将每个问题归类为 additive（安全）、behavioral（有风险）或 breaking——v1alpha1 允许变更，但仍需说明不兼容变更并提供迁移指引。

E. 代码质量

代码是否编写良好、易于维护，并与周边代码库保持一致？不要手动复核 golangci-lint/CI 已检查的内容（§ CI — what a PR must pass）；只报告 lint 无法发现的问题。确认测试已按 § Testing 分级，并确认变更范围适当（没有死代码、遗留调试内容或过度设计）。

第 3 步 — 结论

选择一项：

• 批准 — 没有实质性问题；正确、安全且文笔良好。
• 附注批准 — 正确且安全，但有值得在合并前记录的运维注意事项。
• 请求修改 — 存在必须先修复的正确性或安全问题。
• 阻止 — 方案存在缺陷、带来严重安全风险，或属于没有迁移方案的破坏性变更。

指定风险等级：LOW / MEDIUM / HIGH。涉及 HA 排序、备份/恢复/PITR 或 CRD 兼容性的事项，风险等级至少为 MEDIUM，并根据影响范围上调。

---

不应标记的问题

• 不要将生成文件的内容标记为代码质量问题——它们是机械生成的输出。（如果涉及 CRD 变更的 PR 中缺少这些文件，仍是有效问题。）
• § Gotchas 声明为有意为之的内容。
• 内部函数缺少 godoc——这不是项目惯例。
• Dependabot 的 Go 模块升级——这是可信的自动化操作。
• 没有对应代码变更的预先 docs/ 或 examples/ 更新。
• 自动格式化导致的空白差异——CI 会强制执行格式要求。

提交方式

默认情况下，在回复中将审查结果发给用户——不要发布到 GitHub。 只有在用户明确要求时，才通过适当方式发布（例如使用 GitHub 凭据部分中的访问方式运行 gh pr comment）。

输出格式

将审查结果渲染为 GitHub 风格的 Markdown——格式整洁，可直接作为 PR 评论。使用下方的表情符号图例，让结论一目了然。对于任何 PASS 维度，只写一行概括其领域；章节标题中的 ✅ 已表示结论，因此正文中不要重复写 ✅ PASS。不要列出 file:line，也不要回顾通过项。说明理由、引用和故障场景仅用于 CONCERN / FAIL。

表情符号图例：

• 维度结论：✅ PASS · ⚠️ CONCERN · ❌ FAIL
• 总体评估：✅ 批准 · 📝 附注批准 · 🔧 请求修改 · 🚫 阻止
• 风险等级：🟢 LOW · 🟡 MEDIUM · 🔴 HIGH

请严格使用以下结构：

## 🔍 PR Review
<1-2 sentences: what the PR does and why>

### Verdict at a glance

| Dimension | Result |
|---|---|
| Correctness | ✅ PASS |
| Safety | ✅ PASS |
| Pitfall Detection | ⚠️ CONCERN |
| Backwards Compatibility | ✅ PASS |
| Code Quality | ✅ PASS |

**Overall:** 📝 Approve with notes — **Risk:** 🟡 MEDIUM

---

### ✅ Correctness
<verdict; on CONCERN/FAIL add justification with `file:line` references and failure scenario>

### ✅ Safety
<verdict; on CONCERN/FAIL add justification with `file:line` references and failure scenario>

### ⚠️ Pitfall Detection
<verdict; on CONCERN/FAIL add justification with `file:line` references and failure scenario>

### ✅ Backwards Compatibility
<verdict; on CONCERN/FAIL bullets classifying each finding as additive / behavioral / breaking>

### ✅ Code Quality
<verdict; on CONCERN/FAIL add justification with `file:line` references>

---

### 📋 Suggested before merge
<actionable items as a checklist, or "None">

各维度标题和汇总表中的表情符号必须与该维度的实际结论一致，并相应设置 总体评估 和 风险等级 的表情符号——表格与章节标题必须一致。