Amazon API Gateway：创建与管理 API

FreeGuideOnline 最新 2026-06-30

什么是 Amazon API Gateway？

Amazon API Gateway 是 AWS 提供的一项完全托管的服务，让开发人员能够轻松创建、发布、维护、监控和保护任意规模的 REST、HTTP 和 WebSocket API。它充当“前门”，负责处理传入请求的接受、流量管理、授权与访问控制、监控以及 API 版本管理等任务，使您无需自行搭建和管理 API 基础设施。

无论您是要为移动应用、Web 应用还是微服务构建后端，API Gateway 都能帮您将后端业务逻辑与客户端解耦。它能够无缝集成 AWS Lambda、Amazon EC2、Amazon ECS 以及任何可通过 HTTP 访问的后端服务。

核心概念速览

在动手创建 API 之前，先了解几个关键术语：

  • API 类型：REST API、HTTP API、WebSocket API。本教程聚焦 REST API。
  • 资源（Resource）：API 的 URL 路径组成部分，例如 /users、/orders/{orderId}。
  • 方法（Method）：资源支持的 HTTP 动词，如 GET、POST、PUT、DELETE 等。
  • 集成（Integration）：将 API 方法映射到后端具体服务（Lambda 函数、HTTP 端点等）的配置。
  • 阶段（Stage）：表示 API 的一个部署快照，通常对应环境（dev、staging、prod）。
  • 部署（Deployment）：将 API 的当前配置（资源、方法、集成等）发布到某个阶段的动作。

第一步：创建 REST API

1.1 进入 API Gateway 控制台

登录 AWS 管理控制台，在服务列表中找到 API Gateway，点击进入。

1.2 选择 API 类型

点击 创建 API 按钮。为了完整控制与功能，我们选择 REST API（非私有）。根据提示选择：

  • 新建 API：从头构建。
  • 输入 API 名称，例如 UserManagementAPI。
  • 端点类型可选择 区域（Regional）（推荐，低延迟）或边缘优化等。
  • 点击 创建 API。

第二步：定义资源和路径

API 的 URL 结构通过“资源”来定义。

2.1 创建根路径下的资源

  1. 在左侧导航栏选择您刚创建的 API。
  2. 点击 资源 选项卡，确保根路径 / 被选中。
  3. 点击 创建资源。
  4. 输入资源名称，例如 users，资源路径会自动填充为 /users。
  5. （可选）启用 CORS（跨域资源共享），若前端与 API 不同域则必须开启。
  6. 点击 创建资源。

2.2 创建带路径参数的资源

对于需要根据 ID 获取单个用户的场景：

  1. 选中 /users 资源，再次点击 创建资源。
  2. 资源名称写 user，路径部分输入 {userId}（花括号表示路径参数）。
  3. 最终该资源路径为 /users/{userId}，URI 中的 userId 将作为输入传递给后端。

第三步：创建方法与集成

为资源添加 HTTP 方法，并指定后端如何响应。

3.1 在 /users 资源下创建 GET 方法（列出用户）

  1. 选中 /users 资源，点击 创建方法。
  2. 从下拉菜单选择 GET，确认。
  3. 进入“集成请求”配置页面：
    • 集成类型：选择 Lambda 函数（最常用）。
    • 勾选 使用 Lambda 代理集成（简化请求/响应映射）。
    • 选择区域，输入 Lambda 函数名称（如 listUsersFunction）。
    • 点击 保存，授予 API Gateway 调用 Lambda 的权限，确认。

3.2 创建 POST 方法（创建用户）

同样在 /users 资源下，创建 POST 方法，将其与 createUserFunction Lambda 函数集成。注意：不要忘记后续处理跨域预检请求——可通过创建 OPTIONS 方法并设置为模拟响应（MOCK）来完成。

3.3 创建带路径参数的 GET 方法

选中 /users/{userId} 资源，创建 GET 方法，集成到 getUserFunction Lambda。API Gateway 会自动将路径参数 userId 放入传递给 Lambda 的事件对象中。

第四步：配置请求与响应

即使使用 Lambda 代理集成，您也可以做适当的设置，使 API 更健壮。

4.1 请求验证（可选）

在方法的 方法请求 页面中，可以配置：

  • URL 查询字符串参数：如 ?status=active，可以标记为必填。
  • 请求头：定义必须提供的头信息。
  • 请求体验证模型：为 JSON 请求体创建模型（使用 JSON Schema），API Gateway 能自动校验请求负载格式。

4.2 方法响应与状态码

在 方法响应 中可以添加 HTTP 状态码定义（200、400、500 等），便于与集成响应映射配合。但若使用 Lambda 代理集成，Lambda 返回的响应格式必须符合 API Gateway 要求（包含 statusCode、headers、body 字段），因此通常无需额外映射。

第五步：部署 API 到阶段

配置完成后，必须将 API 部署到某个阶段才能对外访问。

