AWS Chalice 快速上手:从零创建并部署你的第一个 Serverless REST API

原创2026-09-22 09:42:072,218 阅读
文章标签:云原生ServerlessWeb框架后端CLI任务调度

AWS Chalice 快速上手:从零创建并部署你的第一个 Serverless REST API

本文是一份以官方 Quickstart 为主线、结合源码验证的实战指南。你将通过 chalice 命令行工具完成环境搭建、项目创建、首次部署与资源清理的完整闭环,学会用几行 Python 代码写出一个基于 AWS Lambda 与 API Gateway 的 REST API,并理解 new-project、deploy、delete 三个核心命令在仓库内部到底做了什么。

什么是 Chalice

Chalice 是一个用 Python 编写 Serverless 应用的框架,它允许你快速创建并部署使用 AWS Lambda 的应用。根据 README.rst 的描述,它主要提供三方面能力:

  • 一个命令行工具:用于创建、部署和管理你的应用;
  • 基于装饰器的 API:用于对接 Amazon API Gateway、Amazon S3、Amazon SNS、Amazon SQS 以及其他 AWS 服务;
  • 自动 IAM 策略生成:根据你的代码自动生成最小权限的 IAM 策略,无需手工配置权限。

你可以用装饰器快速构建多种形态的 Serverless 应用:

from chalice import Chalice

app = Chalice(app_name="helloworld")

@app.route("/")
def index():
    return {"hello": "world"}

这段代码就定义了一个最简单的 REST API。除此之外,Chalice 还支持定时任务、S3 事件、SQS 队列等多种事件源(详见 README.rst 中的示例)。而下面这条命令,就可以把写好的代码直接部署到云端:

$ chalice deploy
...
https://endpoint/api

$ curl https://endpoint/api
{"hello": "world"}

接下来,我们就按 Quickstart 的完整流程走一遍:安装、配置凭证、创建项目、部署、验证、清理。

环境准备:安装 Chalice

Quickstart 使用 Python 3.10 作为演示环境,并明确指出:AWS Chalice 支持 AWS Lambda 所支持的全部 Python 版本,包括 Python 3.10 到 Python 3.14(见 docs/source/quickstart.rst)。

首先创建并激活一个虚拟环境,避免污染系统 Python:

$ python3 --version
Python 3.10.20
$ python3 -m venv .venv
$ . .venv/bin/activate

然后通过 pip 安装 Chalice:

$ python3 -m pip install chalice

安装完成后,用 --help 验证命令行工具是否可用:

$ chalice --help
Usage: chalice [OPTIONS] COMMAND [ARGS]...
...

从源码看,CLI 基于 click 构建(见 chalice/cli/init.py),顶层 cli 组还提供两个全局选项:

  • --project-dir:指定项目目录(绝对或相对路径),默认为当前工作目录;
  • --debug/--no-debug:是否向 stderr 输出调试日志,默认关闭。

另外,CLI 在每次运行时都会设置环境变量 AWS_CHALICE_CLI_MODE=true(见 chalice/cli/init.py),你可以在 app.py 中借此判断当前是否运行在 Chalice CLI 环境下。

配置 AWS 凭证

部署应用之前,需要确保机器上已配置好 AWS 凭证。如果你之前已经配置过 boto3(AWS Python SDK)或 AWS CLI 的凭证,可以直接跳过本节。

首次配置凭证,可以手动创建 ~/.aws/config 文件:

$ mkdir ~/.aws
$ cat >> ~/.aws/config
[default]
aws_access_key_id=YOUR_ACCESS_KEY_HERE
aws_secret_access_key=YOUR_SECRET_ACCESS_KEY
region=YOUR_REGION (such as us-west-2, us-west-1, etc)

需要注意,官方文档建议前往 boto3 的配置文档了解所有受支持的凭证配置方式。在 Chalice 的 CLI 中,deploy、delete 等命令还支持通过 --profile 参数覆盖部署时使用的 AWS Profile(见 chalice/cli/init.py)。

