AWS SAM CLI 开发环境搭建与贡献指南

AWS SAM CLI 开发环境搭建与贡献指南

aws-sam-cli CLI tool to build, test, debug, and deploy Serverless applications using AWS SAM 项目地址: https://gitcode.com/gh_mirrors/aw/aws-sam-cli

前言

AWS SAM CLI 是一个强大的工具，用于在本地构建、测试和调试基于 AWS Serverless Application Model (SAM) 的无服务器应用程序。本文将详细介绍如何搭建 AWS SAM CLI 的开发环境，以及如何为该项目贡献代码。

开发环境准备

Python 环境要求

AWS SAM CLI 主要使用 Python 3 开发，支持 Python 3.8 及以上版本。建议使用虚拟环境来隔离开发环境。

虚拟环境选择

我们提供两种虚拟环境设置方案：

1. venv - Python 内置的虚拟环境工具
2. pyenv - 支持多版本 Python 管理的工具

对于大多数开发者，venv 是更简单的选择；如果需要测试不同 Python 版本的兼容性，pyenv 更为合适。

venv 设置步骤

python3 -m venv .venv  # 创建虚拟环境
source .venv/bin/activate  # 激活虚拟环境

pyenv 设置步骤（macOS/Linux）

# 安装 pyenv
brew install pyenv
brew install pyenv-virtualenv

# 创建特定 Python 版本的虚拟环境
pyenv install 3.8.9
pyenv virtualenv 3.8.9 samcli38
pyenv activate samcli38

初始化开发环境

1. 克隆仓库到本地
2. 进入项目目录
3. 运行初始化命令

make init  # Linux/macOS
./Make -Init  # Windows PowerShell

初始化完成后，会生成 samdev 可执行文件，可以通过 samdev --version 验证安装是否成功。

开发工作流

代码修改与测试

1. 修改代码后，建议运行以下命令进行本地验证：

make pr  # 运行完整的 PR 检查

2. 对于 Windows 用户：

./Make -pr

多版本 Python 测试

AWS SAM CLI 支持 Python 3.8 及以上版本，建议在不同 Python 版本中测试你的修改：

# 切换到 Python 3.8 环境
pyenv deactivate
pyenv activate samcli38
make init
make pr

集成测试

• 针对全局安装的 SAM CLI 运行集成测试：

make integ-test

• 针对开发版本运行集成测试：

SAM_CLI_DEV=1 make integ-test

代码规范与最佳实践

代码风格

1. 使用 Black 代码格式化工具：

make black

2. 或者设置 IDE 自动格式化（推荐 PyCharm + Black 插件）

文档规范

• 使用 numpy 文档字符串格式
• 模块级日志变量必须命名为 LOG
• 避免使用 *args 和 **kwargs 除非有充分理由

异常处理

• 自定义异常优于内置异常
• CLI 命令必须抛出 click.ClickException 的子类
• 避免捕获宽泛的 Exception

测试策略

AWS SAM CLI 采用分层测试策略：

1. 单元测试 - 测试独立代码路径，使用 mock 隔离外部依赖
2. 功能测试 - 测试包含外部依赖的组件
3. 集成测试 - 测试完整的用户工作流

依赖管理

更新依赖时需要注意：

1. 代码依赖更新 requirements/base.txt
2. 测试依赖更新 requirements/dev.txt
3. 构建依赖更新 requirements/pyinstaller-build.txt
4. 同时更新 reproducible-linux.txt 和 THIRD-PARTY-LICENSES

make update-reproducible-reqs

设计文档

对于重大变更，建议先编写设计文档，内容包括：

• 功能概述
• 用户场景
• 技术方案
• 兼容性考虑
• 测试计划

结语

通过本文，你应该已经掌握了 AWS SAM CLI 的开发环境搭建方法和贡献流程。遵循这些规范将帮助你更高效地为项目做出贡献，同时确保代码质量的一致性。如果在开发过程中遇到问题，可以参考项目文档或联系维护团队获取支持。

aws-sam-cli CLI tool to build, test, debug, and deploy Serverless applications using AWS SAM 项目地址: https://gitcode.com/gh_mirrors/aw/aws-sam-cli