Apollo Client 4.0：变更mutation返回类型为ApolloQueryResult的技术解析

背景与现状

在Apollo Client的当前实现中，client.mutate(...)方法返回的是FetchResult类型。这个类型原本设计用于表示原始的GraphQL响应结果。然而，随着Apollo Client的发展，团队发现这种设计存在一些局限性，特别是在错误处理方面。

问题分析

当前实现中存在两个主要问题：

1. 错误处理不一致：网络错误总是会触发Promise的rejection，而不管errorPolicy如何设置。这与查询(queries)的行为不一致。

2. 类型限制：FetchResult类型不允许包含error字段，这使得无法将现有的错误处理行为统一到与查询相同的模式。

解决方案

Apollo Client团队决定将client.mutate(...)的返回类型从FetchResult改为ApolloQueryResult。这一变更带来了几个重要优势：

1. 行为统一：现在mutation和query的错误处理方式完全一致，开发者可以使用相同的模式处理两种操作中的错误。

2. 更完善的错误处理：errorPolicy现在可以同时影响网络错误和GraphQL错误的行为，而不仅仅是后者。

3. 类型安全：ApolloQueryResult提供了更完整的类型定义，能够更好地表示可能出现的各种结果情况。

技术细节

变更前

// 旧版本
const result: FetchResult = await client.mutate(...);

变更后

// 新版本
const result: ApolloQueryResult = await client.mutate(...);

新的返回类型ApolloQueryResult包含以下关键属性：

• data: 包含GraphQL返回的数据
• error: 包含可能出现的错误信息
• loading: 表示操作是否正在进行中
• networkStatus: 提供更详细的网络状态信息

影响范围

这一变更属于破坏性变更(breaking change)，主要影响：

1. 直接依赖FetchResult类型进行类型检查的代码
2. 对mutation结果进行特定错误处理的逻辑
3. 使用了高级类型推断的TypeScript代码

迁移建议

对于现有项目，迁移到新版本时需要注意：

1. 检查所有client.mutate(...)的调用点，确保错误处理逻辑适应新的行为
2. 更新类型定义，将FetchResult替换为ApolloQueryResult
3. 测试网络错误场景，确认它们现在遵循errorPolicy的设置

设计理念

这一变更体现了Apollo Client团队的一些核心设计理念：

1. 一致性原则：保持API的行为一致性，减少开发者的认知负担
2. 渐进增强：在保持核心功能稳定的前提下，逐步改进API设计
3. 开发者体验：通过更合理的类型系统，提供更好的开发时安全保障

总结

Apollo Client 4.0将mutation操作的返回类型统一为ApolloQueryResult，这一变更虽然带来了短期内的迁移成本，但从长期来看显著提升了API的一致性和可预测性。开发者现在可以用相同的方式处理query和mutation的结果，减少了代码中的特殊处理逻辑，使得应用更加健壮和可维护。