服务器端缓存

1
type Comment {
2
  post: Post! @cacheControl(maxAge: 120)
3
  body: String!
4
}

在您的解析器中（动态）

您可以在解析特定的字段值时决定如何缓存它。为了支持此功能，Apollo Server 的 缓存控制插件 在传递给每个 resolver 的 info 参数 中提供了一个 cacheControl 对象。

cacheControl.setCacheHint

The cacheControl 对象包含一个 setCacheHint 方法，您可以通过以下方式调用它：

1
import { cacheControlFromInfo } from '@apollo/cache-control-types';
2

3
const resolvers = {
4
  Query: {
5
    post: (_, { id }, _, info) => {
6
      // Access ApolloServerPluginCacheControl's extension of the GraphQLResolveInfo object
7
      const cacheControl = cacheControlFromInfo(info)
8
      cacheControl.setCacheHint({ maxAge: 60, scope: 'PRIVATE' });
9
      return find(posts, { id });
10
    },
11
  },
12
};

The setCacheHint 方法接受一个具有 maxAge 和 scope 字段的对象。

cacheControl.cacheHint

此对象代表当前 cache hint 的字段。其字段包括以下内容：

• 字段的当前 maxAge 和 scope（可能已静态设置）

• A restrict 方法，它类似于 setCacheHint 但不能 relax 现有的提示设置：

  TypeScript

  1
  import { cacheControlFromInfo } from '@apollo/cache-control-types';
  2
  
  3
  // Access ApolloServerPluginCacheControl's extension of the GraphQLResolveInfo object
  4
  const cacheControl = cacheControlFromInfo(info)
  5
  
  6
  // If we call this first...
  7
  cacheControl.setCacheHint({ maxAge: 60, scope: 'PRIVATE' });
  8
  
  9
  // ...then this changes maxAge (more restrictive) but NOT scope (less restrictive)
  10
  cacheControl.cacheHint.restrict({ maxAge: 30, scope: 'PUBLIC' });

  复制

cacheControl.cacheHintFromType

此方法允许您获取特定 object 类型的默认缓存提示。这在解决可能返回多种对象类型的联合或接口字段时非常有用。

计算缓存行为

为了安全起见，每个 操作响应的缓存行为是根据结果的字段中 最严格的 缓存提示来计算的：

• 响应的 maxAge 等于所有字段中最小的 maxAge。如果该值为 0，则整个结果将不会被缓存。
• 响应的 scope 如果任何字段的 scope 是 PRIVATE，则为 PRIVATE。

默认 maxAge

默认情况下，以下模式字段除非您指定一个，否则具有 maxAge 为 0：

• 根字段（即 Query、Mutation 和 Subscription 类型的字段）
  • 因为每个 GraphQL 操作都包含一个根字段，这意味着默认情况下，除非您设置缓存提示，否则不会缓存任何操作结果！
• 返回非标量类型的字段（对象、接口或联合）或非标量类型的列表。

您可以自定义此默认值。

所有其他模式字段（即非根字段返回标量类型）则从其父字段继承其默认maxAge

为什么这些是默认的maxAge值？

我们关于Apollo服务器缓存的哲学是，只有当响应的每一部分都同意可缓存时，才应该将响应视为可缓存的。同时，我们认为开发者不应该必须指定模式中每个字段的缓存提示。

因此，我们遵循以下启发式方法

• 根字段解析器非常有可能检索数据（因为这些字段没有父字段），因此我们将它们的默认maxAge设置为0以避免自动缓存不应缓存的数据。
• 解析器对于其他非标量字段（对象、接口和联合）也普遍检索数据，因为它们包含任意数量的字段。因此，我们也将它们的默认maxAge设置为0。
• 标量，非根字段解析器很少检索数据，而是通常通过parent参数填充数据。因此，这些字段从其父字段继承默认的maxAge以减少模式混乱。

当然，这些启发式方法并不总是正确的！例如，在非标根标量字段的解析器可能实际上检索外部数据。您可以为任何具有不希望的行为的默认值的字段设置自己的缓存提示。

理想情况下，您可以为每个实际上从数据源（如数据库或REST API）检索数据的解析器字段提供maxAge。大多数其他字段可以从中继承其缓存提示的父级（具有不经常检索数据的解析器的字段）。有关更多信息，请参阅推荐入门使用方法。

设置不同的默认maxAge

您可以设置一个默认的maxAge，它适用于其它否则接收默认maxAge为0的字段。

通过将缓存控制插件传递给 ApolloServer 构造函数来设置您的默认 maxAge，如下所示：

1
import { ApolloServerPluginCacheControl } from '@apollo/server/plugin/cacheControl';
2

3
const server = new ApolloServer({
4
  // ...other options...
5
  plugins: [ApolloServerPluginCacheControl({ defaultMaxAge: 5 })],  // 5 seconds
6
});

