PR 状态归一化:Closed 为何要展开成 [CLOSED, MERGED],以及 gh pr list 的过滤退化
结论
- 所有平台的 PR 状态都不是二值。 除了
open,至少还存在「关掉没合」和「合并后关闭」两种情况,Bitbucket / YouTrack 用DECLINED表达前者,GitHub 用CLOSED+MERGED表达后者。把 PR 状态设计成isClosed: boolean,是同步类问题的起点。 - 二值模型向上层暴露时,Closed 必须展开成
[CLOSED, MERGED]去过滤;反过来单条读取时,两个枚举值要压回一个 Closed。 这是 decap-cms 在GraphQLAPI.ts里已经固化的做法。 - 过滤参数是列表,但 CLI 是单值。 GraphQL 的
states: [PullRequestState!]支持多值,gh pr list --state只接受单值,带--search时走 Search API,所有条件压成一个查询字符串,多状态和 OR 都不支持。结果是静默少数据,少掉的通常是 merged 那一半。 - GitLab 多一个
locked,而且是过渡态。 按state=locked过滤基本查不到,webhook 的object_attributes.action里也没有locked。 - 归一化实现 = 映射表 +
Unknown兜底 + 比较时用状态集合而不是布尔。 中间模型不留Unknown,遇到新状态就只能 panic 或静默丢弃。 - 站内 #8276 已经写过 GitHub 内部的
CLOSED ≠ MERGED、RESTstate过滤、closing keywords 与state_reason的写法差异,本篇不重复;这里只讨论跨 provider 的枚举归一化,以及过滤参数退化时少数据的路径。下文涉及 GitHub 三值语义的地方均一句话带过。
各平台取值对照
| 平台 / 接口 | 取值 | 过滤参数形态 | 备注 |
|---|---|---|---|
GitHub GraphQL PullRequestState | OPEN CLOSED MERGED | states: [PullRequestState!],多值 | PullRequest.state 类型为 PullRequestState!,非空 |
| GitHub REST | open closed | state=open|closed|all | decap-cms 注释记录的二值语义 |
gh pr list | open|closed|merged|all | 单值,传逗号直接报错 | 带 --search 时走 Object#search |
| GitLab MR API | opened closed merged locked | state=all|opened|closed|locked|merged | 响应字段 state 取值相同 |
| GitLab Webhook | state_id 1/2/3/4;state 同上 | — | object_attributes.action 没有 locked |
| Bitbucket Server / Stash | OPEN MERGED DECLINED | — | 3.11.3 javadoc 取值一致 |
| YouTrack | OPEN MERGED DECLINED | — | state / previousState 只读快照 |
| code-system-graph-core | Open Closed Merged Unknown | — | 跨 provider 中间模型 |
octocat-rs github_rest | Closed Open | — | 对应 REST 语义 |
GitHub GraphQL:states 是列表
docs.github.com/en/graphql/reference/pulls 的原文:
PullRequestState - enum
- CLOSED: A pull request that has been closed without being merged.
- MERGED: A pull request that has been closed by being merged.
- OPEN: A pull request that is still open.
PullRequest.state 的类型是 PullRequestState!,非空,永远有值。过滤参数在 repos 参考 里写作:
states([PullRequestState!]): A list of states to filter the pull requests by.
同一个参数也出现在 Ref.associatedPullRequests、User.pullRequests 上。关键是它是列表,一次可以传 CLOSED 和 MERGED:
query($owner:String!,$name:String!,$states:[PullRequestState!]){
repository(owner:$owner,name:$name){
pullRequests(first:50, states:$states){ nodes { number state mergedAt } }
}
}
{ "states": ["CLOSED", "MERGED"] }
为什么二值模型必须把 Closed 展开成两个值:上层如果只有 Open / Closed,那么「已关闭」这个集合在 GraphQL 里对应的是 CLOSED 与 MERGED 的并集。只传 CLOSED,合并后关闭的 PR 全部漏掉;只传 MERGED,被拒绝的 PR 全部漏掉。这两个值缺一不可,等价于 state != OPEN。反过来做单条读取时,CLOSED 和 MERGED 都要压回 Closed,否则上层拿到的枚举和列表接口对不上。
decap-cms 的 packages/decap-cms-backend-github/src/GraphQLAPI.ts 注释把这件事写得很直白:
// https://developer.github.com/v4/enum/pullrequeststate/
// GraphQL state: [CLOSED, MERGED, OPEN]
// REST API state: [closed, open]
同文件 getPullRequests() 的真实映射:
if (state === PullRequestState.Open) { states = ['OPEN']; }
else if (state === PullRequestState.Closed) { states = ['CLOSED', 'MERGED']; }
else { states = ['OPEN', 'CLOSED', 'MERGED']; }
getPullRequest(number) 单条查询则是反向压缩:
const state = data.repository.pullRequest.state === 'OPEN' ? PullRequestState.Open : PullRequestState.Closed;
这套「列表展开、单条压缩」的不对称,是二值模型和三元后端之间必须存在的翻译层。
GitHub REST 与 gh cli:过滤参数在 CLI 层退化成单值
REST 是二值(closed / open),这一点与上面对应,不再展开。
CLI 层的退化更值得注意。gh pr list 直接传多值会失败,错误原文:
$ gh pr list --state open,merged
invalid argument "open,merged" for "-s, --state" flag: valid values are {open|closed|merged|all}
cli/cli#5295 里 mislav 的回复:
Additionally, we transparently use two separate APIs for listing PRs: the GraphQL list API and the Issues Search API. The latter API does not support this syntax:
is:open,merged.
cli/cli#7728 里 mattruggio 把两条路径拆开说明:
- 不带
--search时走Repository#pullRequests,states参数类型是[PullRequestState!],支持多值; - 带
--search时走Object#search,没有独立的states参数,所有过滤条件压成一个查询字符串(如is:pr state:open),后端解析不支持多状态,也不支持 OR。
也就是说,同一个 --state 参数,在两条代码路径上能力不同:不带 search 时背后是列表参数,带 search 时背后是一段查询字符串语法。Search 路径下 is:pr state:closed 是否包含 merged 的 PR,我没有实测,但按「不支持多状态也不支持 OR」的说法,它只能落到某一个值上,另一端就丢了。
#5295 里给出的绕法有两个:调两次 gh pr list 再合并结果;或者直接用 Repository.pullRequests 的 GraphQL 查询。
GitLab:多一个 locked,以及 state 与可合并性是两回事
docs.gitlab.com/api/merge_requests/ 原文:
state参数:Returns all merge requests (all) or just those that areopened,closed,locked, ormerged. Defaults toall.
响应字段:
state— Possible values:opened,closed,merged, orlocked.
文档还有一句提示:
Searching by
lockedgenerally returns no results as that state is short-lived and transitional.
Webhook(docs.gitlab.com/user/project/integrations/webhook_events/)里字段是另外一套:
state_id: Integer (1: opened, 2: closed, 3: merged, 4: locked)
state: String (opened, closed, merged, locked)
object_attributes.action: open / close / reopen / update / merge
object_attributes.action 里没有 locked 对应的动作,locked 只能从 state 字段看到。这意味着事件驱动的同步逻辑如果只读 action,永远观察不到 locked;如果按 state=locked 去轮询,又会因为它是过渡态而基本查不到。两种情况都要按“可能观测不到”处理。
另外 merge_status(已在 15.6 弃用)和 detailed_merge_status(mergeable / not_approved / need_rebase / draft_status / not_open / conflict 等)是可合并性,与 state 不是一回事,不能混进同一个枚举里归一化。
Bitbucket Server / Stash:DECLINED 代替 CLOSED
docs.atlassian.com/bitbucket-server/javadoc/10.2.0/.../PullRequestState.html 原文:
public enum PullRequestState
- DECLINED: The pull request has been declined.
- MERGED: The pull request has been accepted and merged.
- OPEN: The pull request is open.
老版本 Stash 3.11.3 的 javadoc 同样是 DECLINED / MERGED / OPEN,并提供 fromId(int)、getId()、valueOf(String)、values()。
这里的语义分叉在于:GitHub 用 CLOSED(没合就关)和 MERGED(合并后关闭)两个值区分两种终态,Bitbucket 只用一个 DECLINED 表示“没合就关”。跨平台归一化时如果把 DECLINED 直接丢掉,被拒绝的 PR 会从「已关闭」集合里消失。
YouTrack:状态是快照,不是可变字段
jetbrains.com/help/youtrack/devportal/api-entity-PullRequestState.html 里 states 为 OPEN / MERGED / DECLINED。
v1-PullRequest.html 对 state 与 previousState 的语义写得很明确:两者均为 Read-only。
Pull request state changes create new snapshots instead of updating existing PullRequest entities. In an on-change rule, inspect
ctx.issue.pullRequests.addedand comparestatewithpreviousStateto detect a transition. Do not inspect the complete set or calllast(), because a persisted snapshot can match again on a later issue update.
这段对同步逻辑的约束是具体的:不能对 pullRequests 全量做状态比对,也不能取 last(),必须比对 added 里新增快照的 state 与 previousState。同一个快照可能在后续 issue 更新时再次匹配,全量扫描会重复触发状态变更。
归一化实现:映射表 + Unknown 兜底
中间模型的形状参考 docs.rs 上 code-system-graph-core 的 PullRequestState:
pub enum PullRequestState { Open, Closed, Merged, Unknown }
注释原文:
Provider-neutral pull-request state. Closed = "Closed without a confirmed merge." Unknown = "Provider returned an unrecognized state."
对照 octocat-rs 的 github_rest::model::pull_requests::PullRequestState,它只有 Closed / Open 两个变体,对应 REST 语义,不能直接拿来当跨平台的中间模型。
TypeScript 版本:
type UnifiedState = 'open' | 'closed' | 'merged' | 'declined' | 'unknown';
function fromGitHub(s: 'OPEN' | 'CLOSED' | 'MERGED'): UnifiedState {
switch (s) {
case 'OPEN': return 'open';
case 'CLOSED': return 'closed';
case 'MERGED': return 'merged';
default: return 'unknown'; // 类型收窄后不可达,运行时仍需兜底
}
}
function fromGitLab(s: string): UnifiedState {
switch (s) {
case 'opened': return 'open';
case 'closed': return 'closed';
case 'merged': return 'merged';
case 'locked': return 'unknown'; // 过渡态,不映射为终态
default: return 'unknown';
}
}
function fromBitbucketOrYouTrack(s: 'OPEN' | 'MERGED' | 'DECLINED'): UnifiedState {
switch (s) {
case 'OPEN': return 'open';
case 'MERGED': return 'merged';
case 'DECLINED': return 'declined';
default: return 'unknown';
}
}
反向展开,和 decap-cms 的逻辑一致:
function gitHubStatesFilter(want: 'open' | 'closed' | 'all'): Array<'OPEN' | 'CLOSED' | 'MERGED'> {
if (want === 'open') return ['OPEN'];
if (want === 'closed') return ['CLOSED', 'MERGED'];
return ['OPEN', 'CLOSED', 'MERGED'];
}
比较时用状态集合,不要用布尔:
const isOpen = (s: UnifiedState) => s === 'open';
const isMerged = (s: UnifiedState) => s === 'merged';
// “未合并即关闭”:GitHub 的 closed 与 Bitbucket/YouTrack 的 declined 语义等价
const isDismissed = (s: UnifiedState) => s === 'closed' || s === 'declined';
const isTerminal = (s: UnifiedState) => s !== 'open' && s !== 'unknown';
Unknown 兜底的必要性:所有映射函数的输入都是外部字符串,不是编译期可穷举的封闭集合。GitLab 的 locked 就是现成例子,它不在 GitHub 的三值里,也不该被压成 closed 或 merged 任何一个终态;provider 升级新增枚举值时同理。没有 unknown 分支,遇到不认识的值只有两种结局:解析时 panic,或者被 default 静默归到某个已有状态里,后者在同步场景下比 panic 更难排查。所有 unknown 都不应参与终态判断和状态迁移比较。
一句话收尾
跨平台同步 PR 状态,需要处理的是三个不同层次的问题:枚举取值不一致(GitHub 三值、GitLab 四值、Bitbucket/YouTrack 三值且用 DECLINED)、过滤参数能力不一致(GraphQL 多值、REST 二值、CLI 单值、Search 单字符串)、以及快照型 provider(YouTrack)不提供可变字段。任一层按二值处理,数据都会少一部分,且不会报错。