创建你的第一个项目

使用 new-project 命令创建项目骨架:

$ chalice new-project helloworld

命令执行后会在当前目录生成一个 helloworld 目录:

$ cd helloworld
$ ls -la
drwxr-xr-x   .chalice
-rw-r--r--   app.py
-rw-r--r--   requirements.txt

其中 .chalice 目录用于存放部署元数据,现阶段可以忽略;核心文件是 app.py 与 requirements.txt。

看一下生成的 app.py:

from chalice import Chalice

app = Chalice(app_name='helloworld')


@app.route('/')
def index():
    return {'hello': 'world'}

这段代码定义了一个视图函数 index(),当收到对路径 / 的 HTTP GET 请求时,返回 JSON 响应 {"hello": "world"}。

关于这个命令的源码实现,有两点值得展开:

1. 模板从哪里来? 项目模板存放在仓库的 chalice/templates/ 目录下,目录名遵循 0123-template-name 结构,前面的四位数字只用于排序展示,模板名(- 之后的部分)才是 --project-type 参数的真实取值。每个模板目录下的 metadata.json 记录模板描述(例如 REST API 模板的描述为 {"description": "REST API"},见 chalice/templates/0000-rest-api/metadata.json)。上述逻辑位于 chalice/cli/newproj.py。

2. 模板变量如何填充? 模板中支持 {{template_var}} 形式的占位符,目前支持 app_name(项目名)与 chalice_version(生成项目的 Chalice 版本号)两个变量(见 chalice/cli/newproj.py 与 chalice/cli/newproj.py)。生成项目时,ProjectCreator 会递归遍历模板目录,用 get_templated_content() 通过正则替换填充占位符,并跳过 metadata.json 与 *.pyc 等文件(见 chalice/cli/newproj.py)。比如你看到的 app = Chalice(app_name='helloworld'),其实就是模板文件 chalice/templates/0000-rest-api/app.py 中的 {{app_name}} 被替换后的结果。

值得一提的是,new-project 命令还有更多玩法:不带项目名直接运行 chalice new-project 会进入交互式向导(显示欢迎横幅并询问项目名与项目类型);-t/--project-type 参数可以指定项目类型,默认值为 legacy(见 chalice/cli/init.py)。仓库当前自带的模板包括 0000-rest-api(REST API)、0002-s3-event-handler(S3 事件处理)、0007-lambda-only(纯 Lambda)、0009-legacy(兼容旧版)以及 6001-cdk-ddb(CDK + DynamoDB)等。

另外,从 chalice/constants.py 可以看到,new-project 还会在配置中写入 CONFIG_VERSION = '2.0',用于在将来行为变更时给出升级提醒。

部署到 AWS

进入 helloworld 目录,执行部署命令:

$ chalice deploy
Creating deployment package.
Creating IAM role: helloworld-dev
Creating lambda function: helloworld-dev
Creating Rest API
Resources deployed:
  - Lambda ARN: arn:aws:lambda:us-west-2:123456789012:function:helloworld-dev
  - Rest API URL: https://abcd.execute-api.us-west-2.amazonaws.com/api/

部署完成后,你就拥有一个基于 API Gateway 与 Lambda 的线上 API 了,直接通过 curl 验证:

$ curl https://abcd.execute-api.us-west-2.amazonaws.com/api/
{"hello": "world"}

试着修改 index() 函数返回的字典内容,然后再次运行 chalice deploy,即可把改动重新部署上去。

