AWS SAM部署Lambda处理multipart/form-data二进制文件返回502问题求助

问题根因 #

你遇到的502错误核心是二进制文件上传时，API Gateway（含SAM本地模拟环境）会自动将BinaryMediaTypes列表内的请求体编码为Base64字符串，同时设置请求参数isBase64Encoded=true，文本类请求不会触发该编码逻辑。你之前的代码未处理Base64解码，直接解析编码后的请求体导致程序报错，API Gateway无法识别异常返回结构就会抛出502错误。 #

可行修复步骤 #

1. 修改Lambda处理逻辑，新增Base64解码判断 #

你使用Java11 runtime，直接读取APIGatewayProxyRequestEvent的isBase64Encoded字段判断是否需要解码，示例代码如下：

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent;
import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyResponseEvent;
import java.util.Base64;
import java.io.ByteArrayInputStream;

public class PostRequest {
    public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent request, Context context) {
        byte[] requestBodyBytes;
        // 核心解码逻辑
        if (Boolean.TRUE.equals(request.getIsBase64Encoded())) {
            requestBodyBytes = Base64.getDecoder().decode(request.getBody());
        } else {
            requestBodyBytes = request.getBody().getBytes();
        }
        // 后续用requestBodyBytes解析multipart/form-data即可，比如配合Apache Commons FileUpload工具
        // 示例：new ServletFileUpload().getItemIterator(new InputStreamContext(new ByteArrayInputStream(requestBodyBytes), request.getHeaders().get("Content-Type")))
        
        // 业务逻辑处理完成后返回响应
        return new APIGatewayProxyResponseEvent().withStatusCode(200).withBody("success");
    }
}

同时请确认你的Lambda Java依赖版本足够新，避免isBase64Encoded字段无法正确读取，Maven依赖参考：

<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-lambda-java-events</artifactId>
    <version>3.11.1</version>
</dependency>
<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-lambda-java-core</artifactId>
    <version>1.2.21</version>
</dependency>

2. 修正BinaryMediaTypes配置 #

你之前仅在函数的Api事件下配置BinaryMediaTypes不生效，AWS SAM要求该配置必须放在全局Api配置或者显式声明的Api资源下，两种正确配置方式如下：

方式一：全局Api配置（无需修改现有事件绑定）

Globals:
  Api:
    BinaryMediaTypes:
      - "multipart/form-data"
      - "application/pdf"
      - "image/*" # 可通过通配符匹配所有图片类型，无需逐个声明

Resources:
  PostRequest:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: .
      Handler: com.demo.handlers.request.PostRequest
      Runtime: java11
      Description: Post a Request
      MemorySize: 512
      Timeout: 100
      Events:
        HttpPost:
          Type: Api
          Properties:
            Path: /requests
            Method: post

方式二：显式声明Api资源（适合需要自定义Api其他配置的场景）

Resources:
  # 先显式定义Api资源，统一配置二进制类型
  CustomApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      BinaryMediaTypes:
        - "multipart/form-data"
        - "application/pdf"
        - "image/*"

  PostRequest:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: .
      Handler: com.demo.handlers.request.PostRequest
      Runtime: java11
      Description: Post a Request
      MemorySize: 512
      Timeout: 100
      Events:
        HttpPost:
          Type: Api
          Properties:
            RestApiId: !Ref CustomApi # 绑定到自定义Api资源
            Path: /requests
            Method: post

3. 本地测试特殊配置 #

旧版本SAM CLI本地启动服务时不会自动加载template中的BinaryMediaTypes配置，启动命令需添加参数显式指定：

sam local start-api --binary-media-types "multipart/form-data,application/pdf,image/png,image/jpeg"

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