企业官网建设流程全解析

• 大数据
• 数据库
• 后端

导读

本文基于 Presto 官方仓库（prestodb/presto）中的.claude/skills/review-presto-pr/SKILL.md技能文档，系统整理面向 Presto 分布式 SQL 查询引擎的 Pull Request 审查方法论。文章覆盖从检出 PR 代码、评估变更规模、代码风格与安全性检查，到 SPI / Connector / Planner / 执行引擎等模块的专项审查要点、测试覆盖要求、文档义务、Conventional Commits 提交规范，以及可直接套用的审查输出模板与本地校验命令。读完本文，你将掌握一套可直接落地执行的 Presto PR 审查清单，能够在面对任意 Presto 变更时快速定位风险点、给出有依据的反馈。

适用范围与前置条件

该技能明确声明：仅用于 Presto 仓库（prestodb/presto），不得用于其他项目。其核心场景是用户提供 GitHub PR 链接、指定某个分支，或要求审查最近 N 个提交时，触发完整的代码审查流程。

开始审查前，需要先验证当前目录确实是 Presto 仓库，技能文档给出的验证方式是检查仓库标志性内容：

# 检查是否存在 Presto 特有标记 test -f pom.xml && grep -q "com.facebook.presto" pom.xml

仓库根目录的 pom.xml 正是 Presto 的 Maven 父工程描述文件，整个代码库以com.facebook.presto为顶层 Java 包名（如presto-spi/src/main/java/com/facebook/presto/spi），因此该命令可以可靠地识别 Presto 仓库。若验证失败，应告知用户并终止技能流程，而不是在错误的仓库上执行审查。

一、检出 PR 代码

审查的第一步是让待审查代码在本地可见，便于浏览与交叉核对：

# 针对 GitHub PR URL，检出 PR 分支 gh pr checkout <pr-number> # 或者根据给定的分支名检出 git fetch origin <branch-name> git checkout <branch-name>

这里依赖 GitHub CLI（gh）将 PR 对应的远程分支映射到本地。检出后，审查者可以在本地 IDE 中浏览代码、搜索符号、运行测试，从而给出更可信的反馈。

二、收集上下文：变更规模与流程合规

在深入代码之前，先搞清楚"改了什么"以及"是否走对了流程"。

规模与流程检查

• 大型变更：应关联 RFC（Presto 的设计提案仓库），RFC 需在补丁提交前完成评审；
• 超大型 PR：在不影响可审查性的前提下应拆分，生成文件（generated files）应单独考虑；
• 中等规模变更：应关联对应的 GitHub issue。

这一要求与仓库根目录的 CONTRIBUTING.md 完全一致——该文档明确规定"Contributions should have an associated GitHub issue"，大型改动需 RFC、中型改动需 issue，而小型 bug 修复与代码格式化可以不带 issue 直接提 PR。

对比基准分支

技能文档特别强调：不要硬编码分支名，而应对比 PR 的目标基础分支（base branch）。大多数 PR 以master为目标，但 release/edge 分支是从发布标签（如从 0.290 标签切出的release-0.290）剪出的，因此要先确定 base。

# 对于 GitHub PR，用 gh 查询基础分支 BASE=$(gh pr view <pr-number> --json baseRefName --jq .baseRefName) # 否则回退到默认分支；若对比的是发布分支，则使用 merge-base BASE=${BASE:-$(git remote show origin | sed -n 's/.*HEAD branch: //p')} git diff "$BASE"...HEAD --stat git log "$BASE"..HEAD --oneline # 针对单个提交 git show <commit> --stat

使用"$BASE"...HEAD（三点）会基于 merge-base 做 diff，即使基础分支已经前移或由发布标签创建，结果依然正确。这是审查 Presto PR 时必须养成的习惯。

三、代码风格检查清单

Presto 对代码风格有严格且可机器校验的要求，审查时逐项核对：

