Bootstrap python service

Bootstrap Python 服务

这是一个 Python 应用示例，实现了 Clean Architecture 和 SOLID 原则中的相关概念。

• 仓储类通过接口隔离，以遵循接口隔离原则 和控制反转设计模式
• 应用框架与领域逻辑解耦
• 存储层与领域逻辑解耦

此模板开箱即用地提供了一些常用功能：

• 使用 FastAPI 和 AsyncAPI 编写同步和异步 API 文档
• 使用 Dramatiq 执行异步任务
• 使用 Socket.io 构建 WebSocket 应用
• 使用 SQLAlchemy 和 SQLAlchemy bind manager 实现数据库仓储模式
• 使用 Alembic 进行数据库迁移（配置为支持同步和异步 SQLAlchemy 引擎）
• 通过自定义的 Alembic 配置支持数据库 Fixtures
• 使用 ORY Zero Trust architecture 实现身份验证和身份提供方
• 使用 OpenTelemetry 配置完整的可观测性（指标、追踪和日志）
• 提供 GitLab 的 CI/CD 部署流水线示例（此仓库仍以 GitHub 为重点，不过如果你想使用 GitLab，也可以 🤷）
• [TODO] 使用 HTTP 以 CloudEvents 格式生成和消费事件的生产者与消费者，可与 Knative Eventing 配合使用

文档

详细文档可通过以下方式查看：

• 在线查看：GitHub pages
• 离线查看：安装依赖后运行 make docs，依赖通过 make dev-dependencies 安装

使用方法

使用此模板创建你的 GitHub 仓库（绿色的 Use this template 按钮）。 你可以选择在 pyproject.toml 文件中调整名称和作者，但构建应用时不会使用这些元数据， 代码中也不会引用它们。

运行任何命令之前，请先安装 uv 和 Docker：

• 在 Mac 上，你可以使用 brew 安装 uv：brew install uv
• 下载并安装 Docker：https://www.docker.com/products/docker-desktop/

使用 Docker：

• make containers：构建容器
• docker compose up dev-http：运行支持热重载的 HTTP 应用
• docker compose up dev-socketio：运行支持热重载的 HTTP 应用
• docker compose up dramatiq-worker：运行 dramatiq 工作进程
• docker compose run --rm test：运行测试套件
• docker compose run --rm migrate：运行数据库迁移
• docker compose run --rm autogenerate-migration：生成新的迁移文件

使用 Make（大多数命令仍需要 Docker）：

• make install-dependencies：安装依赖项
• make dev-dependencies：安装开发依赖项
• make update-dependencies：更新依赖项
• make dev-http：运行支持热重载的 HTTP 应用
• make dev-socketio：运行支持热重载的 HTTP 应用
• make test：运行测试套件
• make migrate：运行数据库迁移
• make autogenerate-migration：生成新的迁移文件

其他开发命令

• make check：运行测试、代码风格和 lint 检查
• make fix：运行测试、代码风格和 lint 检查，并在可能的情况下自动修复问题

多阶段 Dockerfile 配置

安装应用依赖项后，Python Docker 镜像往往会变得很大（精简基础镜像解压后约为 150 MB），因此即使会让多阶段 Dockerfile 稍微复杂一些，也要尽可能缩小镜像体积。

以下配置可确保生产镜像保持最小体积（“仅” 360 MB）：

• 150 MB 基础镜像
• 210 MB Python 已安装依赖项

使用以下流水线构建的“test”镜像则约为 850 MB，每次拉取镜像都会产生超过 400 MB 的流量成本。