AWS Chalice 快速上手:用 Python 装饰器构建并部署 Serverless 应用

原创2026-09-22 15:54:471,963 阅读
文章标签:云原生ServerlessWeb框架后端CLI任务调度

AWS Chalice 快速上手:用 Python 装饰器构建并部署 Serverless 应用

导读:AWS Chalice 是一个面向 Python 的 Serverless 微框架,让你用极简的装饰器 API 编写运行在 AWS Lambda 上的应用,并通过一条 chalice deploy 命令完成从代码打包、IAM 角色创建到 API Gateway / S3 / SNS / SQS 等资源接入的全流程部署。读完本文,你将掌握 Chalice 的安装配置、REST API 与事件驱动应用的编写方式,理解其自动 IAM 策略生成与部署管线的底层实现,并能在 30 秒内完成第一个应用的部署与验证。

Chalice 是什么

Chalice 是专为在 AWS 上编写 Serverless 应用而设计的 Python 框架。它基于 AWS Lambda 运行你的代码,核心价值在于把"从代码到上线"之间的大量胶水工作(打包、权限、事件源绑定、API 网关配置)全部自动化。根据仓库根目录的 README.rst,它主要提供三大能力:

  • 命令行工具:负责创建(new-project)、部署(deploy)、管理(logs、invoke、delete 等)你的应用;
  • 装饰器风格 API:通过 @app.route、@app.schedule、@app.on_s3_event、@app.on_sqs_message 等装饰器,将 Lambda 函数与 Amazon API Gateway、Amazon S3、Amazon SNS、Amazon SQS 以及其他 AWS 服务进行集成;
  • 自动 IAM 策略生成:Chalice 会静态分析你的应用代码,识别其中调用的 AWS API,自动生成最小权限的 IAM Policy,避免手工编写权限策略。

从源码看,这些能力被组织在 chalice/app.py(核心应用对象与全部装饰器)、chalice/cli/init.py(Click 命令行入口)以及 chalice/policy.py(IAM 策略生成)等模块中。chalice 包对外导出的公共 API 定义在 chalice/init.py:除 Chalice 和 Blueprint 外,还包括 Response、CORSConfig、Rate、Cron、AuthResponse、各种 Authorizer 以及若干内置错误类(如 BadRequestError、NotFoundError)等,方便应用层直接引用。

一个装饰器,一类 AWS 集成

REST API:@app.route

编写一个返回 JSON 的 REST API 只需要几行代码,其最小示例与 chalice new-project 生成的模板 chalice/templates/0000-rest-api/app.py 完全一致:

from chalice import Chalice

app = Chalice(app_name="helloworld")

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

@app.route 默认将函数注册为 GET / 的视图。结合模板中附带的注释示例,你可以在此基础上扩展出路径参数、POST 请求与请求体读取:

@app.route('/hello/{name}')
def hello_name(name):
    # '/hello/james' -> {"hello": "james"}
    return {'hello': name}

@app.route('/users', methods=['POST'])
def create_user():
    # 读取用户通过 POST 发送的 JSON body
    user_as_json = app.current_request.json_body
    return {'user': user_as_json}

在源码 chalice/app.py 中,route 方法实际是通过 _create_registration_function(handler_type='route', ...) 注册处理函数,app.current_request 则暴露出请求上下文对象,支持 json_body、raw_body、headers 等访问方式,并可结合 CORSConfig、Authorizer 等参数定制路由行为。

定时任务:@app.schedule 与 Rate/Cron

周期性的后台任务同样用装饰器声明。比如每隔 5 分钟执行一次的任务:

from chalice import Chalice, Rate

app = Chalice(app_name="helloworld")

# 每 5 分钟自动运行一次
@app.schedule(Rate(5, unit=Rate.MINUTES))
def periodic_task(event):
    return {"hello": "world"}

Rate 与 Cron 都是 ScheduleExpression 的子类,定义在 chalice/app.py。Rate 支持 MINUTES、HOURS、DAYS 三种单位,其 to_string() 会把 Rate(5, unit=Rate.MINUTES) 转译为 CloudWatch Events 识别的 rate(5 minutes) 表达式,并在值为 1 时自动去掉复数后缀(1 minute);Cron 则接受 minutes、hours、day_of_month、month、day_of_week、year 六个字段,生成 cron(...) 表达式。你同样可以传入字符串形式的原生表达式,例如 'rate(1 hour)' 或 'cron(0 12 * * ? *)'。

S3 事件:@app.on_s3_event

当对象上传到指定 S3 桶时触发 Lambda:

from chalice import Chalice

app = Chalice(app_name="helloworld")

