使用 Cookiecutter FastStream 模板快速搭建 FastStream 事件驱动应用
使用 Cookiecutter FastStream 模板快速搭建 FastStream 事件驱动应用
FastStream 是面向 Kafka、RabbitMQ、NATS、Redis、MQTT 等消息代理的异步事件驱动框架。要在一分钟内得到一个开箱即用的 FastStream 项目骨架,官方推荐的路径是 Cookiecutter FastStream 为骨架,完整讲解如何用它生成项目、搭建本地开发环境、跑通测试与静态分析、本地运行应用、构建 Docker 镜像,以及如何在 CI 中自动生成 AsyncAPI 文档并部署到服务器,最终掌握一整套可复用的 FastStream 工程化落地流程。
模板特性一览
Cookiecutter FastStream 模板为你准备的并非一个空壳,而是一套经过验证的工程底座,涵盖以下能力:
- 基础应用:模板自带一个可运行的 Python 基础应用(位于
app/目录),你可以直接替换为自有业务代码; - 测试框架:预置
pytest{.external-link target="_blank"},测试写在tests/目录,配套自动化测试工作流; - 代码规范:内置
mypy{.external-link target="_blank"}、black{.external-link target="_blank"}、ruff{.external-link target="_blank"}、bandit{.external-link target="_blank"} 的脚本与配置,保证代码风格统一、类型安全; - Docker 支持:附带 Dockerfile,可一键将 FastStream 应用容器化;
- 依赖管理:应用依赖与开发依赖统一声明在
pyproject.toml中,pytest、mypy、black、ruff、bandit等工具配置也集中于此; - 持续集成(CI):
.github/workflows下预置三套 GitHub Actions 工作流,覆盖静态分析、测试、Docker 镜像构建推送与 AsyncAPI 文档部署。
从仓库实践看,这种“脚手架 + 工程规范”的思路与 FastStream 主仓库高度一致:主仓库自身的 pyproject.toml 同样集中管理着依赖与工具配置,Dockerfile 与 justfile 提供了容器化与各类开发命令的入口,模板正是把这些最佳实践以可复制的形态交付给每个新项目。
环境准备与项目生成
1. 安装 cookiecutter
使用 pip 安装 cookiecutter{.external-link target="_blank"}:
pip install cookiecutter
2. 生成 FastStream 项目
执行以下命令并交互式填写项目相关信息(项目名、slug、Kafka 相关参数等):
cookiecutter https://github.com/ag2ai/cookiecutter-faststream.git
命令执行后,模板会引导你逐步填写配置,最终在当前目录下生成一个完整的新项目,交互过程类似下图(以创建基于 Kafka 的 FastStream 应用为例):
注:上述截图来自本仓库的 AsyncAPI 文档页面演示,用于示意生成项目的交互式 CLI 流程;实际生成时的提示文本以模板为准。
3. 进入项目目录
cd <directory-name>
注意:将
<directory-name>替换为你生成的项目目录名。
4. 安装开发依赖
模板使用 PEP 668 兼容的依赖组机制,安装全部开发依赖:
pip install --group dev -e .
-e 表示以可编辑(editable)模式安装,便于后续修改 app/ 下源码时无需重装即可生效;--group dev 会连同 pyproject.toml 中 [project.optional-dependencies] 定义的 dev 工具组一起安装。
5. 创建 GitHub 仓库并完成首次提交
在 GitHub 上新建一个仓库后,执行初始化、提交与推送:
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:<username>/<repo-name>.git
git push -u origin main
注意:将
<username>替换为你的 GitHub 用户名,<repo-name>替换为仓库名。
项目结构与会话开发循环
生成后的项目采用清晰的目录约定:
app/:应用代码所在目录,所有业务功能(订阅、发布、路由)都在此编写;tests/:与app/对应的测试目录;.github/workflows/:CI 工作流定义;pyproject.toml:依赖声明与工具配置的中心;justfile:封装常用开发命令(启动/停止 Kafka、lint、静态分析等)的入口。
模板约定:代码改动必须同步更新对应测试。改动 app/ 中的功能后,需在 tests/ 中补充或调整测试,再执行验证。
运行测试
在 tests/ 目录中补充好测试后,直接运行:
pytest
pytest 会执行整个测试套件。FastStream 框架本身支持 内存测试(in-memory testing),即无需真实消息代理即可对消费、发布逻辑做单元验证;模板默认的 CI 测试工作流也正是依赖这一能力,保证在无外部基础设施的情况下测试即可通过。
本地运行 FastStream 应用
1. 启动本地 Kafka
模板通过 just 命令封装了 Docker Compose 操作,启动 Kafka 容器:
just kafka-up
这与主仓库 justfile 中的 kafka-up 定义一致——其本质是执行 docker compose up -d kafka。
2. 启动应用
faststream run <directory-name>.application:app --workers 1
其中 <directory-name> 是根据项目 slug 自动生成的目录名,内含 app.py。faststream run 是框架提供的 CLI 入口,其参数在 CLI 主模块 中定义:--workers 控制进程数(对应多进程 Supervisor),还支持 --reload、--app-dir、--log-level 等选项;在非 Windows 环境且未指定 --loop 时,CLI 会自动尝试加载 uvloop 作为事件循环实现。
3. 停止应用
在终端按下 Ctrl+C 即可停止 FastStream 应用。
4. 停止 Kafka
just kafka-stop
本地构建与测试 Docker 镜像
1. 构建镜像
just init
该脚本会在本地构建一个与 CI 中同名的 Docker 镜像。参考主仓库的 Dockerfile 可以发现其构建策略:以指定 PYTHON_VERSION(默认 3.10)为基础镜像,将 pyproject.toml、README.md、LICENSE 与 faststream 包元数据复制进镜像,再执行 uv sync --group dev 安装依赖。
2. 确保 Kafka 已启动
容器启动前需要本地已有 Kafka 容器在运行:
just kafka-up
3. 运行本地容器
docker run --rm --name faststream-app --net=host ghcr.io/<username>/<repo-name>:latest
参数说明:
--rm:容器停止后自动删除,避免残留无用容器;--name faststream-app:为容器指定名称faststream-app;--net=host:让容器共享宿主机的网络命名空间,从而直接访问宿主机上的 Kafka 端口。
4. 停止容器与 Kafka
先在终端按 Ctrl+C 停止容器,再执行:
just kafka-stop
注意:将
<username>替换为 GitHub 用户名,<repo-name>替换为仓库名。
代码格式化与 Lint
修改代码后,执行一键修复 lint 问题:
just lint
主仓库的 justfile 给出了这一命令的完整构成:linter: ruff-format ruff-check _codespell,即依次执行 ruff format 格式化、ruff check 静态检查与 codespell 拼写检查,覆盖代码风格、潜在问题与拼写错误的全面校验。
静态分析
静态分析工具能提前发现类型与安全问题,运行:
just static-analysis
从主仓库 justfile 可见 static-analysis: mypy pyright bandit semgrep,即默认执行 mypy(类型检查)、pyright(类型检查)、bandit(安全扫描,配置位于 pyproject.toml 的 [tool.bandit] 段)与 semgrep(语义扫描)四类检查。若出现静态分析错误,请修正代码后重跑,直到全部通过。模板中的 Tests 工作流即采用 mypy + bandit 组合进行静态分析。
本地查看 AsyncAPI 文档
FastStream 原生支持 AsyncAPI{.external-link target="_blank"} 规范文档,应用中的订阅、发布通道与消息结构会由框架自动生成规范并渲染成可交互的 HTML 文档。
1. 启动文档服务
faststream docs serve <directory-name>.application:app
该命令会基于你的应用构建 AsyncAPI 规范文件、生成文档,并在 localhost:8000 提供访问。其底层实现在 docs.py:CLI 通过 import_from_string 导入应用对象,读取其 schema 工厂生成规范,再由 serve_app(定义于 site.py)启动 HTTP 服务。
2. 打开浏览器访问
浏览器访问 http://localhost:8000 即可查看包含 Servers、Operations、Messages、Schemas 等完整结构的 AsyncAPI 文档:
从上图可以看到,文档完整呈现了应用的服务器配置、每个操作(如 OnInputData 消费者与 Output_DataPublisher 发布者)、对应消息类型及其字段 Schema 与示例值,非常适合与团队、下游消费者共享接口契约。
3. 停止文档服务
按 Ctrl+C 停止文档服务器。
注意:将
<directory-name>替换为包含app.py的自动生成目录名。
faststream docs 子命令还支持 gen(生成 asyncapi.json/asyncapi.yaml 规范文件)以及 serve 的 --yaml、--out、--host、--port、--reload 等选项,均可通过 faststream docs --help 查看。
贡献你的改动
完成上述全部步骤后,即可提交改动:
git add .
git commit -m "Your commit message"
git push origin your-branch
然后到 GitHub 上发起 Merge Request。
CI 持续集成流水线
模板内置三套 GitHub Actions 工作流,均在代码 push 时触发:
- Tests 工作流(Tests):由两个并行作业组成。第一个作业运行静态分析工具
mypy与bandit,检查潜在问题;第二个作业运行pytest执行测试套件,两作业并行以加快 CI 速度。即使开发者在本地遗漏了 lint 或测试步骤,CI 也会在合并前拦截问题。 - Build Docker Image 工作流(Build Docker Image):单个作业,基于 Dockerfile 构建镜像并推送到 GitHub Container Registry{.external-link target="_blank"},供部署或其他用途拉取。
- Deploy FastStream AsyncAPI Docs 工作流(Deploy FastStream AsyncAPI Docs):单个作业,从规范构建 AsyncAPI 文档并部署到 GitHub Pages{.external-link target="_blank"},方便利益相关方访问与分享接口文档。
查看部署在 GitHub Pages 的 AsyncAPI 文档
当 Deploy FastStream AsyncAPI Docs 工作流在 CI 中成功完成后,文档会自动部署到 GitHub Pages,打开浏览器访问:
https://<username>.github.io/<repo-name>/
即可看到托管的 AsyncAPI 文档站点。这一集中式托管方式便于把 AsyncAPI 规范分享给他人,也为持续审阅文档提供统一入口。
注意:将
<username>替换为 GitHub 用户名,<repo-name>替换为仓库名。
部署 Docker 容器到服务器
当 Build Docker Image 工作流在 CI 中成功后,镜像已推送至 GitHub Container Registry,可按下述步骤部署到服务器:
1. 拉取镜像
docker pull ghcr.io/<username>/<repo-name>:latest
注意:将
<username>替换为 GitHub 用户名,<repo-name>替换为仓库名。
2. 启动容器
docker run --rm --name faststream-app --env-file /path/to/env-file ghcr.io/<username>/<repo-name>:latest
参数说明:
--rm:容器停止后自动删除;--name faststream-app:指定容器名称;--env-file /path/to/env-file:指定环境变量文件(通常是.env)路径,其中存放 FastStream 应用所需的 Kafka host、端口、认证信息等配置。将密钥与配置放在环境文件中是处理敏感信息的推荐安全实践。
按此流程即可完成 FastStream 应用的容器化部署;请根据实际应用需求自定义 env-file 与相关环境变量。
小结
Cookiecutter FastStream 模板把 FastStream 项目的初始化、测试、lint、静态分析、容器化、CI 与 AsyncAPI 文档化串联成一条完整的工程链路:cookiecutter 生成骨架 → pip install --group dev -e . 安装依赖 → just kafka-up 起本地代理 → faststream run 本地运行 → just lint/just static-analysis 保障质量 → faststream docs serve 本地审阅接口文档 → 推送代码触发 CI(测试 + 镜像 + 文档部署)→ 服务器拉取镜像完成上线。无论从零起步新项目,还是为既有服务补充工程化规范,这一模板都是通往生产级 FastStream 应用的快速路径。