5.1 创建部署

  1. 在 API 主页面，点击 操作 下拉菜单，选择 部署 API。
  2. 若无现有阶段，选择 新建阶段，阶段名称如 dev，可添加部署描述。
  3. 点击 部署。

5.2 获取调用 URL

部署成功后，您会看到 调用 URL，类似：
https://a1b2c3d4.execute-api.us-east-1.amazonaws.com/dev

  • 资源的完整访问路径为：调用 URL + 资源路径，例如 .../dev/users。
  • 此 URL 即可用于测试或集成到前端应用。

第六步：测试与监控

6.1 在控制台内测试

在每个方法下，都有 测试 功能。您可以模拟发送请求，填写查询参数、请求头、请求体，查看后端响应与日志。这非常适合调试 Lambda 函数。

6.2 启用 CloudWatch 日志

为了更好地监控与排查错误，建议为 API 启用日志：

  1. 在阶段设置（如 dev）页面，点击 日志/跟踪 选项卡。
  2. 勾选 启用 CloudWatch Logs，设置日志级别为 INFO 或 ERROR。
  3. 选择是否记录完整的请求/响应数据（注意敏感信息）。
  4. 保存更改。

之后，API 的所有请求日志会发送至 CloudWatch，可搭配指标创建告警。

第七步：管理 API 安全性与访问控制

API Gateway 提供多种安全方案，确保只有授权客户端能够使用 API。

7.1 API 密钥与使用计划

若需对外部开发者开放 API（例如 SaaS 场景）并限制调用速率：

  1. 创建 API 密钥，分发给每个客户。
  2. 创建 使用计划，设置节流（速率/突发）和配额（每周期请求数）。
  3. 将 API 密钥与使用计划关联。
  4. 在需要密钥的方法上，将 API 密钥必填 设为 true。

7.2 AWS IAM 授权

适用于 AWS 内部服务调用：在方法请求中，将授权方式设为 AWS_IAM，客户端需要使用 AWS Signature V4 签署请求。

7.3 Cognito 用户池授权

面向终端用户登录场景：启用 Cognito 用户池 作为授权方，API Gateway 会自动验证令牌。非常适合移动或 Web 应用的用户认证。

7.4 Lambda 自定义授权方

适用于高度定制的逻辑（如承载第三方 JWT 令牌）：编写 Lambda 函数作为“授权方”，返回有效的 IAM 策略来决定是否允许请求。

第八步：进阶管理技巧

8.1 自定义域名

将默认的 execute-api 域名替换为您自己的域名（如 api.example.com）：

  1. 在 API Gateway 控制台选择 自定义域名，点击创建。
  2. 输入域名，选择证书（需要 AWS Certificate Manager 中预置）。
  3. 关联到相应的 API 和阶段。
  4. 在 DNS 服务商处创建 CNAME 记录指向 API Gateway 提供的目标域名。

8.2 API 版本与金丝雀发布

利用阶段变量与多阶段实现蓝绿/金丝雀部署。例如，为 prod 阶段配置两个部署，通过调整流量权重将小部分流量路由到新版本 Lambda 别名，逐步验证后全量切换。

8.3 跨账户资源共享（CORS）配置细节

当客户端与 API 不同域时，必须正确设置 CORS 头。最简单的做法：为资源创建 OPTIONS 方法，集成类型设为 模拟（MOCK），并在集成响应和网关响应中添加所需的 CORS 头（Access-Control-Allow-Origin 等）。API Gateway 也提供快速的“启用 CORS”操作，可自动完成以上配置。

常见问题与排错

问题现象 可能原因 解决思路
{ "message": "Missing Authentication Token" } 路径错误或调用 URL 不完整（遗漏阶段或资源） 检查完整 URL 是否与 API 资源路径匹配
403 Forbidden 认证/授权问题（API 密钥不匹配、IAM 策略不足等） 验证法方请求中认证信息，检查使用计划与密钥
500 Internal Server Error 后端 Lambda 超时或日志报错 增加 Lambda 超时时间，查看 CloudWatch 后端日志
CORS 错误（浏览器控制台） OPTIONS 预检未正确响应 CORS 头 检查资源是否已有 OPTIONS 方法并返回需要的头信息
延迟较高或冷启动 Lambda 冷启动或 API Gateway 地区过远 配置预置并发或选择就近区域

总结

Amazon API Gateway 将复杂的 API 管理抽象为简单的资源配置流程。通过本教程，您已经学会了如何：

  • 从零创建 REST API
  • 构建带路径参数的资源结构
  • 将方法集成到 Lambda 等后端
  • 部署 API 到阶段并获取可调用 URL
  • 配置认证、监控与自定义域名

接下来，您可以深入探索 HTTP API（更低延迟、更低成本）或 WebSocket API 以满足实时通信需求，并将 API Gateway 与 AWS 服务生态无缝结合，构建健壮的微服务架构。