# 每当对象被上传到 "mybucket" 时,该 Lambda 函数就会被调用
@app.on_s3_event(bucket="mybucket")
def handler(event):
    print(
        f"Object uploaded for bucket: {event.bucket}, key: {event.key}"
    )

on_s3_event 的完整签名(见 chalice/app.py)支持更多定制:

@app.on_s3_event(bucket='mybucket',
                 events=['s3:ObjectCreated:*'],   # 监听的事件类型
                 prefix='images/',                 # 只匹配该前缀的 key
                 suffix='.jpg')                    # 只匹配该后缀的 key
def handler(event):
    pass

仓库中的事件型项目模板 chalice/templates/0002-s3-event-handler/app.py 展示了实际工程写法:桶名通过 APP_BUCKET_NAME 环境变量注入(在 .chalice/config.json 中配置),并使用 app.log.debug 记录日志,同时默认开启了 app.debug = True 便于本地排查。对应的底层配置类 S3EventConfig 会记录 bucket、events、prefix、suffix 四个字段(chalice/app.py),在部署阶段由 chalice/deploy/appgraph.py 中的 _create_bucket_notification 转换为 S3 桶通知配置。

SQS 队列:@app.on_sqs_message

从队列中消费消息:

from chalice import Chalice

app = Chalice(app_name="helloworld")

# 每当有消息发送到 "my-queue-name" 这个 SQS 队列时,调用该函数
@app.on_sqs_message(queue="my-queue-name")
def handler(event):
    for record in event:
        print(f"Message body: {record.body}")

on_sqs_message 的签名(chalice/app.py)还支持队列 ARN 与批量消费参数:

@app.on_sqs_message(queue_arn='arn:aws:sqs:us-west-2:123456789012:my-queue',
                    batch_size=10,           # 每次批量拉取的消息条数
                    maximum_batching_window_in_seconds=5)  # 最长攒批等待时间
def handler(event):
    ...

SQSEventConfig 类(chalice/app.py)记录了 queue/queue_arn、batch_size、maximum_batching_window_in_seconds、maximum_concurrency 等字段。部署时 Chalice 会通过 create_lambda_event_source 创建 Lambda 事件源映射,并在 chalice/deploy/validate.py 的 validate_sqs_configuration 中对队列名/ARN 的合法性做前置校验。

更多 AWS 集成

README 中提到的"其他若干 AWS 资源"在源码层面都有对应装饰器,它们共享同一套注册机制(_create_registration_function / _register_handler):

装饰器 作用 关键配置类
@app.on_sns_message(topic=...) 订阅 SNS 主题消息 SNSEventConfig
@app.on_cw_event(event_pattern={...}) 按事件模式匹配 CloudWatch Events CloudWatchEventConfig
@app.on_kinesis_record(stream=..., batch_size=100, starting_position='LATEST') 消费 Kinesis 流记录 KinesisEventConfig
@app.on_dynamodb_record(stream_arn=..., batch_size=100) 消费 DynamoDB 流记录 DynamoDBEventConfig
@app.lambda_function() 纯 Lambda 函数,不绑定任何触发器 LambdaFunctionEventConfig
@app.on_ws_connect / on_ws_message / on_ws_disconnect WebSocket API 的三种生命周期事件 Websocket*Config

所有事件源配置类均继承自 BaseEventSourceConfig,统一携带 name 与 handler_string 字段,这为后续部署阶段的资源规划(见 chalice/deploy/planner.py 与 chalice/deploy/appgraph.py)提供了统一的数据模型。

30 秒跑通第一个应用:完整 Quickstart

README 提供了完整可复现的快速开始流程,本文按其步骤逐段说明(Quickstart 以 Python 3.10 为例,Chalice 支持 AWS Lambda 所支持的全部 Python 版本,即 Python 3.10 至 Python 3.14)。

第 1 步:安装 Chalice

先创建并激活虚拟环境,再通过 pip 安装:

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

安装完成后可用 --help 验证,你会看到完整的子命令列表:

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

从 chalice/cli/init.py 可以看到,CLI 基于 Click 构建,根命令 chalice 支持 --project-dir 与 --debug/--no-debug 全局选项;--project-dir 未指定时默认使用当前工作目录(os.getcwd())。每次执行 CLI 命令时还会设置环境变量 AWS_CHALICE_CLI_MODE=true,供应用代码在本地与 Lambda 运行时区分行为。除 README 展示的命令外,CLI 还内置了 local(本地模拟运行)、logs(查看 Lambda 日志)、invoke(手动调用函数)、url(获取 API URL)、gen-policy(生成 IAM 策略)、package(生成 CloudFormation/SAM 模板)等实用命令。

