コンテンツにスキップ

実装ガイドライン

「なぜこの設計か」はADRを見れば済むので書かない。ここに書くのは「このコードベースで具体的にどう書くか」だけ。

  • Java 25 / Spring Boot 4。ビルドは ./gradlew(Mavenは使わない)。
  • 層構成とパッケージ責務は architecture.md と各 package-info.java を読む。
  • 全体 @NullMarked(JSpecify)。null可の箇所だけ @Nullable。Javadocは ///(Markdownコメント)。
  • 依存方向は ArchitectureTest(ArchUnit)が機械的に強制する。
Handler (生成 XxxApi を implements)
→ UseCase.execute(...) // usecase
→ TransactionManager.execute(() -> ...) // トランザクション境界
→ Repository(port) // → infra 実装(Mapper + 行レコード変換)
→ ResponseMapper.from(domainObject) // ドメイン → 生成DTO

例外はドメイン例外として投げ、GlobalExceptionHandler がHTTP(Problem Details)へ変換する。 ハンドラー・ユースケースでHTTPステータスを直接組み立てない。

新しいドメイン/機能を起こす手順

Section titled “新しいドメイン/機能を起こす手順”
  1. ドメインモデル: 集約・値オブジェクトを domain.model に作る。生成時に不変条件を検証し、不正値を存在させない。状態を持つならsealed interface(下記「状態を持つ集約」)。 複数の集約・値オブジェクトにまたがるビジネスルールは domain.service に置く。
  2. ポート: 永続化や外部I/Oのインターフェースを domain.port に定義する。戻り値がないとき Optional、異常時の例外をJavadocで契約化する(see: TransactionManager)。
  3. ユースケース: usecase に1ユースケース1クラス(execute)。Portの呼び出し順序と結果の受け渡しに徹し、ビジネスルールの判定・計算は書かない。
  4. インフラ: Mapper インターフェースと mapper/*.xml、DB行レコードとドメインの変換を実装する。DataAccessException を RepositoryException にラップする。
  5. OpenAPI(スキーマファースト): docs/openapi/*.yaml にエンドポイントとスキーマを定義し、./gradlew openApiSyncToSrc で generated/(XxxApi インターフェース + DTO)を生成する(ADR-010)。生成コードは手編集しない。
  6. ハンドラー: 生成された XxxApi を implements する @RestController。入力は生成DTO、出力はMapperで生成DTOへ変換する(handler.response)。検証は後述。エラーは投げるだけ。
  7. DI登録: config/AppConfig に @Bean を追加(自動スキャンは使わない)。
  8. テスト: ユースケース単体(Mockito)と統合(Testcontainers)。

ドメインサービスとビジネスロジックの配置

Section titled “ドメインサービスとビジネスロジックの配置”
処理配置先
単一集約の状態遷移・値の導出domain.model のメソッド
主体となる集約があり、他方を引数にできる操作主体側エンティティのメソッド
対等な複数オブジェクトの判定・計算domain.service
ドメインオブジェクトに属さない共通の値変換・表示domain.common

ユースケースにはビジネスルールを書かない(ADR-013)。ただし、存在確認や空判定などの軽微な分岐はよい。 ユースケース内での複数のドメインオブジェクトを比較する if や for は、domain.service への切り出しを検討する。

// 疑うべき例(判定条件が複数のドメインオブジェクトを跨ぐ)
for (var other : candidates) {
if (other.altitude().overlaps(plan.altitude()) && other.period().overlaps(plan.period())) {
throw new ConflictException(...);
}
}
// 是正後(判定をdomain.serviceへ切り出す。UseCaseに残るif文は判定結果を見るだけ)
if (overlapChecker.hasConflict(plan, candidates)) {
throw new ConflictException(...);
}

他のBeanに依存しないドメインサービスは static メソッド、依存するものはコンストラクタ注入のクラスにする。 後者は AppConfig に登録し、Springアノテーションを付けない。

public final class OverlapChecker {
private OverlapChecker() {}
public static boolean overlaps(FlightPlan a, FlightPlan b) { ... }
}

結果を真偽や既存の値オブジェクトで表せない場合は型を作る。複数の値なら record、種類ごとに値が異なるなら sealed interface を使う。

ユースケース設計とトランザクション境界

Section titled “ユースケース設計とトランザクション境界”

既定は1UseCase = 1集約 = 1トランザクション(ADR-013)。@Transactional は使わず TransactionManager.execute で境界を引く。

return transactionManager.execute(() -> {
var entity = repository.findById(id).orElseThrow(() -> new NotFoundException(id));
return repository.save(entity.doSomething());
});

正常終了でコミット、例外が伝播すればロールバック(ドメイン例外はすべて非チェック例外なので対象)。

トランザクション属性の上書き(分離レベル・readOnly)

Section titled “トランザクション属性の上書き(分離レベル・readOnly)”

既定はグローバル設定(app.transaction.* = TransactionProperties)。特定ユースケースだけ変えたいときは execute に TransactionOptions を渡す(TransactionOptions・IsolationLevel は domain.port、Spring非依存)。

まず行ロックで足りないかを問う。特定行の排他なら findByIdForUpdate(ADR-019)で済む。範囲・集計の一貫読み取り(ファントム回避)が要るときだけ分離レベルを上げる。グローバル設定は無関係なユースケースまで巻き込むため、per-callで上書きする。

// 集計の一貫読み取りで REPEATABLE_READ にしたいユースケースだけ上書き(グローバルは変えない)
return transactionManager.execute(
TransactionOptions.withIsolation(IsolationLevel.REPEATABLE_READ),
() -> aggregateRepository.summarize(cmd));
// 読み取り専用の最適化
return transactionManager.execute(
TransactionOptions.forReadOnly(),
() -> reportRepository.find(cmd));

IsolationLevel.DEFAULT とタイムアウト:0はグローバル既定にフォールバックする。

状態を持つ集約(パターン例)

Section titled “状態を持つ集約(パターン例)”

ステートマシンならsealed interfaceで状態ごとに型を分け、遷移メソッドをその状態にだけ置く(不正遷移をコンパイルで防ぐ)。取得→検証→保存の定型は共通ヘルパーに集約し、findByIdForUpdate(行ロック、ADR-019)で取得する。 すべての集約がステートマシンとは限らない。状態を持たない集約はこのパターンを使わない。

複合ユースケース(複数集約をまたぐ)— ADR-021

Section titled “複合ユースケース(複数集約をまたぐ)— ADR-021”

複数集約を更新したくなったら、「整合性の強さ」と「境界」で判断する(方針は1つに絞らずケースバイケース。判断軸の根拠はADR-021)。

(a) 同一DBで強整合が必須 → 1つの execute で複数リポジトリを束ねる「複合ユースケース」として識別する。

// 理由: 計画の承認と機体の割り当ては同時に成立すべき不変条件(二重割り当て禁止)
return transactionManager.execute(() -> {
// ロック取得順序を一定(型/ID 順)にしてデッドロックを避ける(ADR-019)
var plan = planRepository.findByIdForUpdate(cmd.planId()).orElseThrow(...);
var aircraft = aircraftRepository.findByIdForUpdate(cmd.aircraftId()).orElseThrow(...);
var approved = plan.approveWith(aircraft); // またがる不変条件をここで満たす
planRepository.save(approved);
aircraftRepository.save(aircraft.assignTo(approved.id()));
return approved;
});

複合ユースケースには「なぜ1トランザクションが必要か(どの不変条件か)」をコメントで書く。理由のない巨大トランザクションは避ける。

(b) 別サービス/別DB、または即時整合が不要 → 結果整合にする。集約ごとにローカルトランザクションでコミットし、ドメインイベントで伝播する。

return transactionManager.execute(() -> {
var saved = planRepository.save(Plan.submit(cmd));
eventPublisher.publish(new PlanSubmitted(saved.id()));
return saved;
});

ポートを domain.port に定義し、実体はOutbox(同一トランザクションでイベント行も書き、別プロセスが配信)で実装する(ADR-006)。 結果整合が要るサービスで追加する。境界をまたぐ更新に分散トランザクション(2PC)は使わない。

判断の早見:

  • またがる不変条件を即時に満たす必要があり、同一DB → (a) 複合ユースケース(1Tx)
  • それ以外(別DB/サービス、または最終的整合で十分) → (b) 結果整合(イベント+Outbox)

外部連携を伴う状態遷移 — ADR-022

Section titled “外部連携を伴う状態遷移 — ADR-022”

状態遷移が外部システムの成否に依存する場合(「外部へ連絡できたら遷移する」)、 トランザクションの中で外部I/Oを呼ばない(ロック長期保持・dual write・ロールバック不能)。連携の向きで分ける。

DB確定 → 外部通知(一方向): 状態遷移とイベント行を同一トランザクションでコミットし、Outboxで外部へ送る(ADR-006)。

外部の成否 → 遷移(同期依存): ステートマシンに「外部待ち」の中間状態を組み込み、3段で書く。

// 遷移1: 申請中へ(ローカルTx、ここでロック)
transactionManager.execute(() -> {
var plan = planRepository.findByIdForUpdate(id).orElseThrow(...);
return planRepository.save(plan.requestApproval()); // → Pending
});
// 外部呼び出し: トランザクション外。冪等キー・リトライ・タイムアウト前提(ADR-020)
var result = externalApprovalClient.submit(id, idempotencyKey);
// 遷移2: 応答で確定(別Tx、再取得。並行で状態が変わりうる)
transactionManager.execute(() -> {
var plan = planRepository.findByIdForUpdate(id).orElseThrow(...);
if (!(plan instanceof Plan.Pending p)) throw new InvalidTransitionException(...);
return planRepository.save(result.accepted() ? p.confirm() : p.fail());
});

外部クライアントは domain.port にインターフェース(例 ExternalApprovalClient)として定義し、実体はinfraに置く。 呼び出しはトランザクション外で行う。非同期コールバックの場合、遷移2は別のPrimary Adapter (コールバック受信ハンドラー)が相関IDで対象を引いて行う(本リポジトリでは未実装)。

判断: 外部の応答を遷移条件にするなら中間状態+Saga。単なる通知ならOutbox。

検証の配置(OAS制約 / 構文parse / 意味的parse)

Section titled “検証の配置(OAS制約 / 構文parse / 意味的parse)”

入力検証はOAS(スキーマファースト・ADR-010)を起点に3段で考える。生成DTOに手で制約やparseを足さない。

  • 単純な制約(必須・長さ・範囲・正規表現)→ OASに書く。生成DTOに @NotNull・@Size・@Pattern などが付き、ハンドラー引数の @Valid で効く。違反は GlobalExceptionHandler が422(errors 付き)に変換する。
    title:
    type: string
    minLength: 1
    maxLength: 255
    pattern: '.*\S.*' # 空白のみを拒否
  • 構文parse(String → LocalDate・UUID などの基本型)→ OASの format(date・uuid)で生成DTOがその型を持ち、Jacksonがparseする。形式不正はパース失敗 = 400(GlobalExceptionHandler が HttpMessageNotReadableException・MethodArgumentTypeMismatchException を変換)。
  • 意味的parse(基本型 → ドメイン値オブジェクト)→ ハンドラーで変換する。値オブジェクトは生成時に不変条件を検証し、不正値を存在させない。
    var todo = createXxxUseCase.execute(req.getName(), Xxx.from(req.getValue()));

API経路以外(バッチ・メッセージ受信など)で生文字列を受ける場合は ParseResult でparse結果を扱う。

var result = Xxx.parse(raw);
if (result instanceof ParseResult.Err<Xxx>(var msg)) {
throw ValidationProblemException.of("xxx", msg); // 422
}
return result.unwrap();

handler.problem(RFC9457基盤)と GlobalExceptionHandler は土台として残し、再利用する。

  1. ドメイン例外を作る。業務ルール違反は BusinessRuleException を継承する。専用ハンドラーが無くても GlobalExceptionHandler のフォールバックで422になる。
  2. 個別のステータス・国際化メッセージが要るなら GlobalExceptionHandler に @ExceptionHandler を足し、buildProblem(...) ヘルパーを使う(ProblemDetail を自分で組み立てない)。
  3. ProblemTypes にtype URI定数、messages.properties に problem.title.* / error.* キーを追加する。
  4. インフラ障害は業務エラーではない。RepositoryException(技術例外、500)として扱い、DataAccessException をラップする。

自動スキャン(@Component/@Service)は使わない。ドメイン・ユースケースにSpringアノテーションを付けない。AppConfig に @Bean を書く(依存グラフがそこに集約される)。 Web層の部品(@RestController・@RestControllerAdvice・Filter・@Configuration)だけはSpringのライフサイクルに乗せるためアノテーションで登録する。

  • ドメイン ⇔ DB行の変換は実装クラスに閉じる。ドメインにDB都合(行レコード・SQL)を漏らさない。
  • 作成(INSERT)と更新(UPDATE)をポートで分ける場合がある(ADR-020)。
  • UPDATE ... RETURNING が0行なら(並行削除など)Optional.empty() を NotFoundException にする。
  • SQLは mapper/*.xml。パラメータは必ず #{}。文字列結合は禁止。
  • 共有するSELECT本体は <sql> フラグメントで重複を避ける(参照用とロック用 FOR UPDATE など)。

IAMドメイン(docs/iam/design/)でRLSと認証系統を実装済みである。仕組みの全体像(データモデル・認証フロー・RLSとの関係を図解したもの)はIAMオンボーディングガイドにある。ここに書くのは、この土台を別ドメインで使うときの拡張手順だけである。

やりたいことに応じて読む節を選ぶ。

やりたいこと読む節
組織所有のテーブルを新しく作る「組織所有テーブルを追加する場合」
ビュー・マテリアライズドビュー・外部テーブルを作る「ビュー類を追加する場合」
既存パスに認証を足す(テーブルは増やさない)「APIの認証を有効化する」
通常のユーザー認証と別の認証方式を足す(稀なケース)「認証系統を追加する」

組織所有テーブルを追加する場合

Section titled “組織所有テーブルを追加する場合”
  1. db/schema/<feature>.sqlにテーブルを作る。organization_id UUID NOT NULLを持たせ、iam.organizationsへの外部キーを張る
  2. organization_idにインデックスを張る。RLSは全クエリに条件を暗黙に付けるため、無いと全件走査になる
  3. 新しいスキーマにテーブルを作る場合は、db/init/01_roles.sqlの許可リストにそのスキーマを足す。許可リストに無いスキーマにはutm_appへ権限が付かず、RLSに届く前にpermission deniedになる。publicは許可リストに入れない(書き込み権限があるとPostGISのspatial_ref_sysを壊せる)
  4. db/init/02_rls.sqlにポリシーを足す。ENABLEとFORCEの両方、USINGとWITH CHECKの両方を書く。条件はorganization_id = (SELECT iam.current_org_id())とし、current_settingを直接書かない。関数はGUCが未設定か空文字なら失敗する(fail-closed)。(SELECT …)で包むのは、行ごとではなく文ごとに1回だけ評価させるため。関数の置き場所と書き方はdb/README.md「関数の置き場所と書き方」にある
  5. db/schema/iam.sqlのrls_reference_examplesとRlsReferenceIntegrationTestをコピー元にする
  6. CIで常時実行されるRlsCoverageTestが、アプリの全テーブル(システムスキーマと拡張のテーブルを除く)を検査する。テーブルコメントに宣言の無いテーブルには、RLSのENABLEとFORCE、ポリシーの存在、utm_appに効くPERMISSIVEなポリシーがUSINGとWITH CHECKの両方で承認済みの関数(iam.current_org_id()など)を呼ぶこと、を課す。関数を呼ぶかしか見ないので、organization_idで絞れているかは手順5のテストで確かめる。organization_id列を持つテーブルには、宣言の有無によらず、それが索引の先頭列であることも課す。RLSを張らないテーブルは、COMMENT ON TABLEの末尾で宣言する。後で張るなら@rls-pending、全組織が共有するデータのように設計上かけないなら@rls-exempt <理由>と書く。親テーブルを通じてだけ組織に属する子テーブルも自分で宣言する。宣言したテーブルにRLSかポリシーがあるとテストが失敗するので、RLSを張るときは宣言を外す。宣言はMigrationScopeTestの項目になるので、migration-baseline.txtも更新する
  7. 認証の有効化と同時に行う。 SecurityPaths.MIGRATINGにいるパスはNoSessionで動くためGUCが張られず、そのテーブルに触ればエラーになる。テーブルをRLS対象にするPRで、そのパスをPROTECTEDへ移す(手順は下記「APIの認証を有効化する」)
  8. 挿入時のorganization_idは、列にDEFAULT iam.current_org_id()を付けてDBに埋めさせる。アプリは組織を知らなくてよく、ドメインもorganization_idを持たなくてよい。他組織の値を明示したINSERTや、既存行を他組織へ書き換えるUPDATEは、WITH CHECKが拒否する。組織文脈が無いときは、iam.current_org_id()が失敗して静かに別組織の行にはならない。iam.rls_reference_examplesがこの形で、RlsReferenceIntegrationTestのT2cが確かめている
  9. UUID主キーはid UUID NOT NULL DEFAULT uuidv7()にする。アプリ側で採番しない。DBのuuidv7()はミリ秒タイムスタンプ順に採番するため、INSERTからid列を省けばよく、UUID.randomUUID()(v4、時系列に並ばない)を書く必要が無い
  10. 外部に露出するIDでは作成時刻の漏洩に注意する。UUIDv7はミリ秒精度のタイムスタンプを含むため、APIが返すIDからその行の作成時刻を誰でも復元できる。IAMのユーザーIDでは許容したが、運用時刻が機微な対象では、露出するIDをv4にするか内部IDと分けるかを個別に判断する

ビューは既定で所有者の権限で元のテーブルを読み、RLSを迂回する。

  1. ビューはdb/schema/<feature>.sqlにCREATE VIEW <ビュー> WITH (security_invoker = true) AS ...で作る。utm_appの権限で読むため、元のテーブルのRLSが効く(元のテーブルが@rls-pendingなら分離は無い)。このビューには宣言を書かない。書くとRlsCoverageTestが失敗する
  2. security_invokerを付けられないビュー、マテリアライズドビュー、外部テーブルには、元のテーブルのRLSが効かない。コメント(COMMENT ON VIEWなど)の末尾で@rls-exempt <理由>か@rls-pendingを宣言する。宣言の無いビューはdb/init/がsecurity_invokerに変えるので、所有者の権限で読ませるビューには宣言が要る(理由はdb/README.md「ビュー」)。マテリアライズドビューと外部テーブルは、宣言が無いとRlsCoverageTestが失敗する。単純なビューは書き込みも元のテーブルへ通すので、@rls-exemptの理由は読み取りと書き込みの両方について考える。置き場所はdb/README.md「ビュー」に従う。宣言はMigrationScopeTestの項目になるので、migration-baseline.txtも更新する

MIGRATINGからPROTECTEDへ移すときの手順。上記「組織所有テーブルを追加する場合」の手順7から参照されるが、単独でも使う(既存パスに認証を足すだけでテーブルは増やさない場合)。

  1. SecurityPaths.MIGRATINGから自分のパスを削り、PROTECTEDに足す
  2. そのパスの統合テストにTestJwtSupport.tokenFor(AUDIENCE_USER, userId)を付与する
  3. ユースケースのexecuteの引数にSessionContextを足し、transactionManager.execute(...)をtransactionManager.execute(context, ...)に替える
  4. ハンドラーがユースケースへSessionContextを渡す。組織のデータを扱うならsessionContextFactory.currentOrganizationScope()、組織を対象にしない(ログイン中のユーザー自身の情報だけを扱う)ならsessionContextFactory.currentUserScope()にする
  5. SecurityPathCoverageTestが緑であることを確認する

認証系統を追加する(稀なケース)

Section titled “認証系統を追加する(稀なケース)”

通常のユーザー認証とは別の認証方式を足すケース。外部USS(/uss/v1/**、対向USSからのclient_credentials通信、別issuer)を例にする。

  1. SecurityConfigに@Order(20)のチェーンを足す。securityMatcher("/uss/v1/**")
  2. jwk-set-uriプロパティは使えない。単一のJwtDecoderしか組み立てないため、NimbusJwtDecoder.withJwkSetUri(...)を明示構築し.jwt(j -> j.decoder(...))で渡す
  3. 判定軸はaudではなくscope。JwtGrantedAuthoritiesConverterの既定(SCOPE_接頭辞)を使う
  4. SessionContextにrecordでpermitsを足す(利用者が存在しないためOrganizationMemberにはならない)。RlsSessionInitializer.initializeSessionのswitchが非網羅になりコンパイルエラーになる。これは意図した設計で、GUCの張り方を決めるべき箇所が漏れなく列挙される。必要ならSessionContextFactoryに組み立て経路を足す
  5. SecurityPaths.MIGRATINGから/uss/v1/**を外す

設計の背景や却下した代替案はIAM Phase 1の最小設計を参照する。

IdPのアクセストークンを検証し、内部JWTへ置き換えてSpringへ転送するリバースプロキシをauth-service/に置いている。認証フロー全体はIAMオンボーディングガイド、設計の理由はIAM Phase 1実装仕様(spec 2)にある。

ターミナルウィンドウ
docker compose --profile auth up -d --build --wait
mise run db:seed
mise run e2e:auth

profileを付けないdocker compose upの挙動は変わらない。8080へ直接アクセスする経路もそのまま残っている。auth-serviceは前段の追加であって置き換えではない。

変更するのはSpringのSecurityPathsだけである。auth-serviceは認可のためのパス一覧を持たないので、MIGRATINGからPROTECTEDへ移してもauth-service側に変更は要らない。

ターミナルウィンドウ
mise run auth:fmt # golangci-lint fmt(gofmtとgoimports)
mise run auth:lint # golangci-lint run。整形漏れも--diffで落ちる
mise run auth:build # auth:lintに依存する。Lintを通さないとビルドしない
mise run auth:cover # go test -race + カバレッジ判定。CIはauth:testでなくこちらを見る
mise run auth:generate # openapi_iam_internal.yamlを変えたら再生成する。CIがドリフトを検査する
mise run auth:licenses # go.modを変えたら実行する。忘れるとCIのauth:licenses:checkが落ちる

audとissの文字列をGoやJavaのソースへ直接書かない。両者はcompose.yamlの単一の変数から注入している。2箇所に書くと、片方だけ変えても両方のテストが緑のまま実行時に401になる。

  • ユースケース単体: Mockitoでリポジトリをモック。トランザクションはNoopTransactionManager(src/testのusecaseパッケージにあるテストダブル)を渡す。actionをそのまま実行し、渡されたTransactionOptionsを記録する。
    var useCase = new XxxUseCase(repository, new NoopTransactionManager());
    ロックして取得する処理は findByIdForUpdate をスタブする(findById ではない)。
  • マッパー SQL(BoundSql): DB接続なしでSQLテキストの性質を検証する(mybatis-config-test.xml から SqlSessionFactory を組み、MappedStatement#getBoundSql を見る。サンプル: AssetMapperBoundSqlTest)。 対象は <if> による句の付与・省略、ON CONFLICT・FOR UPDATE の有無、UPDATE対象列の範囲。 いずれも「機能テストが通っていても検出できない」もの。例えば FOR UPDATE の付け忘れは、単一スレッドで動く後述のDB往復テストでは落ちない。 新しいマッパーXMLを追加したら src/test/resources/mybatis-config-test.xml の <mappers> にも登録すること。
  • マッパー SQL(DB往復): Repository実装を実際のPostgreSQLに対して検証する(@SpringBootTest(webEnvironment = NONE) + TestcontainersConfiguration + @Transactional。サンプル: AssetRepositoryImplIntegrationTest)。 対象は 実スキーマとの整合。列名・型の誤り、resultMap の <constructor> 引数順のズレ、ENUMキャストの妥当性は、BoundSqlの文字列検査では検出できない(ADR-015が挙げるMyBatisのデメリット「Column 名・型ミスは実行時エラーになる」への対策)。 TestcontainersConfiguration が db/ と db/init-container.sh をコンテナへコピーし、compose と同じ初期化経路でスキーマを作るため、本物のDDLに対して実行される(テスト用にDDLを複製しない)。
  • 統合テスト: @SpringBootTest(webEnvironment = RANDOM_PORT) + Testcontainers + RestClient。エラー応答は onStatus(HttpStatusCode::isError, (req,res)->{}) で受けて Problem Details を検証する。 内部API用のTomcatコネクタは既定で固定ポート(8082)を使うため、RANDOM_PORT のテストクラスを新しく足すと、既存のコンテキストと同じ内部ポートを取り合って BindException になる。WithEphemeralInternalApiPort を実装して内部ポートをテストごとに分ける。
  • アーキテクチャ: ArchitectureTest(ArchUnit)が層依存を強制する。層・パッケージを足したらルールも確認する。

やってはいけないこと(ArchUnitと規約で弾かれる)

Section titled “やってはいけないこと(ArchUnitと規約で弾かれる)”
  • domain からSpring / MyBatis / infrastructure を参照する。
  • usecase でHTTPの関心事(HttpStatus・ResponseEntity・ヘッダー)を扱う。
  • @Transactional を使う(TransactionManager を使う)。
  • ドメイン・ユースケースに @Component/@Service を付けて自動スキャンさせる。
  • ProblemDetail を各所で手組みする(GlobalExceptionHandler の buildProblem に集約)。
  • 状態遷移・複合更新で findById(ロックなし)を使う(findByIdForUpdate)。
  • ドメイン例外にHTTPステータスを持たせる(変換はhandlerの責務)。
  • 理由のない巨大トランザクション(複数集約を漫然と1Txに束ねる。ADR-021の判断軸で必要性を示す)。
  • トランザクションの中で外部I/O(HTTP・メッセージングなど)を呼ぶ(ロック長期保持・dual write。ADR-022。外部呼び出しはTx外へ)。
  • ユースケースに値・状態の妥当性判定や複数ドメインオブジェクトを跨ぐ判定・計算を直接書く(domain/domain.serviceに書く。単純な存在確認・空判定などの軽微な分岐は対象外)。

Observability(コードを足すときの規範)

Section titled “Observability(コードを足すときの規範)”

spanは境界で自動的に付く。計装は handler・infrastructure・config にのみ置き、usecase・domain は計装ゼロで純粋に保つ(ArchUnitが io.micrometer../io.opentelemetry.. 依存を禁止)。新しくコードを足すとき、通常は何もしなくてよい。

足すものやること
handler(HTTPエンドポイント)なし(HTTPサーバのspanは自動)
infrastructureのDBアクセスなし(SQL spanはdatasource-micrometerが自動)
usecase計装コードを書かない(io.micrometer/io.opentelemetry をimportしない)。純粋に保つ
外部I/O(HTTPクライアント・メッセージングなど)自動計装は付かない。必要なら infrastructure 側で ObservationRegistry を使いObservationを張る(usecase/domain には入れない)

内訳をもっと見たくなったときの拡張ポイント:

  • usecase span: config/AppConfig の各UseCaseの @Bean を ObservationRegistry を使ったデコレータで包む。usecaseクラスは純粋なまま、観測の関心事をconfigに閉じる。
  • mapper/repositoryメソッド名のspan: infrastructure の TodoRepositoryImpl の各メソッドを手動Observationで包み、どのrepository操作がSQLを発行したかをspan名に出す。

トレース送信先(OTLP)の設定やローカルでの確認方法はREADME「トレースの確認」を参照(実装ではなく運用設定)。

ターミナルウィンドウ
./gradlew spotlessApply # 整形
./gradlew check # テスト・spotless・NullAway・ArchUnit
mise run lint # OpenAPI / データモデル文書 / SQL / GitHub Actions / secrets / spotless
# ※ データモデル文書の検査は npm ci 済みであることが前提(github-slugger を使う)
# pre-commit(lefthook)の lint-datamodel も同じ前提
  • messages.properties のキー追加忘れ、OpenAPIと実装の不一致に注意する。
  • 長い行(とくにコメント内の英数字列挙)はspotlessが折り返しでMarkdownコメントを壊すことがある。整形後に確認する。

本文中の ADR-0xx は組織共通ADRの番号を指す。ADR本体の場所はarchitecture.mdの関連ADRを参照。