如何在AWS API Gateway以请求体为缓存键？GraphQL Lambda场景指南

1. 配置API Gateway计算请求体哈希并传递自定义头 #

API Gateway通过**Velocity模板语言（VTL）**的映射模板实现请求体哈希计算，同时保证原始请求体完整传递给Lambda，具体步骤如下：

配置流程 #

• 进入API Gateway控制台，定位到你的GraphQL API的POST方法
• 切换至集成请求标签，找到映射模板区域
• 选择application/json作为内容类型，启用映射模板
• 替换默认模板为以下VTL代码：该代码会计算请求体的SHA-256哈希，添加为X-Request-Body-Hash自定义头，同时原样返回原始请求体给Lambda

## 引入哈希工具类
#set($hashTool = $util.crypto)
## 读取原始请求体内容
#set($requestBody = $input.body)
## 计算SHA-256哈希并转为十六进制字符串
#set($bodyHash = $hashTool.sha256Hex($requestBody))
## 向请求中添加自定义哈希头
$util.http.addHeader("X-Request-Body-Hash", $bodyHash)
## 输出原始请求体，确保Lambda能拿到完整数据
$input.json('$')

• 保存配置后，API Gateway转发请求时会自动携带该哈希头，Lambda仍可正常接收原始请求体。

2. POST方法启用缓存的可行性 #

完全可以为POST方法启用缓存，但需调整API Gateway的缓存规则：

配置要点 #

• 进入API Gateway的缓存标签，开启API级别的缓存功能
• 回到POST方法的方法请求标签，在缓存键参数中添加X-Request-Body-Hash（POST请求默认不使用请求体作为缓存键，必须通过自定义头关联唯一请求体）
• 在方法的集成请求标签中勾选“启用缓存”，并设置合理的缓存TTL（例如300秒，根据业务需求调整）

配置完成后，API Gateway会依据X-Request-Body-Hash的值缓存响应，相同请求体的POST请求将直接返回缓存结果，无需调用Lambda。

3. GraphQL/Lambda场景下的潜在问题与注意事项 #

核心风险与优化建议 #

• 请求体大小限制：API Gateway的VTL模板最多支持处理10MB以内的请求体，若GraphQL请求体超过此阈值，哈希计算会失败，需提前在API Gateway配置请求体大小校验。
• GraphQL操作类型区分：Mutation操作绝对不能缓存，需在映射模板中判断请求体的operationName或查询内容，仅为Query类型请求添加哈希头并启用缓存，修改后的VTL示例：

  #set($requestBodyObj = $input.path('$'))
  #if($requestBodyObj.operationName != null && $requestBodyObj.operationName.startsWith("Mutation"))
      ## Mutation操作不添加哈希头，跳过缓存
      $input.json('$')
  #else
      ## Query操作计算哈希并添加头
      #set($hashTool = $util.crypto)
      #set($requestBody = $input.body)
      #set($bodyHash = $hashTool.sha256Hex($requestBody))
      $util.http.addHeader("X-Request-Body-Hash", $bodyHash)
      $input.json('$')
  #end
  

• 哈希冲突风险：SHA-256哈希的冲突概率极低，但极端场景下仍可能存在，若业务对缓存一致性要求极高，可结合请求路径、用户身份标识等信息共同生成哈希键。
• 原始请求体验证：部署后需在Lambda中打印event.headers['X-Request-Body-Hash']和event.body，确认原始请求体未被修改、哈希头已正确传递。
• 缓存失效策略：若GraphQL查询的数据源更新，需调用API Gateway的InvalidateCache API手动清除相关缓存，或设置合理的TTL让缓存自动失效。
• 敏感数据防护：若请求体包含敏感信息（如用户令牌），哈希头本身不会泄露数据，但需确保缓存的响应内容无敏感信息，或启用API Gateway缓存的用户身份校验机制。

CloudFormation配置示例（基础设施即代码实现） #

以下是用CloudFormation配置该方案的关键片段：

Resources:
  GraphQLApi:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: GraphQLApiWithRequestBodyCache

  GraphQLResource:
    Type: AWS::ApiGateway::Resource
    Properties:
      ParentId: !GetAtt GraphQLApi.RootResourceId
      PathPart: graphql
      RestApiId: !Ref GraphQLApi

  GraphQLLambda:
    Type: AWS::Lambda::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs18.x
      Code:
        ZipFile: |
          exports.handler = async (event) => {
            console.log("Received request body:", event.body);
            console.log("Request body hash:", event.headers['X-Request-Body-Hash']);
            return {
              statusCode: 200,
              body: JSON.stringify({ data: "GraphQL response" })
            };
          };
      Role: !GetAtt LambdaExecutionRole.Arn

  GraphQLPostMethod:
    Type: AWS::ApiGateway::Method
    Properties:
      RestApiId: !Ref GraphQLApi
      ResourceId: !Ref GraphQLResource
      HttpMethod: POST
      AuthorizationType: NONE
      Integration:
        Type: AWS_PROXY
        IntegrationHttpMethod: POST
        Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${GraphQLLambda.Arn}/invocations
        RequestTemplates:
          application/json: |
            #set($hashTool = $util.crypto)
            #set($requestBody = $input.body)
            #set($bodyHash = $hashTool.sha256Hex($requestBody))
            $util.http.addHeader("X-Request-Body-Hash", $bodyHash)
            $input.json('$')
        CacheNamespace: !Ref GraphQLApi
        CacheKeyParameters:
          - method.request.header.X-Request-Body-Hash
      MethodResponses:
        - StatusCode: 200
      CacheEnabled: true
      CacheTtlInSeconds: 300

  LambdaExecutionRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: lambda.amazonaws.com
            Action: sts:AssumeRole
      Policies:
        - PolicyName: LambdaBasicExecution
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  - logs:CreateLogGroup
                  - logs:CreateLogStream
                  - logs:PutLogEvents
                Resource: arn:aws:logs:*:*:*

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