企业官网建设流程全解析

• 可观测性
• APM
• 链路追踪
• 指标监控
• 日志分析
• 微服务

Apache SkyWalking 是一个开源的 APM（Application Performance Monitoring）系统，其官方代码仓库的.claude/skills/gh-pull-request/SKILL.md为 AI 编码助手（Claude Code）定义了一套完整的 PR 分支工作流：在每次提交与推送前执行编译、Checkstyle、License 头与全限定类名（FQCN）审计等预检，随后按项目规范提交推送、创建 PR，并在合并后完成分支同步与清理。本文以该文档为主体，结合仓库中的 checkstyle 配置、PR 模板、License 头模板 与 CI 工作流，系统讲解这套流程的每一步，帮助贡献者掌握"可被合并"的 SkyWalking 提交流程。

工作流总览

整套 PR 分支工作流可分为四个阶段，文档将其定义为"PR Branch Workflow"：

1. 预检（Pre-flight checks）：每次commit + push之前运行，包括编译与 Checkstyle、License 头检查、全限定类名审计；
2. 提交与推送（Commit and push）：预检通过后按分支策略提交并推送；
3. 创建 PR（Create PR）：若当前分支尚无 PR，则按仓库模板创建；
4. 合并后清理（After the PR is merged）：同步默认分支并删除本地特性分支。

这套流程的核心思想是：把质量把关前置到推送之前，确保 CI 与评审者看到的第一版代码就已通过项目的基本质量门禁。

预检一：编译与 Checkstyle

两条预检命令

文档要求在每次提交推送前执行以下两条命令：

# Checkstyle ./mvnw -B -q clean checkstyle:check # Full build (compile + javadoc) ./mvnw clean flatten:flatten install javadoc:javadoc -B -q -Pall \ -Dmaven.test.skip \ -Dcheckstyle.skip \ -Dgpg.skip

• -B：批处理（非交互）模式，适合 CI 与自动化场景；
• -q：安静模式，只输出错误与关键信息；
• flatten:flatten：执行 flatten-maven-plugin，将多模块工程的复杂 POM 扁平化为发布用 POM；
• install：将构件安装到本地仓库，验证所有模块可构建；
• javadoc:javadoc：生成 Javadoc，验证注释格式与{@link}引用的有效性；
• -Pall：激活全部 profile，保证所有可选模块都被编译验证；
• -Dmaven.test.skip：跳过测试执行（预检阶段只验证编译）；
• -Dcheckstyle.skip：跳过 Checkstyle（第一条命令已单独执行过）；
• -Dgpg.skip：跳过 GPG 签名。

仓库中的 Checkstyle 配置依据

SkyWalking 的 Checkstyle 规则集中在 apm-checkstyle/checkStyle.xml，根 POM 中通过maven-checkstyle-plugin（版本3.1.0，见 pom.xml 的maven-checkstyle-plugin.version属性）引用该文件，并设置了：

• configLocation指向${maven.multiModuleProjectDirectory}/apm-checkstyle/checkStyle.xml；
• includeTestSourceDirectory为true，测试代码同样受规则约束；
• failOnViolation由属性checkstyle.fails.on.error控制，默认true，即一旦违规构建即失败。

checkStyle.xml中值得注意的全局规则（Checker级）：

• 禁止源码中出现System.out.println（RegexpSingleline）；
• 禁止@author版权注释（ASF 项目规范）；
• 禁止中文字符出现在代码文件中；
• 单个文件长度上限 3000 行（FileLength）。

TreeWalker级与 import 相关的规则包括UnusedImports、RedundantImport、AvoidStarImport，这正与预检三的"全限定类名审计"形成互补：Checkstyle 负责检查 import 的冗余与通配，而 FQCN 审计负责捕获 Checkstyle 抓不到的"内联全限定名"。

预检二：License 头检查

检查命令

license-eye header check

若发现无效文件，先修复再复检：

license-eye header fix

license-eye（github.com/apache/skywalking-eyes）是 SkyWalking 使用的 License 头检查工具，它依据仓库根目录的 HEADER 模板逐文件校验 Apache License 2.0 头。SkyWalking 的 CI 工作流 .github/workflows/skywalking.yaml 中也包含license-headerjob，通过go install github.com/apache/skywalking-eyes/cmd/license-eye@...安装固定版本后执行检查，与本地预检保持一致。

为什么检查 License 头

作为 Apache 顶级项目，SkyWalking 要求每个源码文件（包括.java、.xml、.yaml等）都以 Apache License 2.0 头开头。仓库根目录 HEADER 中定义的标准模板如下：

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 ...

