编程 PR 状态归一化:Closed 为何要展开成 [CLOSED, MERGED],以及 gh pr list 的过滤退化

2026-11-22 00:04:32

PR 状态归一化:Closed 为何要展开成 [CLOSED, MERGED],以及 gh pr list 的过滤退化

结论

  1. 所有平台的 PR 状态都不是二值。 除了 open,至少还存在「关掉没合」和「合并后关闭」两种情况,Bitbucket / YouTrack 用 DECLINED 表达前者,GitHub 用 CLOSED + MERGED 表达后者。把 PR 状态设计成 isClosed: boolean,是同步类问题的起点。
  2. 二值模型向上层暴露时,Closed 必须展开成 [CLOSED, MERGED] 去过滤;反过来单条读取时,两个枚举值要压回一个 Closed。 这是 decap-cms 在 GraphQLAPI.ts 里已经固化的做法。
  3. 过滤参数是列表,但 CLI 是单值。 GraphQL 的 states: [PullRequestState!] 支持多值,gh pr list --state 只接受单值,带 --search 时走 Search API,所有条件压成一个查询字符串,多状态和 OR 都不支持。结果是静默少数据,少掉的通常是 merged 那一半。
  4. GitLab 多一个 locked,而且是过渡态。 按 state=locked 过滤基本查不到,webhook 的 object_attributes.action 里也没有 locked。
  5. 归一化实现 = 映射表 + Unknown 兜底 + 比较时用状态集合而不是布尔。 中间模型不留 Unknown,遇到新状态就只能 panic 或静默丢弃。
  6. 站内 #8276 已经写过 GitHub 内部的 CLOSED ≠ MERGED、REST state 过滤、closing keywords 与 state_reason 的写法差异,本篇不重复;这里只讨论跨 provider 的枚举归一化,以及过滤参数退化时少数据的路径。下文涉及 GitHub 三值语义的地方均一句话带过。

各平台取值对照

平台 / 接口取值过滤参数形态备注
GitHub GraphQL PullRequestStateOPEN CLOSED MERGEDstates: [PullRequestState!],多值PullRequest.state 类型为 PullRequestState!,非空
GitHub RESTopen closedstate=open|closed|alldecap-cms 注释记录的二值语义
gh pr listopen|closed|merged|all单值,传逗号直接报错带 --search 时走 Object#search
GitLab MR APIopened closed merged lockedstate=all|opened|closed|locked|merged响应字段 state 取值相同
GitLab Webhookstate_id 1/2/3/4;state 同上—object_attributes.action 没有 locked
Bitbucket Server / StashOPEN MERGED DECLINED—3.11.3 javadoc 取值一致
YouTrackOPEN MERGED DECLINED—state / previousState 只读快照
code-system-graph-coreOpen Closed Merged Unknown—跨 provider 中间模型
octocat-rs github_restClosed 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 are opened, closed, locked, or merged. Defaults to all.

响应字段:

state — Possible values: opened, closed, merged, or locked.

文档还有一句提示:

Searching by locked generally 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.added and compare state with previousState to detect a transition. Do not inspect the complete set or call last(), 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)不提供可变字段。任一层按二值处理,数据都会少一部分,且不会报错。

复制全文 生成海报 PullRequestState GitHub GraphQL GitLab Bitbucket API

推荐文章

程序员茄子在线接单