结合源码,chalice deploy 背后做的事情值得理解:

  • 部署管线:命令首先通过 CLIFactory 创建配置对象(create_config_obj),随后创建 botocore 会话与默认部署器(create_default_deployer),调用 d.deploy(config, chalice_stage_name=stage) 完成部署,最后由部署报告器输出资源清单(见 chalice/cli/init.py)。部署相关的核心实现分布在 chalice/deploy/ 目录,例如 deployer.py、planner.py、appgraph.py、packager.py 等。
  • 阶段(Stage)机制:默认阶段名为 dev(DEFAULT_STAGE_NAME = 'dev',见 chalice/constants.py)。从 CLI 选项的说明可以看出,指定一个新的 Chalice 阶段会创建一套全新的 AWS 资源(见 chalice/cli/init.py),这也是输出中看到 helloworld-dev 这样的资源命名的原因。
  • IAM 自动生成:默认开启自动策略生成(--autogen-policy 选项),部署器会根据代码静态分析生成最小权限 IAM 策略,这也是 Chalice 的核心卖点之一。
  • 其他可选参数:--profile 覆盖部署时的 AWS Profile;--api-gateway-stage 指定 API Gateway 的阶段名;--connection-timeout 覆盖 botocore 的默认连接超时(单位秒,见 chalice/cli/init.py)。

如果部署后忘了 API 地址,可以使用 chalice url 命令直接打印 REST API 的 URL;而 chalice dev plan 可以在不实际执行部署的情况下生成并展示完整的部署计划,方便理解部署过程(见 chalice/cli/init.py)。

本地调试:chalice local

在真正部署之前,你还可以用本地开发服务器先行验证代码。chalice local 命令会在本机启动一个模拟服务:

$ chalice local

默认监听 127.0.0.1:8000,支持 --host、--port、--stage 等参数,并默认开启 --autoreload(代码变更时自动重启服务,见 chalice/cli/init.py)。本地服务器启动前会调用 validate_routes() 校验路由配置,确保能通过本地验证的路由同样可以成功部署(见 chalice/cli/init.py)。本地实现的细节位于 chalice/local.py。

清理资源:chalice delete

如果只是实验完毕、不再需要这些资源,可以执行 chalice delete 命令,Chalice 会删除 chalice deploy 创建的全部资源:

$ chalice delete
Deleting Rest API: abcd4kwyl4
Deleting function arn:aws:lambda:region:123456789012:function:helloworld-dev
Deleting IAM Role helloworld-dev

从输出可以看到,delete 会按顺序清理 REST API(API Gateway)、Lambda 函数与 IAM 角色。从源码看,delete 命令会创建一个"删除型"部署器(create_deletion_deployer)来执行清理流程(见 chalice/cli/init.py)。delete 同样支持 --profile 与 --stage 参数,--stage 用于指定要删除的阶段,默认删除 dev 阶段的资源。

下一步学习路径

到这里,你已经用 Chalice 完成了第一个 Serverless 应用的创建、部署、验证与清理。接下来可以沿着以下方向继续深入(对应仓库 docs/source/ 目录下的文档):

  • 创建更复杂的 REST API:阅读 docs/source/tutorials/basicrestapi.rst,深入探索 URL 参数、错误消息、内容类型、CORS 等能力;
  • 接入更多事件源:阅读 docs/source/tutorials/events.rst,学习如何在 REST API 之外,把 Lambda 连接到 S3、SNS、SQS、定时任务等其他事件源;
  • 构建 WebSocket 应用:阅读 docs/source/tutorials/wschat.rst,学习如何创建 WebSocket API 并实现一个示例聊天应用;
  • 查阅主题指南:docs/source/topics/index.rst 提供比教程更深入的参考式文档,涵盖配置、打包、授权器、中间件、蓝本等具体特性;
  • 查阅 API 参考:当你已经确定要使用某个特性、但需要查询具体参数名或返回值时,docs/source/api.rst 是最佳去处。

此外,本仓库的测试代码也可以作为学习范例:例如 tests/unit/test_app.py 覆盖了 Chalice 应用对象的单元行为,tests/unit/cli/test_cli.py 覆盖了 CLI 命令的解析与执行流程,而 tests/functional/cli/test_cli.py 则对 new-project 生成的项目结构等进行了功能级验证,阅读这些测试能帮你更准确地理解各命令的预期行为。

登录后查看全文
chalice