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

大規模なソフトウェア開発を進める上で、多くの人が直面する共通の課題がある。それは、システム内で頻繁に利用される共通の機能や部品を、無計画に一つの「共通パッケージ」や「Sharedライブラリ」と呼ばれる場所にまとめてしまうという問題だ。これは「共通パッケージの落とし穴」とも呼ばれ、最初は便利に思えても、時間とともにそのパッケージは巨大化し、あらゆる種類のヘルパー関数、データ伝達用のオブジェクト、既存の機能を拡張するメソッドなどが混在する「何でも屋」のような状態になる。結果として、誰も全体像を理解できず、メンテナンスが困難で、新しい機能を追加するたびに既存のコードに影響が出やすくなる「巨大な万能ライブラリ」が誕生してしまう。

このような状況を避けるため、HoneyDrunkという開発プロジェクトでは、共有パッケージの構造を最初から計画的に設計している。将来の拡張性やメンテナンス性を考慮し、それぞれのパッケージが明確な役割と境界を持つように整理することで、開発者が迷うことなく目的の機能を見つけ、安心してコードを修正・追加できる環境を目指している。

HoneyDrunkでは、まずシステムの基盤となる最も基本的な機能群を定義している。これらはビジネスロジックを含まず、他のすべての部品がその上に構築される「レゴブロック」のような存在だ。 例えば、「HoneyDrunk.Core」は、基本的なデータ構造、システム内で発生するイベント、共通のエラー処理など、プラットフォーム全体の根幹をなす要素をまとめている。「HoneyDrunk.Validation」は、入力されたデータが正しい形式であるかを確認するためのルールや検証機能を担当する。「HoneyDrunk.Security」は、パスワードのハッシュ化や認証トークン（JWT）の管理など、システム全体のセキュリティに関する機能を提供する。「HoneyDrunk.Caching」は、頻繁にアクセスされるデータを一時的に保存し、システムの応答速度を向上させるための仕組み（Redisやメモリキャッシュの抽象化）を扱う。「HoneyDrunk.Configuration」は、システムの設定情報を安全に管理し、利用しやすい形式で提供する（Key Vaultとの連携や型付けされた設定）役割を持つ。「HoneyDrunk.FeatureFlags」は、新機能を段階的に公開したり、特定のユーザーにのみ提供したりするための機能切り替えの仕組みを提供する。

次に、データの扱いやネットワーク通信に関するパッケージ群がある。 「HoneyDrunk.Data」は、データベースへのアクセス方法（Entity Framework Coreのパターン、DbContextのヘルパー、データベースの構造変更を行うマイグレーション機能）を標準化する。「HoneyDrunk.Storage」は、ファイルや画像を保存する場所（クラウドのBlobストレージ、S3、ローカルファイルシステムなど）に関わらず、統一された方法で扱えるように抽象化する。「HoneyDrunk.Http」は、外部のサービスとHTTP通信を行うための堅牢なクライアント（ネットワークが不安定な状況でも安定して通信するための再試行、通信間隔のばらつき、障害時の遮断といった機能）を提供する。「HoneyDrunk.RestService」は、上記Httpパッケージを基盤に、より簡潔にRESTfulなAPIと連携できるようにする。「HoneyDrunk.Grpc」は、より高速な通信プロトコルであるgRPCを利用するための契約定義とヘルパー機能を提供する。「HoneyDrunk.SignalR」は、リアルタイム通信（チャットや通知など）を実現するためのハブの契約とクライアント側のユーティリティを提供する。

特に重要なのが、「システム間のメッセージング」と「人間への通知」を明確に区別することだ。多くのプロジェクトでこの二つが混同されがちだが、HoneyDrunkでは厳密に分離している。 「HoneyDrunk.Messaging」は、サービス同士が互いに情報をやり取りするための仕組み（イベントの公開・購読、サービスバスを使ったコマンドの送信など）を扱う。これは主に機械同士のコミュニケーションだ。一方、「HoneyDrunk.Notifications」は、人間に対して情報を届けるための機能群で、さらに細分化されている。「HoneyDrunk.Notifications.Email」はメール通知、「HoneyDrunk.Notifications.Sms」はショートメッセージ（SMS）、「HoneyDrunk.Notifications.Push」はモバイルアプリやウェブプッシュ通知をそれぞれ担当する。このようにすることで、それぞれの目的と対象が明確になり、誤用や混乱を防ぐ。

