Bootstrap python service

Python サービスのブートストラップ

これは、クリーンアーキテクチャ と SOLID 原則 の概念を適用した Python アプリケーションの実装例です。

• リポジトリクラスはインターフェースの背後に分離されており、インターフェース分離の原則と 制御の反転設計パターンを適用しています
• アプリケーションフレームワークはドメインロジックから分離されています
• ストレージレイヤーはドメインロジックから分離されています

このテンプレートには、すぐに使える一般的な機能がいくつか備わっています。

• FastAPI と AsyncAPI を使用した同期・非同期 API ドキュメント
• Dramatiq を使用した非同期タスクの実行
• Socket.io を使用した WebSocket アプリケーション
• SQLAlchemy と SQLAlchemy bind manager を使用したデータベース向けリポジトリパターン
• Alembic を使用したデータベースマイグレーション（同期・非同期の両方の SQLAlchemy エンジンに対応するよう設定済み）
• カスタマイズした Alembic 設定によるデータベースフィクスチャのサポート
• ORY Zero Trust アーキテクチャ を使用した認証とアイデンティティプロバイダー
• OpenTelemetry を使用した完全な可観測性の設定（メトリクス、トレース、ログ）
• GitLab 向け CI/CD デプロイパイプラインの例（このリポジトリでは引き続き GitHub を主に扱いますが、GitLab を使いたい場合に備えています 🤷）
• [TODO] HTTP を使用して CloudEvents 形式のイベントを発行・消費するプロデューサーとコンシューマー。Knative Eventing との利用を想定しています

ドキュメント

詳細なドキュメントは次の場所で確認できます。

• GitHub Pages でオンライン閲覧
• 依存関係を make dev-dependencies でインストールした後、make docs を実行してオフラインで閲覧

使い方

このテンプレートを使用して、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：テスト、コードスタイル、リンティングのチェックを実行します
• make fix：可能な場合は自動修正を行いながら、テスト、コードスタイル、リンティングのチェックを実行します

マルチステージ Dockerfile の設定

Python の Docker イメージは、アプリケーションの依存関係をインストールすると大きくなりがちです（圧縮されていない slim ベースイメージは約 150 MB です）。そのため、多少複雑なマルチステージ Dockerfile になっても、イメージサイズの最小化に取り組むことが重要です。

以下の設定では、本番環境のイメージを最小サイズ（「わずか」360 MB）に保てます。

• 150MB のベースイメージ
• 210MB の Python インストール済み依存関係

以下のパイプラインを使用した場合、「test」イメージは約 850MB になります。これは、イメージをプルするたびに発生する通信コストが 400MB 以上増えることになります。