github-pr-diff-tree如何获取PR diff:mediaType diff技巧全解
github-pr-diff-tree如何获取PR diff:mediaType diff技巧全解
🌲 github-pr-diff-tree 是一个超实用的 GitHub Action,它的核心原理正是利用 mediaType 参数请求 PR diff:调用 Pulls API 时附带 mediaType: { format: 'diff' },即可让服务端直接返回原始 unified diff 文本,再经解析后以目录树形式评论到 PR 中,帮助评审者一眼看清本次改动的完整文件结构。
一、它解决了什么问题?
GitHub 的 PR 评审页面虽然能看代码 diff,但当一次 PR 涉及大量文件时,文件分布在哪些目录这类结构信息很容易被评审者忽略。
github-pr-diff-tree 的作用很简单:每当 PR 创建或更新(opened / synchronize 事件)时,它会自动在 PR 下发表评论,用人类可读的"文件树"展示所有变更文件,并标注每个文件的增删改状态:
A:新增文件D:删除文件M +x, -y:修改文件及增删行数R:重命名文件
最终效果如下图所示,一条注释就能看清整个 PR 的改动全貌:
二、核心技巧:用 mediaType 获取 PR diff
这是整篇文章最值钱的知识点 💡。
GitHub REST API 中 GET /repos/{owner}/{repo}/pulls/{pull_number} 默认返回 JSON。但如果请求时声明接受 diff 媒体类型,服务端就会返回纯文本格式的 unified diff。在 Octokit 中,这个技巧的写法就是在请求参数里加上 mediaType:
const {data: raw} = await octokit.rest.pulls.get({
...repo,
pull_number: number,
mediaType: {
format: 'diff'
}
})
对应源码见 src/main.ts。
💡 小知识:
mediaType: { format: 'diff' }会设置 HTTP 请求头Accept: application/vnd.github.v3.diff。此时响应不再是 JSON 对象,raw直接就是 diff 字符串,所以源码里用类型断言把它当作 string 使用。
三、把 diff 文本解析成文件列表
拿到 diff 文本后,src/parse.ts 负责逐行"读懂"它。unified diff 的格式非常规整,解析器只需关注几个关键行:
| diff 中的行 | 含义 | 解析动作 |
|---|---|---|
diff --git a/... b/... |
新文件段开始 | 开启下一个文件记录 |
--- a/路径 / +++ b/路径 |
源路径 / 目标路径 | 出现 /dev/null 则判定为新增或删除 |
@@ ... @@ |
hunk 开始 | 统计后续 +/- 行,得到增删行数 |
rename from/to |
重命名 | 标记为 renamed |
Binary files ... differ |
二进制文件 | 标记 binary 并跳过内容 |
解析结果被规整为统一的结构,类型定义在 src/types.ts 中:每个文件包含 type(added / deleted / modified / renamed)、from、to、additions、deletions 等字段,为下一步构建树结构做好准备。
四、从文件列表到目录树
src/print.ts 把扁平的文件列表组装成嵌套的目录树,再用 ├──、└──、│ 等制表符递归渲染。每个文件行前面还会带上状态标记,例如:
├── src/
│ ├── parse.ts (M +7, -2)
│ └── print.ts (M +131, -0)
└── README.md (M +18, -98)
这样一来,评审者不用逐个点开文件,就能快速判断:哪些目录被触碰了、改动集中在哪里、哪个文件改动最大。
五、快速上手:一键接入你的仓库
在仓库的 .github/workflows/ 下新建 workflow 文件即可,配置非常简单 ✅:
name: 'PR Diff Tree'
on:
pull_request:
types: [opened, synchronize]
jobs:
dump:
runs-on: ubuntu-latest
steps:
- uses: wadackel/github-pr-diff-tree@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
几个值得注意的设计细节:
- 评论只有一条:Action 会在评论里嵌入一个 HTML 注释标记(
<!-- wadackel/github-pr-diff-tree -->),下次触发时先查找已有评论——找到就更新,找不到才新建,避免 PR 被刷屏(见 src/main.ts)。 - 输入项:唯一必填项是
token,用于调用 API,定义在 action.yml 中。 - 运行环境:Action 使用 Node.js 打包产物运行,构建与测试脚本见 package.json。
六、小结
回顾一下 github-pr-diff-tree 的技术链路,其实就是四步:
- 🎯 用
mediaType: { format: 'diff' }让 API 直接返回 PR diff 文本 - 📄 按 unified diff 规范逐行解析出文件列表与增删行数
- 🌲 将文件列表组装为目录树并渲染输出
- 💬 以"更新已有评论"的方式发布到 PR
mediaType 控制响应格式这个技巧本身同样适用于其他 GitHub API 场景(比如请求 patch、html 等格式),学会它,你在处理任何 GitHub 数据时都会多一把利器。想要了解完整的用法与贡献流程,可以参阅 README.md。
