【ITニュース解説】Avoiding the 'Common' Trap: How I Structure Shared Packages at HoneyDrunk

大規模なシステム開発を進める際、「共通部品」と呼ばれるコードの集合体をどのように管理するかは、非常に重要な課題となる。多くの開発者が陥りがちなのが、「Common」や「Shared」といった名前のついた巨大なライブラリに、あらゆる種類の共通コードをまとめてしまうという落とし穴である。最初は便利に感じるかもしれないが、時間が経つにつれて、このライブラリは誰にも全体像が把握できず、変更を加えるのも恐ろしい「怪物」のような存在になってしまう。機能が混在し、依存関係が複雑になり、システムの保守や拡張が極めて困難になるのである。

このような問題を避けるため、HoneyDrunkというプロジェクトでは、共有パッケージの構造を事前に慎重に設計している。これは、将来の自分自身が過去の設計に悩まされないようにするための、戦略的な取り組みだ。システムの土台となる部分から、段階的に具体的な機能へとパッケージを分割していくことで、各部品の役割を明確にし、独立性を高めることを目指す。

まず、システムの心臓部となる「基盤」となる機能から着手する。これらは、特定のビジネスロジックを持たず、システム全体で共通して利用される基本的な構成要素である。例えば、HoneyDrunk.Coreには、システム内のデータの基本形（エンティティ）や、システム内で発生する出来事（ドメインイベント）、共通のエラー処理（例外）などが含まれる。HoneyDrunk.Validationはデータの正しさをチェックするルールを提供し、HoneyDrunk.Securityはパスワードの暗号化やユーザー認証に関する機能（JWTユーティリティなど）を担当する。また、HoneyDrunk.Cachingはデータの一時的な保存（キャッシュ）の仕組みを提供し、HoneyDrunk.Configurationはシステムの設定情報を安全に管理する方法を定義し、HoneyDrunk.FeatureFlagsは特定の機能をオンオフするための仕組みを提供する。これらは、まるで家を建てる際の基本的なブロックのように、他のすべての部品の土台となる。

次に、データの扱いとネットワーク通信に関するパッケージを定義する。HoneyDrunk.Dataは、データベースへのアクセス方法（EF Coreパターン、DbContextヘルパー、マイグレーションなど）を標準化する。HoneyDrunk.Storageは、ファイルや画像などのデータを保存する場所（クラウドストレージやローカルファイルシステムなど）の違いを吸収し、一貫したインターフェースを提供する。HoneyDrunk.Httpは、外部サービスと通信するための信頼性の高いHTTPクライアント（エラー時の自動再試行や接続切断機能など）を提供する。HoneyDrunk.RestServiceは、HTTP通信をより簡単に利用するための共通処理をまとめる。さらに、HoneyDrunk.Grpcは高速なシステム間通信のための契約やヘルパーを提供し、HoneyDrunk.SignalRはリアルタイム通信の機能を提供する。

特に注意が必要なのが、「メッセージング」と「通知」の違いである。多くの開発者がこれらを混同しがちだが、HoneyDrunkでは明確に区別している。HoneyDrunk.Messagingは、システム同士が互いに情報やコマンドをやり取りするための仕組み（イベント発行/購読、サービスバスコマンドなど）を扱う。一方、HoneyDrunk.Notifications.Email、HoneyDrunk.Notifications.Sms、HoneyDrunk.Notifications.Pushは、人間（ユーザー）に対して情報（メール、SMS、プッシュ通知など）を届けるための機能に特化している。システム間の連携と、ユーザーへの情報伝達という、異なる目的を持つ機能は、別のパッケージとして扱うべきである。

システムの健全性を保つためには、「可観測性」と「品質」も重要である。HoneyDrunk.Observabilityパッケージは、システムの状態を監視し、問題を早期に発見するための機能（ログ記録、メトリクス収集、処理の追跡など）を提供する。これにより、開発者はシステムがどのように動作しているかを正確に把握できる。また、HoneyDrunk.Testingは、システムの品質を保証するための様々なテスト支援ツール（モックオブジェクトの設定、UIテストヘルパー、テストデータなど）をまとめる。

ビジネスロジックが絡む部分では、より上位の概念でパッケージを分割する。例えば、「支払い」機能だけをまとめるのではなく、HoneyDrunk.Commerce.Orders（注文管理）、HoneyDrunk.Commerce.Payments（支払い処理）、HoneyDrunk.Commerce.Billing（請求管理）のように、商取引という大きな枠組みの中で、より具体的な機能に分ける。これにより、例えば注文と請求の仕組みは必要だが、支払いは別のシステムに任せる、といった柔軟な対応が可能になる。

外部サービスとの連携も重要であり、これらはHoneyDrunk.Integrationsの下に、連携するサービスごとにパッケージを分ける。例えば、HoneyDrunk.Integrations.StreamingにはTwitchやYouTubeとの連携機能が、HoneyDrunk.Integrations.MediaにはAniListやTMDBとの連携機能が、HoneyDrunk.Integrations.GamingPlatformsにはSteamやEpic Gamesなどのゲームプラットフォームとの連携機能が、HoneyDrunk.Integrations.SocialにはDiscordやTwitter/X、Redditといったソーシャルメディアとの連携機能が含まれる。

システム開発を効率化し、他の開発者やクライアントが利用しやすくするための「ツール」や「SDK（ソフトウェア開発キット）」も別途パッケージ化する。HoneyDrunk.Tooling.DevOpsは、開発・運用プロセスを支援するユーティリティ（データベーススキーマ管理ツール、パイプラインヘルパー、インフラ構築スクリプトなど）を提供する。また、HoneyDrunk.Sdk.DotNetや将来的なHoneyDrunk.Sdk.JavaScriptは、このシステムが提供する機能を利用するための専用ライブラリであり、外部のアプリケーションが簡単に連携できるようになる。

これらの様々なパッケージは、それ自体が最終的なユーザー向けプロダクトではない。これらはシステムを動かす「エンジンルーム」のようなものであり、実際にユーザーが触れる部分は、これらのパッケージの上に構築される「サテライトサイト」と呼ばれるアプリケーション群である。例えば、ユーザー向けのWebサイトはNext.jsで、モバイルアプリはExpoで、管理者向けの画面はBlazorで、マーケティング用のブログやドキュメントはAstroで構築される。ここで重要なルールは、これらのユーザー向けアプリケーションがデータベースに直接アクセスせず、必ずAPIやSDKを通じてバックエンドの機能を利用することだ。これにより、各アプリケーションの役割が明確になり、システムの安全性と保守性が向上する。

このように、HoneyDrunkでは、パッケージの名前一つ一つに意味を持たせ、明確な境界線を設けることを重視している。細かすぎると逆に管理が大変になり、曖昧すぎると再び「共通パッケージの罠」に陥る。適切な粒度でパッケージを分割し、それぞれの役割を明確にすることで、将来的にシステムがどのように成長しても、その変化に対応しやすい柔軟な構造を築くことを目指している。これは単なる技術的な手法ではなく、システムの長期的な戦略そのものである。