第 2 步:配置 AWS 凭据

部署前必须配置 AWS 凭据。如果你之前已经配置过 boto3 或 AWS CLI,可以直接跳过本节。首次使用可手动创建默认配置:

$ 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)

配置成功后,Chalice 会通过 botocore 会话(chalice/cli/factory.py 中的 create_botocore_session)自动读取这些凭据完成 AWS 调用。

第 3 步:创建项目

使用 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'}

new-project 命令定义在 chalice/cli/init.py 的 new_project 函数中,实际的项目骨架生成逻辑位于 chalice/cli/newproj.py(create_new_project_skeleton),它会根据 --project-type 从 chalice/templates 目录复制模板。仓库内置了多种项目模板,除默认的 REST API 外,还包括:

第 4 步:部署

在 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/

输出清晰地展示了部署管线(对应 chalice/deploy/deployer.py 的 Deployer.deploy 流程):创建部署包 → 创建 IAM 角色 → 创建 Lambda 函数 → 创建 REST API。默认使用 dev 阶段(stage),因此资源名带 -dev 后缀。部署完成后即可用 curl 验证:

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

值得一提的是,"自动 IAM 策略生成"正是在这一步发挥作用:Chalice 通过 chalice/analyzer.py 对 app.py 做 AST 静态分析,提取代码中对 AWS 客户端的调用(get_client_calls),再由 chalice/policy.py 的 policy_from_source_code 基于 chalice/policies.json 中的 API 动作映射生成最小权限策略,作为 create_role 的入参传给 AWS。

尝试修改 index() 返回的字典内容,再执行 chalice deploy 即可增量重新部署。

第 5 步:清理资源(可选)

实验结束后,chalice delete 会删除部署时创建的全部资源:

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

删除逻辑由 chalice/deploy/deployer.py 中的删除型 Deployer 与 chalice/deploy/sweeper.py(ResourceSweeper)协作完成:后者对比本次部署记录(deployed.json)与当前应用定义的资源差异,仅清理属于该应用且已不再需要的资源。

项目结构速览

从仓库根目录的布局可以直观看出 Chalice 的模块划分,这也是排查问题与二次开发时的导航图:

chalice/                  # 框架核心源码
├── app.py                # Chalice 应用对象、全部装饰器、事件配置类、请求/响应模型
├── analyzer.py           # AST 分析,为自动 IAM 策略生成提取 AWS API 调用
├── policy.py             # 由源码生成最小权限 IAM Policy
├── awsclient.py          # 对 AWS SDK 的封装(创建函数、API Gateway、事件源等)
├── cli/                  # Click 命令行实现(new-project / deploy / delete / logs / local ...)
├── deploy/               # 部署管线(appgraph / planner / executor / deployer / sweeper ...)
├── templates/            # 各类项目骨架模板
├── local.py              # chalice local 本地模拟运行
└── test.py               # 本地测试客户端(HTTP / Lambda / 事件生成器)
tests/                    # 单元测试与功能测试(unit/、functional/、aws/ 等)
docs/source/              # 官方文档源文件(tutorials/ 教程、topics/ 专题、api.rst API 参考)

如果你希望在本地调试 API 而无需反复部署,可运行 chalice local(默认监听 127.0.0.1:8000,支持代码改动自动重载,参见 chalice/cli/init.py);若要为视图函数编写测试,可直接使用 chalice/test.py 提供的 ChaliceTestClient(含 HTTP 客户端与 S3/SQS/SNS/CloudWatch/Kinesis 事件生成器),仓库中的模板测试示例见 chalice/templates/0000-rest-api/tests/test_app.py。

下一步可以做什么

现在你已经用 Chalice 完成了第一个应用的创建与部署。后续可以按需深入:

  • 跟随官方教程:仓库 docs/source/tutorials 提供了 Basic REST API、事件驱动、自定义域名、WebSocket 聊天室等分步教程;
  • 查阅专题文档:docs/source/topics 涵盖路由、蓝图(Blueprints)、授权器(Authorizers)、中间件、配置管理、WebSocket、CDK 集成等深度主题;
  • 查阅 API 参考:仓库 docs/source/api.rst 与 chalice/ 源码是公共 API 的权威来源,各事件配置类、请求/响应对象与装饰器签名均可在 chalice/app.py 中找到。

以上所有内容均以当前仓库 README.rst 为核心骨架,并结合 chalice/app.py、chalice/cli/init.py、chalice/deploy 等源码与模板文件补充了实现细节,便于你在阅读文档的同时对照源码验证每一项行为。

登录后查看全文
chalice