コンテンツにスキップ
manj.io
検索語を入力してください

    はじめに

    ソースリポジトリ: kamae-scala

    Kamae（構え）— 備えの姿勢。

    Kamae Scalaは、サーバーサイドのScala 3ドメインコードを型で守り、レビューしやすくするための設計スタンスとガイド集である。kamae-rs や kamae-ts と同じ思想を、Scala 3のイディオム（opaque types、sealed traits、Either、エフェクト型）に落とし込んでいる。

    すべてのリファレンスを通読する必要はない。今のタスクに関係するトピックだけを開けばよい。各リファレンス末尾の レビュー観点 に、そのトピックのコードレビューで確認すべき項目がある。

    何を目指すか

    Section titled “何を目指すか”

    Kamaeが守りたいのは、次のような失敗である。

    • 文字列や数値のまま混在するドメイン概念
    • status フィールドとオプショナル列で表せてしまう無効な状態
    • throw や .get / .head に頼る想定内の失敗処理
    • API JSONやDB行をそのままドメイン型として使う境界の曖昧さ
    • ログ・メトリクス・エラーへのPII漏洩
    • 状態変更とドメインイベントの非アトミックな永続化

    Scala 3では、opaque types、value class、sealed trait / enum、検証付き apply / from ファクトリ、Either[DomainError, T] といった型機能で、実用的な範囲でこれらをコンパイル時または構築時に弾く。

    コア原則

    Section titled “コア原則”
    • 意味を型で表す — opaque types、sealed traits、enum、検証付きコンストラクタでドメイン概念をモデル化する。
    • 無効な遷移を型で封じる — ソース状態ごとに遷移メソッドや型を分け、網羅的な match で分岐を閉じる。
    • Either で失敗を明示する — ドメイン固有のエラー ADTとともに Either[DomainError, T] を使い、ドメインコードでは throw、???、unsafe .get を避ける。
    • 境界で一度パースする — 外部データはDTO / 行ケースクラスに入れてから検証付き変換でドメイン型へ変換する。
    • ユースケースは小さく配線する — ポート（trait）経由で依存を受け取り、アダプタはコンポジションルートで注入する。
    • 集約の変更はトランザクション内に — 実用的な範囲で、ユースケースごとに集約の変更を1つのトランザクション境界に収める。
    • PII とシークレットは内側に — マスキング用ラッパーの内側に置き、観測経路ではデフォルトでマスクする。
    • JNI / ネイティブは境界に閉じる — ドメインロジックからは排除し、必要なら文書化された不変条件を持つ小さな安全APIの背後に隠す。
    • 品質ゲートを揃える — scalafmt・scalafix・テスト・Scaladocをクリーンに保ち、CIをレビュー前提と一致させる。

    これらは強い既定であり、絶対ではない。既存のプロジェクト慣習と矛盾する場合は慣習に従い、ドメイン安全性に影響する逸脱は短い説明を残す。

    前提となるツールチェーン

    Section titled “前提となるツールチェーン”

    新規プロジェクトの既定は次のとおり。既存コードベースでは、まずリポジトリの慣習を確認する。

    • Scala 3.3+（ThisBuild / scalaVersion）
    • sbt 1.10+（project/build.properties）
    • Java 17以上（LTS）
    • フォーマットは scalafmt、lintは scalafix（プロジェクトで採用している場合）

    状況別の読み方

    Section titled “状況別の読み方”

    新規ドメインを設計するとき

    Section titled “新規ドメインを設計するとき”
    1. ドメインモデリング
    2. 状態遷移
    3. 境界防御 と エラーハンドリング
    4. 永続化、集約、イベント
    5. タクシー配車の例
    6. 仕上げ前に 品質ゲート

    既存コードベースへ段階的に導入するとき

    Section titled “既存コードベースへ段階的に導入するとき”
    1. 段階的導入
    2. 境界防御
    3. 永続化にORMを使う場合は ORM アダプター
    4. 移行したワークフローごとに、上記「新規ドメイン」のパスを続ける

    オブザーバビリティと PII だけ見るとき

    Section titled “オブザーバビリティと PII だけ見るとき”
    1. PII 保護
    2. ロギングとメトリクス
    3. テストのアサーションは テストデータ

    インフラ・開発環境の整備

    Section titled “インフラ・開発環境の整備”
    関心リファレンス
    ユースケース配線、DIアプリケーション配線
    Cats Effect / ZIO の選び方エフェクトシステム
    サービス間契約、HTTP / gRPCサービス境界
    ストリーム、継続クエリストリームと継続クエリ
    マクロ、deriveドメインマクロ
    JNI、ネイティブJNI / ネイティブ境界
    テスト、フィクスチャテストデータ
    プロパティベーステストプロパティベーステスト
    フォーマット、lint、品質ゲート品質ゲート
    公開 API の Scaladoc公開 API のドキュメント
    ローカル開発・ブートストラップ開発環境
    スキルリポジトリの開発スキルリポジトリの開発
    CICI セットアップ

    依存ライブラリ

    Section titled “依存ライブラリ”

    プロジェクトの build.sbt に応じて、必要なときだけ ライブラリガイド を参照する。

    用途ガイド付きライブラリ検出のみ（ローカル慣習の参考）
    エフェクトcats、ziomonix
    シリアライズcirceplay-json、json4s、upickle
    検証 / 単位refinedsquants
    PII / シークレットsecrets パターン—
    永続化doobieslick、quill、skunk
    ストリームfs2pekko-stream、zio-streams
    設定pureconfig—
    テストscalacheckmunit、scalatest、weaver

    正規の例

    Section titled “正規の例”

    新しいリファレンスに全文スニペットをコピーせず、次の定義へリンクする。

    トピック正規リファレンス
    ハッピーパスのユースケース状態遷移 — ユースケースを薄く保つ
    永続化エラーのマッピングエラーハンドリング — Either による早期リターン
    リポジトリポート永続化、集約、イベント — 責務でリポジトリを分離する
    エンドツーエンドコードタクシー配車の例
    品質ゲートのコマンド品質ゲート — ベースラインコマンド

    リファレンス一覧

    Section titled “リファレンス一覧”

    実践例

    Section titled “実践例”

    タクシー配車の例 で、opaque ID、分離した状態型、型付き遷移、ドメインイベントの流れを一通り追える。