システムの健全性を保つためには、その状態を常に把握できることが不可欠だ。 「HoneyDrunk.Observability」は、システムの動作状況を監視するための機能（ログ記録ライブラリSerilog、システム全体の挙動を追跡するOpenTelemetry、パフォーマンスを示すメトリクス、処理の流れを可視化するトレーシング）をまとめている。「HoneyDrunk.Testing」は、コードの品質を保証するためのテスト関連機能（モックオブジェクトのセットアップ、ウェブUIテストツールCypressのヘルパー、テストデータ、汎用テストユーティリティ）を提供する。

コマース機能についても、単に「決済」として一括りにせず、より広い視点で分割している。 多くのシステムでは「決済パッケージ」に無理やり関連機能を詰め込んでしまいがちだが、HoneyDrunkでは「HoneyDrunk.Commerce.Orders」で注文管理、「HoneyDrunk.Commerce.Payments」で決済処理、「HoneyDrunk.Commerce.Billing」で請求やサブスクリプション管理をそれぞれ独立したパッケージとして扱っている。これにより、各機能がより専門化され、柔軟な対応が可能になる。

外部サービスとの連携も、それぞれ専用のパッケージに切り出している。 「HoneyDrunk.Integrations.Streaming」はTwitch、YouTube、Kickといったストリーミングサービスとの連携機能を、「HoneyDrunk.Integrations.Media」はAniListやTMDBのようなメディア情報サービスとの連携機能を、「HoneyDrunk.Integrations.GamingPlatforms」はSteam、Epic Games、XboxなどのゲームプラットフォームAPIとの連携機能を、「HoneyDrunk.Integrations.Social」はDiscord、X（旧Twitter）、Redditといったソーシャルメディアとの連携機能をそれぞれ担当する。

さらに、運用やクライアント開発を支援するためのツールやSDKも用意されている。 「HoneyDrunk.Tooling.DevOps」は、データベースのデプロイを自動化するDACPACユーティリティ、CI/CDパイプラインのヘルパー、インフラ構築スクリプトなど、開発運用（DevOps）を効率化するツールをまとめる。「HoneyDrunk.Sdk.DotNet」は、他の.NETアプリケーションがHoneyDrunkのシステムと連携するためのSDKを提供する。将来的には「HoneyDrunk.Sdk.JavaScript」として、Next.jsやExpoのようなJavaScriptベースのクライアントアプリケーション向けSDKも開発が予定されている。

これらすべてのパッケージは、システムの中核をなす「エンジンルーム」のような存在であり、直接ユーザーが触れるものではない。実際にユーザーと対話する部分は「サテライトサイト」と呼ばれるアプリケーション群だ。 例えば、公開ウェブサイトには「Next.js」、モバイルアプリには「Expo mobile app」、管理者向けの管理画面には「Blazor admin」、ブログやドキュメントなどのマーケティングサイトには「Astro marketing site」が利用される。これらのサテライトサイトには重要なルールがあり、直接データベースにアクセスすることはなく、必ずAPIやSDKを介してシステムと通信する。これにより、各アプリケーションの責務が明確になり、セキュリティとスケーラビリティが向上する。

このように、すべてのパッケージの名前と役割を明確に定義することは、将来的な開発の戦略そのものだ。名前が狭すぎると、機能を追加したくなったときに制約になり、曖昧すぎると、結局「何でも屋」になってしまう。HoneyDrunkのプロジェクトは、明示的な名前、明確な境界線、そしてプラットフォームの大部分を書き直すことなく成長できる余地を持たせることで、正しい方法でのシステム構築を目指している。抽象化は単なる学術的な概念ではなく、大規模なシステムを長期的に運用するための重要な戦略なのだ。