• 行宽：目标为 180 字符，但若强行折行反而难看，允许超长；
• 命名：禁止缩写，positionCount而非positionCnt。这条适用于包括 lambda 参数在内的所有命名——operator ->而非op ->，pipeline ->而非p ->，stage ->而非s ->；
• 静态导入：优先使用format()、toImmutableList()、requireNonNull、checkArgument；
• 导入顺序：Presto 通过 checkstyle 强制严格的导入顺序——按字母序排列，静态导入单独分组，不允许未使用导入与通配符导入；
• 不可变性：优先使用 Guava 不可变集合（ImmutableList、ImmutableMap）；
• 字段：尽可能声明为final；
• 类结构：字段在前、方法在后，按访问级别排序（public → private）；
• 可空性：在合适位置使用@Nullable注解；
• 校验：构造器参数用requireNonNull与checkArgument校验。

这些条目并非凭空而来。仓库根目录的 CONTRIBUTING.md 在 "Code Style" 一节详细阐述了同名规范，包括：行宽不超过 180 字符且函数声明超长时每个参数独立成行、类成员按访问级别降序排列、字段按 static final → final → normal 排序、优先静态导入java.lang.String.format与com.google.common.collect.ImmutableList.toImmutableList、构造器参数校验示例（如SqlScalarFunction中对signature的requireNonNull与checkArgument）等。

更重要的是，这些规则被 checkstyle 强制化：仓库的 src/checkstyle/presto-checks.xml 定义了机器可执行的检查，例如：

• 禁止of、copyOf、valueOf、all、none的静态导入；
• 仅允许java.lang.String.format被静态导入；
• Objects.requireNonNull、Math.toIntExact只能静态导入使用；
• org.jetbrains.annotations.Nullable被禁止，应使用jakarta.annotation.Nullable；
• 通过ImportOrder模块强制导入分组与排序、AvoidStarImport禁止通配符导入、UnusedImports清除未使用导入。

因此在审查中遇到可疑的导入或命名时，可以直接引用这些 checkstyle 规则作为依据。

四、代码安全与质量：三个维度的评估框架

技能文档要求审查者遵循既有惯例：在接受新模式或新机制之前，先自问——代码库中是否已有类似模式？能否在现有基础设施上扩展，而非另起炉灶？为什么现有方案不能扩展？技能明确提示："从头重做一切的倾向需要被抵制，现有机制往往可以被扩展或复用，新抽象应是最后手段而非第一直觉。"

具体评估从三个维度展开：

代码质量与可维护性（Code Quality & Maintainability）

• 代码是否遵循既有约定？
• 是否通过合适的接口干净地实现？
• 如果所有代码都这样写，代码库是否会变得难以维护？

代码安全（Code Safety）

• 是否线程安全？
• 是否存在无界增长的数据结构？
• 内存使用是否被计账（memory usage accounted for）？
• 是否在性能敏感路径引入了昂贵调用？
• 风险较高的新功能是否有 feature flag 保护？

用户友好性（User Friendliness）

• 配置项的名称与描述是否易于理解？
• 新功能是否配套文档？
• 用户可见变更是否补充了 release notes？

此外还需关注：资源管理（可关闭资源使用 try-with-resources）、错误处理（合适的异常类型与有意义的错误消息）、日志（合适的日志级别，不记录敏感数据）。

这三个维度与 CONTRIBUTING.md 中 "Designing Your Code" 一节提出的三轴评估完全同源，属于 Presto 社区公认的设计评审框架。

五、模块化专项审查要点

Presto 是多模块大型项目（仓库内含 presto-spi、presto-main、presto-hive、presto-parser、presto-native-execution 等数十个模块），不同模块的变更需要不同的审查侧重。

SPI 变更（presto-spi 模块）

SPI（Service Provider Interface）是 Presto 连接器与内核的契约层，仓库中的 presto-spi/src/main/java/com/facebook/presto/spi 就是这一层。SPI 变更需要格外谨慎：

• 不得引入新依赖：SPI 必须保持无依赖（dependency-free），否则会迫使连接器拉入不必要的库；
• 保持通用性：避免为特定厂商基础设施或专有系统添加钩子；
• 简单优于灵活：覆盖常见场景的简单 SPI 好过处理所有边缘情况的复杂 SPI；
• 向后兼容：不得破坏已有连接器实现；
• 自问："一个开源连接器作者会觉得这个接口合理且易于理解吗？"

连接器（Connector）变更

