moai-domain-backend

バックエンド開発スペシャリスト

クイックリファレンス

バックエンド開発の習得 — API 設計、データベース連携、マイクロサービス、最新のアーキテクチャパターンを網羅した、包括的なバックエンド開発パターンです。

主な機能：

• API 設計：OpenAPI 3.1 に対応した REST、GraphQL、gRPC
• データベース連携：PostgreSQL、MongoDB、Redis、キャッシュ戦略
• マイクロサービス：サービスメッシュ、分散パターン、イベント駆動型アーキテクチャ
• セキュリティ：認証、認可、OWASP 準拠
• パフォーマンス：キャッシュ、最適化、監視、スケーリング

使用する場面：

• バックエンド API の開発とアーキテクチャ設計
• データベースの設計と最適化
• マイクロサービスの実装
• パフォーマンスの最適化とスケーリング
• バックエンドシステムへのセキュリティの統合

---

実装ガイド

API 設計パターン

RESTful API アーキテクチャ：

認証とレスポンスモデルを備えた FastAPI アプリケーションを作成します。id、email、name フィールドを持つ Pydantic の UserResponse モデルを定義します。HTTPBearer セキュリティ依存関係を使用して、list_users エンドポイントと create_user エンドポイントを実装します。list エンドポイントは UserResponse オブジェクトのリストを返し、create エンドポイントは UserCreate モデルを受け取り、単一の UserResponse を返します。

GraphQL の実装：

Strawberry を使用して GraphQL 型を定義します。id、email、name フィールドを持つ User 型を作成します。User オブジェクトのリストを非同期で返す users リゾルバーを備えた Query 型を定義します。Query 型を strawberry.Schema に渡してスキーマを生成します。

データベース連携パターン

SQLAlchemy を使った PostgreSQL：

declarative_base を使用して SQLAlchemy モデルを定義します。id を主キー、email を一意の文字列、name を文字列カラムとする User モデルを作成します。接続プールのパラメーターとして、pool_size を 20、max_overflow を 30 に設定し、接続のヘルスチェックのために pool_pre_ping を有効にして、エンジンを構成します。

Motor を使った MongoDB：

AsyncIOMotorClient で初期化する UserService クラスを作成します。コンストラクターでデータベースと users コレクションを設定します。email（一意）フィールドと created_at フィールドにインデックスを作成します。ドキュメントを挿入し、inserted_id を文字列として返す create_user メソッドを実装します。

マイクロサービスアーキテクチャ

Consul によるサービスディスカバリー：

Consul に接続する ServiceRegistry クラスを作成します。name、id、port、ヘルスチェックエンドポイントを指定してサービスを登録する register_service メソッドを実装します。正常なサービスを照会し、address:port 形式の文字列のリストを返す discover_service メソッドを実装します。

イベント駆動型アーキテクチャ：

AMQP メッセージングに aio_pika を使用する EventBus クラスを作成します。接続とチャネルを確立する connect メソッドを実装します。イベントの種類とデータを JSON としてシリアル化し、イベントの種類に一致する routing_key を指定してデフォルトの交換にパブリッシュする publish_event メソッドを実装します。

---

高度なパターン

キャッシュ戦略

Redis の連携：

Redis 接続を備えた CacheManager クラスを作成します。ttl パラメーターを受け取る cache_result デコレーターを実装します。このデコレーターは関数名と引数からキャッシュキーを生成し、Redis にキャッシュ済みの結果があるか確認します。キャッシュミスの場合は関数を実行し、結果を有効期限付きで保存します。シリアル化には json.loads と json.dumps を使用します。

セキュリティの実装

JWT 認証：

パスワードの bcrypt ハッシュ化に CryptContext を使用する SecurityManager クラスを作成します。コンテキストを使用する hash_password メソッドと verify_password メソッドを実装します。HS256 アルゴリズムを使用し、有効期限を含む JWT をエンコードする create_access_token を実装します。指定がない場合、有効期限はデフォルトで 15 分です。

パフォーマンスの最適化

データベース接続プーリング：

