KeystoneJS中findOne查询缓存策略失效问题解析

问题背景

在KeystoneJS项目中，当开发者尝试为列表类型设置缓存提示(cacheHint)时，发现一个有趣的缓存失效现象：直接查询列表(findMany)时缓存策略能正常工作，但当同样的查询作为嵌套查询出现在findOne查询中时，缓存策略却失效了。

现象重现

假设我们有以下两个模型定义：

const COMMON_CACHE_HINT = {
  maxAge: 60,
  scope: 'PUBLIC',
}

const lists = lists({
  User: list({
    fields: {
      name: text(),
      posts: relationship({
        ref: 'Post.user',
        many: true,
      }),
    },
    graphql: {
      cacheHint: COMMON_CACHE_HINT,
    },
  }),
  Post: list({
    fields: {
      user: relationship({
        ref: 'User.posts',
        many: false,
      }),
      category: text(),
      title: text(),
      body: json(),
    },
    graphql: {
      cacheHint: COMMON_CACHE_HINT,
    },
  }),
})

当执行以下查询时，缓存策略正常工作：

query {
  posts(where: { category: { equals: "Category_1" } }) {
    title
    body
  }
}

但当同样的查询作为嵌套查询出现时：

query {
  user(where: { id: "22fc8814-3845-4287-bbbe-34cb65ecebb6" }) {
    name
    posts(where: { category: { equals: "Category_1" } }) {
      title
      body
    }
  }
}

缓存策略失效，响应头中返回"no-cache"。

技术分析

Apollo缓存策略机制

Apollo Server采用"最严格优先"的缓存策略计算原则。这意味着：

1. 对于包含多个字段的查询，Apollo会收集所有字段的缓存提示
2. 最终应用的缓存策略将是所有字段中最严格的那个
3. 如果任一字段没有明确设置缓存提示，默认会采用"no-cache"

KeystoneJS实现问题

在KeystoneJS的源码中，发现了两个关键实现问题：

1. findOne解析器缺少缓存提示应用：在core/queries/resolvers.ts中，findMany和count解析器都正确应用了缓存提示，但findOne解析器却没有相应的处理逻辑。

2. GraphQL字段解析器信息未传递：在core/queries/index.ts中，findOne字段解析器没有将GraphQL的info对象传递给底层解析函数，导致无法获取缓存相关信息。

解决方案

修改findOne解析器

需要在findOne解析器返回结果前添加缓存提示处理逻辑：

if (list.cacheHint) {
  maybeCacheControlFromInfo(info)
    ?.setCacheHint(list.cacheHint({
      result,
      operationName: info.operation.name?.value,
      meta: false
    }))
}

传递解析器信息

需要修改字段解析器，确保将info对象传递给底层findOne函数：

async resolve (_rootVal, args, context, info) {
  return queries.findOne(args, list, context, info)
}

技术影响

这个修复将带来以下改进：

1. 一致的缓存行为：无论查询是直接执行还是作为嵌套查询执行，都将应用相同的缓存策略。

2. 性能提升：正确配置的缓存可以显著减少重复查询的数据库访问，提高系统整体性能。

3. 开发者体验改善：缓存配置的行为更加可预测，减少了开发中的困惑。

最佳实践建议

1. 统一设置缓存策略：为所有列表类型设置适当的缓存策略，即使是那些不常变更的数据。

2. 考虑数据敏感性：对于包含敏感信息的列表，谨慎设置scope为"PUBLIC"。

3. 测试缓存行为：在开发过程中，使用工具检查响应头，验证缓存策略是否按预期工作。

4. 监控缓存命中率：在生产环境中监控缓存效果，根据实际情况调整maxAge等参数。

总结

KeystoneJS中的这个缓存策略问题展示了GraphQL实现中一个常见的陷阱：嵌套查询的缓存行为可能因为某个环节的缺失而完全失效。通过理解Apollo的缓存策略计算机制和仔细检查解析器实现，我们能够定位并修复这个问题，确保系统缓存行为的一致性和可预测性。