新增文件时若漏掉 License 头，license-eye header check会将其标记为无效文件；此时执行header fix可自动补齐，但修复后应重新运行 check 确认全部通过，再进入提交阶段。

预检三：全限定类名（FQCN）审计

规则背景

项目 Checkstyle 禁止内联全限定类名——代码中的每个类型引用都应通过import解析，而不是直接写出java.util.HashMap这样的全限定名。文档特别指出：Checkstyle 并不总能抓住这类问题，例如：

• 内联java.util.HashMap；
• 内联java.util.concurrent.TimeUnit；
• 将org.apache.skywalking.oap.server.telemetry.api.HistogramMetrics.Timer用作局部变量类型、泛型参数或new目标。

因此，推送前需要用 Grep 工具（ripgrep）对分支改动的文件做一次额外审计。

扫描模式

文档给出的扫描模式如下（注意：它依赖负向前瞻，BSDgrep不支持，需使用 ripgrep 或 GNUgrep -P）：

pattern: ^(?!\s*(import |package |\s*\*)).*\b(java\.util\.|java\.io\.|java\.nio\.|java\.util\.concurrent\.|javassist\.|org\.apache\.skywalking\.)[A-Z][A-Za-z0-9_]* glob: *.java output_mode: content -n: true

该模式通过^(?!\s*(import |package |\s*\*))排除 import 语句、package 语句与注释行，再匹配以java.util.、java.io.、java.nio.、java.util.concurrent.、javassist.、org.apache.skywalking.开头的内联类型引用。

扫描范围：只扫分支改动的文件

文档强调将扫描范围限定在分支实际改动的文件上，避免整棵代码树中历史遗留的 FQCN 产生噪音。获取改动文件列表：

git diff --name-only master...HEAD -- '*.java'

然后对列表中的每个文件运行上述 ripgrep 模式。

允许的例外

与 CLAUDE.md 的规则一致，以下三种情况是允许的例外：

1. 两个类同名、同时 import 会冲突时；
2. Javadoc{@link}中短名称对读者有歧义时；
3. 字符串字面量内部（例如传给Class.forName的类名字符串）。

除此之外的所有命中都必须修复——增加import并改用短名称。字段声明、方法签名、局部变量、泛型类型参数都应使用 import 后的短名称，包括new java.util.HashMap<>()和java.util.Set<String>参数类型这类写法。

修复后的隐患：Range 越界错误

文档特别提醒：修复时如果使用粗糙的sed/replace_all，可能损坏import行本身——例如把import java.util.concurrent.locks.ReentrantLock;错误地替换成import ReentrantLock;。这种损坏不会报普通的 Checkstyle 违规，而是抛出令人困惑的Range [0, -1) out of bounds for length N错误。看到该错误时，应首先检查 import 块。

修复完成后需要重新运行 Checkstyle（第一条预检命令）确认。

提交与推送

预检全部通过后，进行提交与推送：

git add <files> git commit -m "<message>" git push -u origin <branch-name>

分支策略

文档明确规定：

• 绝不直接在 master 分支上工作；
• 若当前处于 master，先创建新分支：

  git checkout -b feature/<name> # 或 git checkout -b fix/<name>

分支名按用途区分：feature/前缀用于新功能，fix/前缀用于缺陷修复。这与仓库的 CI 工作流和评审习惯相呼应，也便于 PR 标题与模板归类。

创建 Pull Request

检查 PR 是否已存在

gh pr view --json number 2>/dev/null

如果当前分支已有 PR，此命令会输出其编号；若没有（命令失败），则创建新 PR。

PR 标题

标题需简洁概括改动内容，文档给出示例：

• Fix BanyanDB query timeout issue
• Add support for OpenTelemetry metrics

PR 描述：严格遵循仓库模板

文档强调：必须阅读 .github/PULL_REQUEST_TEMPLATE 并使用其精确格式与复选框，不得使用自定义摘要格式。仓库模板将 PR 分为三类，对应不同的勾选项：

缺陷修复（Bug Fixes）：

### Fix <bug description or issue link> - [ ] Add a unit test to verify that the fix works. - [ ] Explain briefly why the bug exists and how to fix it.

新功能（New Features）：

### <Feature description> - [ ] If this is non-trivial feature, paste the links/URLs to the design doc. - [ ] Update the documentation to include this new feature. - [ ] Tests(including UT, IT, E2E) are added to verify the new feature. - [ ] If it's UI related, attach the screenshots below.

性能改进（Performance Improvements）：