• 是否正确实现了 SPI 接口？
• 元数据操作是否高效（避免 N+1 查询）？
• split 生成是否可并行化？
• 谓词下推（pushdown）是否实现正确？

仓库中 presto-hive、presto-iceberg、presto-kafka、presto-accumulo 等目录均属于连接器模块，审查时可参考这些成熟实现来对照新代码。

Planner / Optimizer 变更

• 优化规则是否正确且完备？
• 是否保持查询语义不变？
• 规则应用中是否存在潜在死循环？
• 代价估算（cost estimation）是否受影响？

Presto 的 planner 相关代码主要集中在 presto-main-base 与 presto-analyzer、presto-expressions 等模块。

执行引擎变更

• 内存跟踪（memory tracking）是否正确？
• 算子是否正确处理 yield 信号？
• 数据是否尽可能以流式（streaming）方式处理？
• 交换（exchange）操作中是否存在死锁风险？

配置变更

• @ConfigDescription：每个新的@Configsetter 必须带@ConfigDescription，使属性对运维人员自文档化。仓库中可找到大量实例，例如 FailureDetectorConfig.java 中@ConfigDescription("How long to wait before 'forgetting' a service after it disappears from discovery")这样的写法；
• @ConfigSecuritySensitive：密码、密钥、token 等敏感值的 setter 必须标注该注解，以便在日志与诊断信息中被掩码；
• 新配置属性应在文档中说明默认值。

新增 HTTP 端点

• 遵循 RESTful 约定（正确使用 GET/POST/PUT/DELETE、基于资源的 URL）；
• 与代码库中既有端点模式保持一致；
• 提供正确的错误响应与状态码。

六、测试覆盖要求

基本要求

• 新代码有对应测试；
• Bug 修复包含回归测试；
• 边缘情况被测试覆盖；
• 测试是确定性的（不用Thread.sleep、不用随机值）；
• 跨模块边界的行为变更需集成测试。

避免测试重复

如果多个新测试覆盖重叠场景，优先保留最全面的那个。例如测试 A 覆盖场景 X、Y、Z，测试 B 只覆盖 X、Y，则保留 A 即可。每个测试都应提供独特价值，不要为了覆盖率数字而堆测试。

必须包含负向测试用例

• Feature flags：验证功能在禁用时行为正确；
• 访问控制：验证被拒绝的权限确实阻止了访问（而不只是验证授权路径可用）；
• 校验：验证非法输入确实被拒绝；
• 错误路径：验证失败能被优雅处理，而非只测 happy path。

仓库根目录的 CONTRIBUTING.md 也印证了测试确定性要求："Avoid addingThread.sleepin tests"、"Do not use random values in tests. All tests should be reproducible"，并提示 Presto 使用 TestNG——与 JUnit 不同，TestNG 不会为每个测试创建新对象，共享实例字段可能导致测试耦合、顺序依赖与不稳定，若确需实例字段应在@BeforeMethod中重置并标注@Test(singleThreaded = true)。

七、文档义务

以下变更必须配套文档：

• 新的 SPI 接口或变更：更新 Developer Guide（prestodb.io/docs/current/develop.html，仓库内对应源码为 presto-docs 目录）；
• 新的 session 属性：在连接器或相关模块文档中说明；
• 新的配置属性：用运维人员能理解的清晰描述记录；
• Release notes：用户可见变更必须记录。

同时检查：

• Javadoc：对复杂接口、非显而易见的行为有补充价值的地方使用（不必处处都有）；
• 复杂逻辑的注释；
• 用户可见行为变化时更新 README。

仓库的 presto-docs/src/main/sphinx 目录承载了官方文档源文件，是补充文档时的目标位置。

八、提交结构与 Conventional Commits

Presto 采用 Conventional Commits 规范，PR 标题必须符合：

<type>[(scope)]: <description>

类型（Types）：feat、fix、docs、refactor、perf、test、build、ci、chore、revert、misc

常见 scope：parser、analyzer、planner、spi、scheduler、connector、function、operator、native、docs

示例：

• feat(connector): Add support for dynamic catalog registration
• fix: Resolve memory leak in query executor
• feat!: Remove deprecated configuration options（破坏性变更）

校验项：

