咨询：修改GraphQL Mutation返回类型的向后兼容方案

方案1：将MutationResult改为接口，让新类型实现该接口 #

这是最优雅的向后兼容方案，无需新增Mutation，同时支持新旧客户端：

步骤1：修改GraphQL定义 #

将原有的MutationResult类型改为接口，新增基础实现类BasicMutationResult（供其他未升级的Mutation继续使用），并让PhoneNumber实现该接口：

# 改为接口，定义成功结果的通用字段
interface MutationResult {
    # whether the mutation was successful
    success: Boolean!
}

# 原MutationResult的基础实现，供其他未升级的Mutation使用
type BasicMutationResult implements MutationResult {
    success: Boolean!
}

# 新增的PhoneNumber类型，实现MutationResult接口
type PhoneNumber implements MutationResult {
    success: Boolean! # 固定返回true，满足接口要求
    phoneNumber: String!
    verified: Boolean!
    factorStatus: FactorStatus!
}

enum FactorStatus {
    PENDING_ACTIVATION,
    ACTIVE,
    EXPIRED
}

# 更新Union类型，替换为接口
union AddPhoneNumberResult = FieldErrors | MutationResult

步骤2：服务端实现调整 #

• 其他仍使用原MutationResult的Mutation，返回BasicMutationResult实例即可，无需改动现有逻辑。
• addPhoneNumber成功时返回PhoneNumber实例（success字段固定为true），失败时返回FieldErrors。
• 在graphql-java中，需为MutationResult接口配置类型解析器，确保框架能正确识别返回对象对应的GraphQL类型。

兼容性说明 #

• 旧客户端的原有查询完全可用：当返回PhoneNumber时，... on MutationResult { success }片段会匹配接口字段，拿到true值。
• 新客户端可以扩展查询，同时获取接口字段和PhoneNumber的专属字段。

方案2：保留原Mutation，新增版本化的Mutation #

这是最直接的方案，完全隔离新旧逻辑：

type UserMutation {
    # 保留原有Mutation，维持旧返回类型
    addPhoneNumber(phoneNumber: String!): AddPhoneNumberResult! @RequireAuthorization(secure: true)
    # 新增新版本Mutation，返回包含PhoneNumber的Union
    addPhoneNumberV2(phoneNumber: String!): AddPhoneNumberResultV2! @RequireAuthorization(secure: true)
}

union AddPhoneNumberResultV2 = FieldErrors | PhoneNumber

优缺点 #

• 优点：完全不影响旧客户端，新旧逻辑彻底分离，实现简单。
• 缺点：会增加冗余的Mutation定义，长期维护可能产生接口膨胀。

方案3：在原Union中新增PhoneNumber类型（不推荐） #

直接修改原Union为：

union AddPhoneNumberResult = FieldErrors | MutationResult | PhoneNumber

问题说明 #

旧客户端的... on MutationResult { success }片段不会匹配PhoneNumber类型，因为PhoneNumber不是MutationResult的子类/实现类。这会导致旧客户端在成功场景下拿不到success字段，出现逻辑错误，因此不推荐。

内容的提问来源于stack exchange，提问作者Patrick M