### Improve the performance of <class or module or ...> - [ ] Add a benchmark for the improvement. - [ ] The benchmark result. - [ ] Links/URLs to the theory proof or discussion articles/blogs.

所有 PR 都必须包含：

- [ ] If this pull request closes/resolves/fixes an existing issue, replace the issue number. Closes #<issue number>. - [ ] Update the [`CHANGES` log](https://link.gitcode.com/i/96e7559dd1b031b647ab7499fe4b5a5a).

模板中的"Always include"部分体现了 SkyWalking 的硬性要求：关联 issue 编号（Closes #<number>），以及更新 CHANGES 日志——仓库在docs/en/changes/目录下按版本维护changes.md及changes-X.Y.Z.md各版本记录，这是每次合入代码都必须同步维护的变更清单。

创建命令

gh pr create --title "<title>" --body "$(cat <<'EOF' <PR body from template> EOF )"

使用 heredoc 将模板正文传入--body，可避免引号转义问题。

创建后动作

• 添加copilot作为评审者：gh pr edit <number> --add-reviewer copilot；
• 不要将 AI 助手添加为共同作者（co-author），代码责任由提交者承担；
• 完成后返回 PR 链接。

PR 合并后的同步与清理

PR 合并后，需要同步默认分支并清理特性分支。文档给出四步操作：

# 1. Prune stale remote refs. GitHub auto-deletes the PR's branch on merge, so # the remote feature branch is usually already gone; --prune removes the # dangling local tracking ref. git fetch origin --prune # 2. Switch back to the default branch and fast-forward it to include the merge. git checkout master git pull --ff-only origin master # 3. Confirm the change actually landed in master before deleting anything — # `git log --oneline -1` should show the merge/squash commit with the PR # number, or grep for a symbol the PR introduced. git log --oneline -1 # 4. Delete the local feature branch. SkyWalking SQUASH-merges PRs, so the # feature branch's commit is NOT an ancestor of master (master gets a new # squash commit instead). `git branch -d` therefore reports "not fully # merged" — that is expected, not an error. After confirming the content is # in master (step 3), force-delete: git branch -d <branch> 2>/dev/null || git branch -D <branch>

关键注意事项

• Squash 合并导致git branch -d报 "not fully merged" 是正常现象：SkyWalking 的 PR 采用 SQUASH 合并，master 上生成的是全新的 squash 提交（SHA 与特性分支提交不同），因此特性分支的提交不是 master 的祖先。第 3 步确认改动确实合入后，使用-D强制删除即可；
• 第 3 步不可跳过：强制删除一个实际未合入的本地分支会永久丢失工作。确认方式可以是git log --oneline -1显示的合并提交带 PR 编号，也可以 grep PR 引入的某个符号；
• 若远端分支未被自动删除（取决于仓库设置），需显式删除：git push origin --delete <branch>；
• git pull --ff-only保证 master 以快进方式更新，避免产生意外的合并提交。

总结：把流程沉淀为可执行清单

结合文档与仓库源码，SkyWalking 的 PR 分支工作流可沉淀为如下执行清单：

1. 切分支：绝不直接在 master 上工作，使用feature/或fix/前缀；
2. 编译 + Checkstyle：./mvnw -B -q clean checkstyle:check与完整构建命令，规则见 apm-checkstyle/checkStyle.xml；
3. License 头：license-eye header check，模板见 HEADER，CI 同款校验见 .github/workflows/skywalking.yaml；
4. FQCN 审计：用 ripgrep 对git diff --name-only master...HEAD -- '*.java'列出的文件扫描内联全限定名，修复后重跑 Checkstyle（警惕Range [0, -1) out of bounds提示 import 块被损坏）；
5. 提交推送：git add→git commit→git push -u origin <branch>；
6. 创建 PR：先gh pr view判重，标题简洁，正文严格套用 .github/PULL_REQUEST_TEMPLATE 的复选框格式（Bug Fix / New Feature / Performance Improvement 三类），并附带Closes #issue与 CHANGES 日志 更新项；创建后添加copilot评审；
7. 合并后清理：git fetch origin --prune→git checkout master && git pull --ff-only→git log --oneline -1确认合入 →git branch -d失败时（squash 合并属正常）确认后git branch -D删除。

这套工作流既适合人类贡献者手工执行，也适合 AI 编码助手在提交 PR 前自动完成质量门禁，其核心价值在于：把所有可能在评审与 CI 阶段暴露的问题，提前到第一次推送之前解决。

• 可观测性
• APM
• 链路追踪
• 指标监控
• 日志分析
• 微服务