深入探索 Salesforce GraphQL API
我在日常工作中与 Salesforce 数据打交道多年，习惯了用 REST API、SOQL 查询、或是 Composite Graph API 来获取信息。这些工具各有千秋，但总感觉有些场景下用起来不够“优雅”。特别是当我需要为一个前端应用构建数据层时，经常会遇到几个让人头疼的问题：
- 过度获取 (Over-fetching)： REST API 返回的数据字段太多，很多我根本不需要。虽然可以手动指定字段，但当涉及多个相关对象时，工作量会变得很大。
- 请求瀑布 (Request Waterfall)： 如果我需要一个 Account 的信息，以及它所有相关的 Contact 的特定字段，再进一步，可能还需要这些 Contact 关联的一些 Custom Object 的数据，通常就需要发好几次 REST 请求。这不仅增加了网络延迟，也让前端的数据聚合逻辑变得复杂。
- 数据形状固定： REST API 的响应结构往往是服务器预设的。如果前端的展示需求发生变化，我可能需要修改后端接口，或者在前端进行大量的数据转换。
大概是两年前，我听说 Salesforce 开放了 GraphQL API。当时第一反应是：“噢，又一个新的 API？” 但当我深入了解后，发现它在解决我上述痛点方面，有着独特的优势。
初探：GraphQL 的魅力何在？
我最早接触 GraphQL 的概念时，印象最深的就是它的“客户端驱动”特性。客户端可以精确地声明它需要的数据结构和字段。这听起来就像是为前端量身定制的。
我的团队当时正在开发一个新的客户管理界面。这个界面需要在一个视图中展示公司（Account）的基本信息、其主要联系人（Contact）列表，并且每个联系人还需要展示其关联的某个自定义项目（Project__c）的简要状态。如果用传统的 REST API 组合，我可能需要：
- GET /services/data/vXX.X/sobjects/Account/{id} 来获取 Account 详情。
- GET /services/data/vXX.X/sobjects/Account/{id}/Contacts 来获取相关 Contact 列表。
- 对于每个 Contact，可能还需要单独 GET /services/data/vXX.X/sobjects/Contact/{id}/Project__r (如果 Project__c 是 Contact 的子记录)，或者通过 SOQL 查询获取。
这会产生大量的网络请求。或者，我也可以编写一个自定义的 Apex REST 服务来聚合这些数据，但这又增加了后端的开发和维护成本。
GraphQL 在这里展现了它的威力。它允许我通过一个单一的请求，获取所有这些数据，并且只获取我需要的字段：
query AccountWithContactsAndProjects($accountId: ID) {
uiapi {
query {
Account(id: $accountId) {
Id
Name {
value
}
AnnualRevenue {
value
displayValue
}
Contacts {
edges {
node {
Id
Name {
value
}
Title {
value
}
// 假设 Project__c 有一个 lookup 到 Contact
// 并且 GraphQL schema 中将其表示为 Projects__r
Projects__r {
edges {
node {
Id
Name {
value
}
Status__c {
value
displayValue
}
}
}
}
}
}
}
}
}
}
}
这个查询会发送到 Salesforce 的 GraphQL 端点：/services/data/vXX.X/graphql。
为什么选择这个方案？ 对我来说，最大的亮点是：
- 减少网络往返： 一个请求搞定所有相关数据。
- 精确数据获取： 只取我需要的字段，没有额外负担。特别是像
AnnualRevenue这种字段，它同时提供了value和displayValue，我只需要哪个就取哪个。 - 直观的层次结构： 查询的结构与数据的关系结构高度一致，非常易于理解和构建。前端可以直接拿到一个与 UI 结构吻合的数据对象，减少了数据转换的开销。
挑战与判断：它真的能取代所有 API 吗？
尽管 GraphQL 看起来很美好，但在实际应用中，我也遇到了一些需要判断和取舍的地方。
1. 模式探索 (Schema Introspection) 的学习曲线
GraphQL 是强类型的，这意味着你需要知道有哪些对象（Type）、每个对象有哪些字段（Field），以及它们之间如何关联。Salesforce 的对象模型非常庞大且复杂，有很多标准对象、自定义对象、各种关系字段。
Salesforce GraphQL API 允许通过内省（Introspection）查询来获取整个模式。例如，你可以发送一个内省查询来获取所有可用的对象类型及其字段。我发现这对于理解如何将 Salesforce 的 SObject 和字段名映射到 GraphQL 的类型和字段名至关重要。
例如，一个自定义字段 My_Custom_Field__c 在 GraphQL 中可能被表示为 MyCustomField__c 或 MyCustomField，具体取决于其类型和命名约定。而关系字段，例如 Account.Contacts，在 GraphQL 中会被映射为一个名为 Contacts 的连接（Connection），你需要通过 edges 和 node 来遍历。
我的判断： 刚开始会有些困惑，特别是对于自定义对象和关系字段的命名规则。但一旦掌握了内省查询的使用方法，并理解了 Salesforce GraphQL 对 SObject 命名、字段命名以及关系（如 lookup, master-detail）的映射规则，模式探索就变得高效起来。官方文档中的示例和 GraphQL Playground 这样的工具对于这个阶段的学习非常有帮助。
2. 过滤和分页 (Filtering and Pagination)
在 SOQL 中，我们有强大的 WHERE 子句进行过滤，有 LIMIT 和 OFFSET 进行分页。GraphQL 也提供了类似的能力，但语法不同。
Salesforce GraphQL API 使用了标准的 GraphQL 传入参数（arguments）来处理过滤和分页。例如，对于一个集合，你可以使用 where 参数来指定过滤条件，使用 first 和 after 来进行基于游标的分页。
query FilteredContacts($accountId: ID) {
uiapi {
query {
Account(id: $accountId) {
Id
Name { value }
Contacts(
where: { Title: { like: "%Manager%" } },
first: 10,
after: "some_cursor_value"
) {
edges {
node {
Id
Name { value }
Title { value }
}
}
}
}
}
}
}
我的判断： 过滤功能非常强大，支持复杂的逻辑运算符（AND, OR）。分页机制遵循 GraphQL 社区的 Relay 规范，基于游标，对于无限滚动或大型数据集的加载非常友好。相比于传统的 REST API 的基于偏移量的分页，游标分页避免了数据重复或遗漏的问题，尤其是在数据频繁变动时。
3. 变更 (Mutations) 的使用场景
GraphQL 不仅仅可以查询数据，还可以通过 Mutation 来修改数据。Salesforce GraphQL API 也支持创建、更新、删除 SObject 记录。
例如，创建一个新的 Contact：
mutation CreateNewContact($input: ContactCreateInput!) {
uiapi {
mutation {
ContactCreate(input: $input) {
Contact {
Id
Name { value }
}
errors {
message
}
}
}
}
}
// Variables for CreateNewContact mutation
{
"input": {
"Name": "John Doe",
"AccountId": "001xxxxxxxxxxxxxxx" // 假设已有一个 Account ID
}
}
我的判断： Mutation 解决了前端直接进行 DML 操作的需求，避免了编写自定义 Apex REST 服务。对于单个记录的创建、更新、删除，它非常方便。然而，对于复杂的业务逻辑（比如需要多个 DML 操作组成一个事务，或包含复杂的验证规则），我发现我仍然倾向于使用 Apex 触发器、Apex 类或 Flow 来处理，并通过 GraphQL 调用一个简单的更新来触发这些后端逻辑。GraphQL Mutation 更适合那些“薄”的 DML 操作，即直接映射到 Salesforce 记录的增删改。
4. 与其他 Salesforce API 的对比
GraphQL vs. Composite Graph API
这是我内部讨论时经常被问到的一个问题。Composite Graph API 也能通过一个请求聚合多个子请求，并能处理请求间的依赖关系。
- 我的取舍： 如果我只需要按顺序执行几个独立的 REST 请求并聚合结果，或者需要特定顺序的 DML 操作，Composite Graph API 足够用。但如果核心需求是客户端动态定义数据形状和字段，并且需要处理深层嵌套的关系数据，GraphQL 的优势就非常明显了。Composite Graph API 仍然是“服务器驱动”的，它的每一个子请求都相当于一个独立的 REST 调用，返回的字段是固定的（除非手动指定），且其响应结构是链式的，不如 GraphQL 的树状结构直观。
GraphQL vs. REST API (如 SObject Rows)
- 我的取舍： 对于简单地获取单个 SObject 的所有字段，或者进行简单的列表查询，REST API (
/sobjects/SObject/{id}或/sobjects/SObject) 可能更快上手，因为它的路径和参数更直观。但一旦涉及到关联记录、精细字段控制、或者避免过度获取，GraphQL 就能大幅提升效率和开发体验。
GraphQL vs. SOQL (通过 Tooling API 或 Apex)
- 我的取舍： SOQL 依然是 Salesforce 数据查询的终极利器，它的性能通常最优，而且在 Apex 中可以直接操作。如果是在 Apex 代码内部或者通过 Tooling API 进行特定的、复杂的、服务器端的数据处理，SOQL 仍然是首选。GraphQL API 更像是 SOQL 的一个“包装”，但它以一种更标准、更灵活、对前端更友好的方式暴露了这些数据查询能力。
我的当前看法与未解决的问题
通过这段时间的实践，我认为 Salesforce GraphQL API 是一个非常强大的工具，尤其适用于需要：
- 构建现代前端应用： 它们对数据需求多样且不断变化。
- 减少 API 请求次数： 提升用户体验和应用性能。
- 精确控制数据载荷： 避免不必要的网络开销和后端数据转换。
- 处理复杂嵌套的数据关系： 以直观的方式获取整个数据图。
它并没有取代 Salesforce 所有的 API，而是在特定的应用场景下，提供了一个更优的选择。对于大多数客户端驱动的数据获取需求，我倾向于优先考虑 GraphQL。
一些仍待深入探讨或解决的问题：
- 大型数据集与聚合： 当需要处理成千上万条记录，或者进行复杂的聚合计算（如 GROUP BY），GraphQL API 的性能和功能是否能媲美直接的 SOQL 查询，或者说，我是否应该结合使用？目前我的经验主要集中在获取有限数量的记录及其关联数据。
- 批量操作： 如果需要一次性创建、更新或删除大量记录，GraphQL API 的 Mutation 如何支持批处理？目前的文档和实践中，我主要看到的是单条记录的 Mutation。是否有像 Composite API 那样高效的批量 Mutation 机制？
- 自定义业务逻辑的封装： 对于那些不直接映射到 CRUD 的复杂业务操作（例如，一个按钮点击后需要触发一系列的后端计算和数据更新），如何优雅地通过 GraphQL 进行封装和暴露，而不是回退到自定义 Apex REST 接口？
总的来说，Salesforce GraphQL API 打开了一扇新的大门，让开发者能够更灵活、高效地与 Salesforce 数据交互。我期待它未来能提供更丰富的功能和更强大的性能。
评论
发表评论