推荐初始使用方法

您通常不需要为您的模式中的每个 field 指定缓存提示。相反，我们建议从以下几个方面开始：

• 对于应该 永不 缓存的 fields，明确地将 maxAge 设置为 0。

• 为每个具有从数据源（如数据库或REST API）实际获取数据的解析器的 fields 设置 maxAge。你可以基于相关数据的更新频率来设置 maxAge 的值。

• 为每个返回非-标量类型的其他非根 field 设置 inheritMaxAge: true。

  • 请注意，您只能以 inheritMaxAge 静态 的方式设置它。

示例 maxAge 计算

考虑以下模式

1
type Query {
2
  book: Book
3
  cachedBook: Book @cacheControl(maxAge: 60)
4
  reader: Reader @cacheControl(maxAge: 40)
5
}
6

7
type Book {
8
  title: String
9
  cachedTitle: String @cacheControl(maxAge: 30)
10
}
11

12
type Reader {
13
  book: Book @cacheControl(inheritMaxAge: true)
14
}

让我们看看一些查询及其相应的 maxAge 值：

1
# maxAge: 0
2
# Query.book doesn't set a maxAge and it's a root field (default 0).
3
query GetBookTitle {
4
  book { # 0
5
    cachedTitle # 30
6
  }
7
}
8

9
# maxAge: 60
10
# Query.cachedBook has a maxAge of 60, and Book.title is a scalar, so it
11
# inherits maxAge from its parent by default.
12
query GetCachedBookTitle {
13
  cachedBook { # 60
14
    title # inherits
15
  }
16
}
17

18
# maxAge: 30
19
# Query.cachedBook has a maxAge of 60, but Book.cachedTitle has
20
# a maxAge of 30.
21
query GetCachedBookCachedTitle {
22
  cachedBook { # 60
23
    cachedTitle # 30
24
  }
25
}
26

27
# maxAge: 40
28
# Query.reader has a maxAge of 40. Reader.Book is set to
29
# inheritMaxAge from its parent, and Book.title is a scalar
30
# that inherits maxAge from its parent by default.
31
query GetReaderBookTitle {
32
  reader { # 40
33
    book { # inherits
34
      title # inherits
35
    }
36
  }
37
}

与联邦一起使用

在使用 Apollo Federation 时，@cacheControl 指令和 CacheControlScope 枚举可以在 subgraph 的模式中定义。基于 Apollo Server 的 subgraph 将根据非联邦 Apollo Server 向客户端发送响应的方式计算和设置它向网关发送的响应的缓存提示。然后，网关将根据所有子图在 查询计划 执行中接收到的最严格设置来计算整体响应的缓存提示。

设置实体缓存提示

Subgraph schemas 包含在 Query 类型上的 _entities 根 field，因此所有需要 entity 解析 query plans均会默认将 maxAge 设置为 0。要覆盖此默认行为，您可以在实体的定义中添加一个 @cacheControl 指令：

1
type Book @key(fields: "isbn") @cacheControl(maxAge: 30) {
2
  isbn: String!
3
  title: String
4
}

当 _entities 字段被解析时，它将检查适用于缓存提示的具体类型（在上面的示例中为 Book 类型）并应用该提示。

要动态设置缓存提示，在 __resolveReference 解析器的 info 参数中也可以使用 cacheControl 对象及其方法。

在网关中覆盖子图缓存提示

如果一个子图没有指定 max-age，网关将假设其响应（以及随之而来的整体响应）不能被缓存。要覆盖此行为，你可以在 RemoteGraphQLDataSource 的 didReceiveResponse 方法中设置 Cache-Control 头。

另外，如果网关应该忽略将影响操作缓存策略的子图的 Cache-Control 响应头，则可以将 RemoteGraphQLDataSource 的 honorSubgraphCacheControlHeader 属性设置为 false（默认值为 true）：

1
const gateway = new ApolloGateway({
2
  // ...
3
  buildService({ url }) {
4
    return new RemoteGraphQLDataSource({
5
      url,
6
      honorSubgraphCacheControlHeader: false;
7
    });
8
  }
9
});

将 honorSubgraphCacheControlHeader 设置为 false 的效果是，对响应的缓存能力没有任何影响。换句话说，此属性不会决定响应是否可缓存，但它排除了子图的 Cache-Control 头在网关计算中的考虑。如果在计算整体 Cache-Control 头时排除了所有子图，发送给客户端的响应将不会被缓存。

使用 CDN 进行缓存

默认情况下，Apollo Server 会为所有响应发送一个 Cache-Control 头，该头描述了响应的缓存策略。

当响应可缓存时，头部的格式如下

1
Cache-Control: max-age=60, private

当响应不可缓存时，头的值是 Cache-Control: no-store。

