求助：Upwork GraphQL API非空字段amount返回null致查询失败

问题场景 #

我在集成Upwork的GraphQL API时，调用marketplaceJobPostingsSearch接口执行职位搜索，遇到了运行时GraphQL错误。

执行的查询代码 #

const SEARCH_JOBS_QUERY = `
query(
  $marketPlaceJobFilter: MarketplaceJobPostingsSearchFilter,
  $searchType: MarketplaceJobPostingSearchType,
  $sortAttributes: [MarketplaceJobPostingSearchSortAttribute]
) {
  marketplaceJobPostingsSearch(
    marketPlaceJobFilter: $marketPlaceJobFilter,
    searchType: $searchType,
    sortAttributes: $sortAttributes
  ) {
    totalCount
    edges
    {
      node {
        id
        title
        createdDateTime
        description
        duration
        durationLabel
        engagement
        ciphertext
        amount {
            rawValue
          currency
        }
        skills {
          name
          prettyName
        }
          hourlyBudgetMin{
          rawValue
          currency
          displayValue
          }
          hourlyBudgetMax{
          rawValue
          currency
          displayValue
          }
        
        experienceLevel
        category
        subcategory
        client {
          totalSpent {
              rawValue
            currency
          }
          totalHires
          totalPostedJobs
          totalReviews
          companyName
          verificationStatus
          location {
            country
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
`;

API Schema定义 #

根据Upwork提供的API Schema，amount字段被声明为非空类型：

amount: Money!

实际错误信息 #

但部分搜索结果的amount字段返回null，触发GraphQL错误：

The field at path '/marketplaceJobPostingsSearch/edges[26]/node/amount'
was declared as a non null type, but the code involved in retrieving
data has wrongly returned a null value.

由于GraphQL的null冒泡机制，响应中会包含errors数组，导致我的数据同步流程失败。而我的应用中已经将amount定义为可选类型：

amount: UpworkJobAmount | null;

我的问题 #

1. Upwork是否为市场搜索结果提供了其他可空的预算字段？
2. 在此类场景下，GraphQL客户端是否应该容忍包含部分errors的响应？
3. 是否有其他开发者遇到过Upwork GraphQL API违反非空契约的情况？

问题解答与最佳实践 #

1. 可替代的预算字段 #

Upwork提供了hourlyBudgetMin和hourlyBudgetMax这两个可空的小时预算字段，你已经在查询中包含了它们。此外，结合职位的engagement类型（按小时/固定项目），可以区分处理：

• 若为固定项目类型，优先尝试使用amount，若为null则用hourlyBudget字段作为补充；
• 若为按小时类型，直接使用hourlyBudgetMin/hourlyBudgetMax即可。

2. 客户端对部分错误的处理策略 #

面对API违反非空契约的情况，客户端可以通过以下方式容错：

• 配置错误策略：如果使用Apollo Client等工具，设置errorPolicy: 'all'，这样请求不会因单个字段错误而失败，仍能获取其他正常数据，再在业务逻辑中过滤或处理amount为null的条目；
• 拆分查询：将amount字段拆分为单独的查询，避免单个字段错误影响整个列表数据的获取；
• 本地默认值：在接收数据后，手动为amount为null的条目设置默认值（如{ rawValue: 0, currency: 'USD' }），保证同步流程不中断。

3. Upwork API的非空契约问题 #

不少开发者在Upwork开发者社区反馈过类似问题：API Schema标注为非空的字段实际返回null，这类问题多为Upwork后端的逻辑bug。建议：

• 向Upwork开发者支持提交工单，附带具体查询参数、错误日志和相关职位ID，推动官方修复；
• 关注Upwork API的更新日志，官方会不定期修复这类契约不一致的问题。

内容的提问来源于stack exchange，提问作者Unas Mirza