• PR 标题符合 conventional commit 格式；
• 每个提交能独立通过测试；
• 正文说明 what 和 why（而非 how）；
• 关联 issue 被引用（如Resolves: #1234）。

这些规则在仓库中有双重证据：一是 CONTRIBUTING.md 的 "Commit Standards" 一节；二是 CI 工作流 .github/workflows/conventional-commit-check.yml，它在 PR 上自动校验标题——配置了上述全部类型与 scope 列表，并要求 subject 以大写字母开头、不以句号结尾（subjectPattern: ^[A-Z].*[^.]$）。此外 CONTRIBUTING.md 还补充了 PR 规模约束：单 PR 修改行数不超过 5000（生成代码除外）、提交数不超过 20、提交按依赖顺序排列且每个提交须独立通过全部测试、所有 PR 合并时 squash 为单个提交等，这些都可以作为审查提交结构时的参考。

九、审查输出格式

技能文档强调：审查结果直接输出到对话中供用户阅读，不要直接向 GitHub 发评论——由用户决定分享哪些反馈。每次审查必须以[review-pr skill]开头。

推荐的输出结构如下：

<!-- Reviewed using review-pr skill --> ## High-Level Overview 以 2-3 句话概括该变更在概念层面完成了什么。聚焦"是什么"和"为什么"—— 解决什么问题、采用什么方案。应让不熟悉具体代码的人也能看懂。 ## In-Depth Overview 详细说明实现： - 修改了哪些组件/模块及其原因 - 引入或变更的关键类、接口或方法 - 各部分如何拼合 - 值得注意的设计决策与权衡 ## Change Flow Diagram 涉及多组件交互、新的请求/响应流、数据转换或管道、状态机或生命周期 变更时，使用 ASCII 图或 Mermaid 展示。简单变更（单文件 bug 修复、 文档更新、小重构）可跳过此节。 ## Summary 对 PR 整体质量、可合并就绪度与高层级关注点的简要评估。 ## Highlights PR 中做得好的地方。 ## Issues Found ### Critical 合并前必须修复的问题。 ### Suggestions 能让代码更好但不阻塞合入的改进。 ### Nits 细微的风格或格式问题。 ## Questions 需要向作者澄清的事项。 ## Testing Recommendations 应补充考虑的测试。

Mermaid 流程示例：

十、本地运行检查命令

审查过程中建议在本地实际运行校验，技能文档给出如下 Maven 命令（仓库使用根目录的mvnwwrapper）：

# 检查代码风格 ./mvnw checkstyle:check -pl <module-name> # 编译以捕获类型错误 ./mvnw compile -pl <module-name> # 运行测试 ./mvnw test -pl <module-name> -Dtest=<TestClass>

这些命令与 CI 保持一致——仓库的 .github/workflows/maven-checks.yml 在 PR 上运行./mvnw install等 Maven 检查。注意-pl <module-name>指定单个模块（例如presto-hive），避免全量构建。

十一、常见问题速查清单

技能文档最后总结了审查中反复出现的典型问题：

1. 错误导入：com.facebook.presto.spi.QueryId与com.facebook.presto.execution.QueryId的混淆；
2. 缺失空值检查：尤其在处理外部数据的连接器中；
3. 未关闭资源：迭代器、流、连接；
4. 硬编码值：魔法数字、硬编码路径；
5. 向后兼容性：对公共 API 的破坏性变更；
6. 安全性：SQL 注入、命令注入、Web UI 中的 XSS。

总结

.claude/skills/review-presto-pr/SKILL.md为 Presto 贡献者与评审者提供了一套从"检出代码"到"输出审查结论"的端到端流程：先验证仓库身份与变更基准，再按风格清单、三维质量框架、模块化专项要点逐层审查，最后以结构化模板输出、配合本地 Maven 校验闭环。这套流程的核心思想与仓库 CONTRIBUTING.md 中"设计代码的三轴评估"、checkstyle 规则（src/checkstyle/presto-checks.xml）以及 CI 工作流（conventional-commit-check、maven-checks）一脉相承——审查不是挑错，而是帮助作者以符合 Presto 既有约定和质量标准的方式把变更落地。

• 大数据
• 数据库
• 后端