为了可缓存，以下所有条件都必须成立

• 操作有一个非零的 maxAge。
• 操作有一个单一响应而不是增量交付响应。
• 响应中没有错误。

如果您在 CDN 或其他缓存代理后面运行 Apollo Server，您可以配置它使用此头部的值来适当地缓存响应。有关详细信息，请参阅您的 CDN 文档（例如，这里是 Amazon CloudFront 的文档）。

某些 CDN 需要自定义头部来缓存或设置cache-control头部的自定义值，如s-maxage。您可以相应地配置您的ApolloServer实例，通过告诉内置的缓存控制插件仅计算策略而不设置 HTTP 头部，并指定您的自定义插件。

1
new ApolloServer({
2
  plugins: [
3
    ApolloServerPluginCacheControl({ calculateHttpHeaders: false }),
4
    {
5
      async requestDidStart() {
6
        return {
7
          async willSendResponse(requestContext) {
8
            const { response, overallCachePolicy } = requestContext;
9
            const policyIfCacheable = overallCachePolicy.policyIfCacheable();
10
            if (policyIfCacheable && !response.headers && response.http) {
11
              response.http.headers.set(
12
                'cache-control',
13
                // ... or the values your CDN recommends
14
                `max-age=0, s-maxage=${
15
                  overallCachePolicy.maxAge
16
                }, ${policyIfCacheable.scope.toLowerCase()}`,
17
              );
18
            }
19
          },
20
        };
21
      },
22
    },
23
  ],
24
});

使用 GET 请求

因为 CDN 和缓存代理只缓存 GET 请求（不缓存 POST 请求，默认情况下Apollo Client为所有操作发送），我们建议在 Apollo Client 中启用自动持久化查询以及useGETForHashedQueries 选项。

或者，您可以在您的HttpLink实例中设置ApolloClient的useGETForQueries选项。然而，大多数浏览器对 GET 请求强制实施大小限制，并且较大的查询字符串可能会超过此限制。

禁用缓存控制

您可以通过自己安装Apollo Server Plugin Cache Control 插件来阻止Cache-Control头部的设置，并将calculateHttpHeaders设置为 false：

1
import { ApolloServerPluginCacheControl } from '@apollo/server/plugin/cacheControl';
2

3
const server = new ApolloServer({
4
  // ...other options...
5
  plugins: [ApolloServerPluginCacheControl({ calculateHttpHeaders: false })],
6
});

如果您这样做，缓存控制插件仍然为每个操作响应计算缓存行为。然后您可以使用这些信息与其它插件（如响应缓存插件）一起使用。

如果要完全禁用缓存控制计算，则安装ApolloServerPluginCacheControlDisabled插件（此插件除了防止安装缓存控制插件外没有其他作用）：

1
import { ApolloServerPluginCacheControlDisabled } from '@apollo/server/plugin/disabled';
2

3
const server = new ApolloServer({
4
  // ...other options...
5
  plugins: [ApolloServerPluginCacheControlDisabled()],
6
});

使用 responseCachePlugin 缓存（高级）

您可以在Redis、Memcached或Apollo Server的默认内存缓存等存储中缓存Apollo Server查询响应。更多信息，请参阅配置缓存后端。

内存缓存设置

要设置您的内存响应缓存，首先导入responseCachePlugin并将其提供给ApolloServer构造函数：

1
import responseCachePlugin from '@apollo/server-plugin-response-cache';
2

3
const server = new ApolloServer({
4
  // ...other options...
5
  plugins: [responseCachePlugin()],
6
});

在初始化时，此插件会根据字段设置自动开始缓存响应。

该插件使用与Apollo Server其他功能相同的内存LRU缓存。对于具有多个服务器实例的环境，您可能希望使用共享缓存后端，如Memcached或Redis。

Memcached/Redis设置

请参阅配置外部缓存。

为PRIVATE响应识别用户

如果缓存响应具有PRIVATE作用域，则其值仅可供单个用户访问。为了强制执行此限制，缓存需要知道如何识别该用户。

要启用此识别，您需要向responseCachePlugin提供sessionId函数，例如：

1
import responseCachePlugin from '@apollo/server-plugin-response-cache';
2
const server = new ApolloServer({
3
  // ...other settings...
4
  plugins: [
5
    responseCachePlugin({
6
      sessionId: (requestContext) =>
7
        requestContext.request.http.headers.get('session-id') || null,
8
    }),
9
  ],
10
});

缓存使用此函数的返回值来识别之后可以访问缓存PRIVATE响应的用户。在上面的示例中，函数使用原始操作请求中的session-id头。

如果客户端稍后执行了完全相同的查询并且具有相同的标识符，Apollo Server会在响应值仍然可用的情况下返回PRIVATE缓存的响应。