使用 Cookiecutter FastStream 模板快速搭建 FastStream 事件驱动应用

原创2026-09-17 12:54:521,873 阅读
文章标签:后端消息队列微服务

使用 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 应用为例):

使用 cookiecutter 生成 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 文档:

FastStream 生成的 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 时触发:

  1. Tests 工作流(Tests):由两个并行作业组成。第一个作业运行静态分析工具 mypy 与 bandit,检查潜在问题;第二个作业运行 pytest 执行测试套件,两作业并行以加快 CI 速度。即使开发者在本地遗漏了 lint 或测试步骤,CI 也会在合并前拦截问题。
  2. Build Docker Image 工作流(Build Docker Image):单个作业,基于 Dockerfile 构建镜像并推送到 GitHub Container Registry{.external-link target="_blank"},供部署或其他用途拉取。
  3. 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 应用的快速路径。

登录后查看全文
faststream