AWS Lambda 代理集成（Proxy Integration）详解

AWS Lambda 代理集成详解与实践

ima0019

于 2025-04-23 16:20:40 发布

阅读量77

点赞数

CC 4.0 BY-SA版权

分类专栏： AWS Lambda 文章标签： aws 云计算 lambda apigateway

原文链接：https://blog.3g7.cn/archives/aws-lambda-proxyintegration

AWS Lambda 专栏收录该内容

1 篇文章

订阅专栏

在 AWS Lambda 和 API Gateway 的组合中，代理集成（Proxy Integration） 是一个强大但容易让人困惑的功能。许多开发者第一次尝试时都会遇到类似的问题：

“为什么我的 Lambda 返回 'success' 不起作用，但返回 { statusCode: 200, body: '...' } 却可以？”

本文将深入探讨 AWS Lambda 代理集成 的工作原理、常见问题及最佳实践，帮助你彻底掌握它的行为模式。

1. 什么是 Lambda 代理集成？

AWS API Gateway 提供了两种与 Lambda 集成的方式：

代理集成（Proxy Integration）
- Lambda 必须返回特定格式（statusCode, body, headers 等）。
- API Gateway 不会修改请求/响应，直接透传。
- 适用于 REST API、HTTP API 等需要精细控制响应的场景。
非代理集成（传统集成）
- Lambda 可以返回任意格式（如 "success" 或 { data: "..." }）。
- API Gateway 会自动转换响应（需配置映射模板）。
- 适用于简单的后端逻辑，如返回静态 JSON。

默认情况下，如果你在 API Gateway 的 URL 路径中使用 {proxy+} 或手动启用了代理集成，API Gateway 就会要求 Lambda 返回特定的响应格式。

2. 代理集成的工作原理

（1）Lambda 必须返回什么？

启用代理集成后，Lambda 必须返回如下结构：

{
  "statusCode": 200,             // HTTP 状态码（必需）
  "body": "Hello, World!",       // 响应体（必须是字符串，JSON 需 `JSON.stringify`）
  "headers": {                   // 可选 HTTP 头
    "Content-Type": "text/plain"
  },
  "isBase64Encoded": false       // 可选，是否返回二进制数据
}

✅ 正确示例：

exports.handler = async (event) => {
  return {
    statusCode: 200,
    body: JSON.stringify({ message: "Success!" }),
    headers: { "Content-Type": "application/json" }
  };
};

❌ 错误示例（会导致 500 Internal Server Error）：

exports.handler = async (event) => {
  return "success"; // ❌ 代理集成不接受纯字符串
  return { data: "..." }; // ❌ 必须包含 statusCode 和 body
};

（2）API Gateway 如何处理响应？

代理集成：API Gateway 不会修改 Lambda 的响应，直接返回给客户端。
非代理集成：API Gateway 会尝试转换 Lambda 的返回值（需配置映射模板）。

3. 为什么 `return "success"` 不起作用？

根本原因：API Gateway 代理集成要求 Lambda 返回一个符合 HTTP 响应结构的对象，而直接返回字符串或对象会导致 API Gateway 无法正确解析，最终返回 500 Internal Server Error。

错误示例：

exports.handler = async (event) => {
  return "success"; // ❌ 代理集成不接受
};

API Gateway 实际收到的响应：

{
  "error": "Malformed Lambda response",
  "message": "Lambda returned a non-proxy response"
}

4. 解决方案：如何正确使用代理集成？

方案 1：保持代理集成，返回标准格式（推荐）

exports.handler = async (event) => {
  return {
    statusCode: 200,
    body: "success", // 必须是字符串
    headers: { "Content-Type": "text/plain" }
  };
};

适用场景：

需要精确控制 HTTP 状态码、头信息。
适用于 REST API、动态响应。

方案 2：关闭代理集成，使用传统集成

在 API Gateway 中：
- 去掉 {proxy+} 路径。
- 在集成请求中禁用 Use Lambda Proxy Integration。
配置响应映射模板（如 application/json）：
```
{
  "message": "$input.path('$')"
}
```

Lambda 可以自由返回：

exports.handler = async (event) => {
  return "success"; // ✅ 现在可以了
};

适用场景：

简单的后端逻辑，如返回静态 JSON。
不想在 Lambda 中处理 HTTP 细节。

5. 最佳实践

场景	推荐方式
REST API（需要精细控制响应）	✅ 代理集成
返回简单字符串/JSON	⚠️ 非代理集成 + 映射模板
使用 Express.js/Fastify 等框架	✅ `serverless-express` + 代理集成
返回二进制数据（如图片）	✅ 代理集成 + `isBase64Encoded: true`