rust-domain-boundaries

Rust のドメイン境界

このスキルを使って、Rust サービスの内部で無効な状態が生じないようにします。境界で生の入力を一度だけ解析し、検証済みの値を用途を絞ったドメイン型に格納して、検証を経ない構築を難しくします。

基本的なワークフロー

1. 生の入力との境界を特定します：HTTP ペイロード、パス／クエリパラメーター、設定ファイル、環境変数、データベースの行、キュー、CLI フラグ。
2. トランスポート DTO とドメイン型を分離します。serde で入力の形式をデシリアライズし、DTO のフィールドを検証済みのドメイン値に変換します。
3. ルールが定められた値には、プリミティブな文字列の代わりに小さな型を使います。たとえば、メールアドレス、ユーザー名、パスワード、購読者名、スラッグ、テナント ID、冪等性キー、金額や期間に相当する値です。
4. ドメイン型のフィールドは非公開にし、スマートコンストラクターを用意します。検証を経ない pub フィールドや、失敗する可能性のある変換に対する impl From<String> は避けます。
5. 内部の詳細を漏らさず、有用な HTTP レスポンスに対応付けられる型付きの検証エラーを返します。
6. データベースや外部 API へのマッピングは明示的に行います。永続化やシリアライズの最終境界で、生の文字列に変換します。
7. 不変条件を直接テストします。有効な例、不正な入力、境界の長さ、正規化ルール、往復変換を網羅します。

型設計のルール

• 失敗する可能性のある解析には、TryFrom<String、TryFrom<&str>、または FromStr を優先します。
• プロファイリングで借用が必要だと証明されない限り、値は所有する形で保持します。
• 読み取り専用の公開には、AsRef<str> または名前付きアクセサーを実装します。
• フォーマットされた値をログ、エラー、UI に安全に表示できる場合に限り、Display を実装します。
• デバッグ出力が秘匿化されない限り、秘密情報を含む値への Debug の導出は避けます。
• トリム、小文字化、Unicode の扱い、正規化など、正規化の動作がテストで明確になるようにします。

リクエスト境界のパターン

リクエストの形式にデシリアライズしてから、コマンドを構築します：

#[derive(serde::Deserialize)]
pub struct SubscribeRequest {
    email: String,
    name: String,
}

pub struct SubscribeCommand {
    pub email: EmailAddress,
    pub name: SubscriberName,
}

impl TryFrom<SubscribeRequest> for SubscribeCommand {
    type Error = SubscribeValidationError;

    fn try_from(value: SubscribeRequest) -> Result<Self, Self::Error> {
        Ok(Self {
            email: EmailAddress::parse(value.email)?,
            name: SubscriberName::parse(value.name)?,
        })
    }
}

ハンドラーは、ビジネスロジックやデータベースのコードを実行する前に、無効な入力を拒否する必要があります。検証にデータベースの状態が必要な場合は、純粋な解析と一意性チェックや認可チェックを分離します。

テスト

不変条件に多くのエッジケースがある場合、または AI エージェントが例のみのテストでは無効な入力を見逃しそうな場合は、references/property-testing.md を読みます。

新しいドメイン型に必要な最低限のテスト：

• 現実的な有効値を受け入れる。
• 空の入力と空白のみの入力を拒否する。
• ストレージや製品ルールで上限が定められている場合、長すぎる入力を拒否する。
• 書式違反を拒否する。
• テストで文書化したとおりに値を保持または正規化する。
• その型が境界をまたぐ場合、serde または SQL マッピングによる往復変換を確認する。

参照ファイル

• references/newtype-patterns.md：Rust のニュータイプにおけるコンストラクター、トレイト、serde、永続化のパターン。
• references/property-testing.md：パーサーとドメインコンストラクター向けのプロパティベーステストの戦略。