QueuePool を使用し、pool_size を 20、max_overflow を 30 に設定し、pool_pre_ping を有効にして、pool_recycle を 3600 秒に設定した、最適化済みの SQLAlchemy エンジンを作成します。before_cursor_execute と after_cursor_execute にイベントリスナーを追加して、クエリの実行時間を追跡します。100ms のしきい値を超えるクエリについて警告をログに記録します。

---

適切に連携するもの

• moai-domain-frontend - フルスタック開発との統合
• moai-domain-database - 高度なデータベースパターン
• moai-foundation-core - バックエンドサービス向けの MCP サーバー開発パターン
• moai-foundation-quality + moai-ref-owasp-checklist - セキュリティ検証とコンプライアンス
• moai-foundation-core - 中核となるアーキテクチャ原則

---

技術スタック

主要技術：

• 言語：Python 3.13+、Node.js 20+、Go 1.23
• フレームワーク：FastAPI、Django、Express.js、Gin
• データベース：PostgreSQL 16+、MongoDB 7+、Redis 7+
• メッセージキュー：RabbitMQ、Apache Kafka、Redis Pub/Sub
• コンテナ化：Docker、Kubernetes
• モニタリング：Prometheus、Grafana、OpenTelemetry

統合パターン：

• OpenAPI 3.1 を使用した RESTful API
• Apollo Federation を使用した GraphQL
• 高性能サービス向けの gRPC
• CQRS を用いたイベント駆動型アーキテクチャ
• API ゲートウェイパターン
• サーキットブレーカーとレジリエンスパターン

---

ステータス：本番環境で利用可能 保守担当：MoAI-ADK Backend Team

よくある自己正当化

自己正当化	実情
「入力検証はフロントエンドで行えばよい」	フロントエンドの検証は UX のためのものです。バックエンドの検証はセキュリティのためのものです。目的が異なり、どちらも必要です。
「このエンドポイントは内部向けなので、認証は不要だ」	内部エンドポイントも、侵害されたサービスからアクセスされる可能性があります。ゼロトラストでは、すべてのエンドポイントで ID を検証します。
「エラー処理は後で追加すればよい」	未処理のエラーは、スタックトレース、接続文字列、内部状態を漏えいさせます。エラー処理は初日から取り組むべき作業です。
「ORM が SQL インジェクションを防いでくれる」	ORM が保護するのはパラメーター化されたクエリです。生のクエリ、動的フィルター、ORDER BY 句には、依然としてエスケープ処理が必要です。
「この API は後方互換性があるので、バージョンを上げる必要はない」	オプションフィールドの削除、デフォルト値の変更、エラー形式の変更は、既存の呼び出し元に対する破壊的変更です。
「マイクロサービスは大げさなので、エンドポイントをもう1つ追加すればよい」	エンドポイントが際限なく増えると、隠れたモノリスが生まれます。追加する前に、サービスの境界を検討してください。

ヒュラムの法則：十分な数のユーザーがいると、API のあらゆる観測可能な動作は、誰かに依存されるようになります。どんなに些細な変更でも、誰かに影響を与える可能性があります。

危険信号

• API エンドポイントが、検証またはサニタイズせずにユーザー入力を受け付けている
• エラーレスポンスにスタックトレースまたは内部パス情報が含まれている
• データベースの認証情報が環境変数ではなくソースコードにハードコードされている
• 外部公開エンドポイントにレート制限が設定されていない
• すべての失敗ケースで、レスポンス本文にエラーを含めたまま API が 200 OK を返している
• 文字列連結で生の SQL クエリを構築している

検証

• すべてのエンドポイントで処理前に入力を検証している（検証ミドルウェアまたはチェックを示す）
• エラーレスポンスが内部情報を含まない標準形式を使用している（エラーレスポンスのサンプルを示す）
• 認証情報を設定ファイルではなく環境変数から取得している（ハードコードされたシークレットを grep で検索する）
• 外部公開エンドポイントにレート制限が設定されている（ミドルウェアの登録を示す）
• API のバージョニング戦略が文書化され、適用されている
• データベースクエリにパラメーター化されたステートメントを使用している（ユーザー入力との文字列連結がない）
• 非公開エンドポイントすべてで認証が必須になっている（認証ミドルウェアを示す）