18 KiB
18 KiB
バックエンド専門知識
ヘキサゴナルアーキテクチャ（ポートとアダプター）
依存方向は外側から内側へ。逆方向の依存は禁止。
adapter（外部） → application（ユースケース） → domain（ビジネスロジック）
ディレクトリ構成:
{domain-name}/
├── domain/ # ドメイン層（フレームワーク非依存）
│ ├── model/
│ │ └── aggregate/ # 集約ルート、値オブジェクト
│ └── service/ # ドメインサービス
├── application/ # アプリケーション層（ユースケース）
│ ├── usecase/ # オーケストレーション
│ └── query/ # クエリハンドラ
├── adapter/ # アダプター層（外部接続）
│ ├── inbound/ # 入力アダプター
│ │ └── rest/ # REST Controller, Request/Response DTO
│ └── outbound/ # 出力アダプター
│ └── persistence/ # Entity, Repository実装
└── api/ # 公開インターフェース（他ドメインから参照可能）
└── events/ # ドメインイベント
各層の責務:
| 層 | 責務 | 依存してよいもの | 依存してはいけないもの |
|---|---|---|---|
| domain | ビジネスロジック、不変条件 | 標準ライブラリのみ | フレームワーク、DB、外部API |
| application | ユースケースのオーケストレーション | domain | adapter の具体実装 |
| adapter/inbound | HTTPリクエスト受信、DTO変換 | application, domain | outbound adapter |
| adapter/outbound | DB永続化、外部API呼び出し | domain（インターフェース） | application |
// CORRECT - ドメイン層はフレームワーク非依存
data class Order(val orderId: String, val status: OrderStatus) {
fun confirm(confirmedBy: String): OrderConfirmedEvent {
require(status == OrderStatus.PENDING)
return OrderConfirmedEvent(orderId, confirmedBy)
}
}
// WRONG - ドメイン層にSpringアノテーション
@Entity
data class Order(
@Id val orderId: String,
@Enumerated(EnumType.STRING) val status: OrderStatus
) {
fun confirm(confirmedBy: String) { ... }
}
| 基準 | 判定 |
|---|---|
| ドメイン層にフレームワーク依存（@Entity, @Component等） | REJECT |
| Controller から Repository を直接参照 | REJECT。UseCase層を経由 |
| ドメイン層から外向きの依存（DB, HTTP等） | REJECT |
| adapter 間の直接依存（inbound → outbound） | REJECT |
API層設計（Controller）
Controller は薄く保つ。リクエスト受信 → UseCase委譲 → レスポンス返却のみ。
// CORRECT - Controller は薄い
@RestController
@RequestMapping("/api/orders")
class OrdersController(
private val placeOrderUseCase: PlaceOrderUseCase,
private val queryGateway: QueryGateway
) {
// Command: 状態変更
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
fun post(@Valid @RequestBody request: OrderPostRequest): OrderPostResponse {
val output = placeOrderUseCase.execute(request.toInput())
return OrderPostResponse(output.orderId)
}
// Query: 参照
@GetMapping("/{id}")
fun get(@PathVariable id: String): ResponseEntity<OrderGetResponse> {
val detail = queryGateway.query(FindOrderQuery(id), OrderDetail::class.java).join()
?: return ResponseEntity.notFound().build()
return ResponseEntity.ok(OrderGetResponse.from(detail))
}
}
// WRONG - Controller にビジネスロジック
@PostMapping
fun post(@RequestBody request: OrderPostRequest): ResponseEntity<Any> {
// バリデーション、在庫チェック、計算... Controller に書いてはいけない
val stock = inventoryRepository.findByProductId(request.productId)
if (stock.quantity < request.quantity) {
return ResponseEntity.badRequest().body("在庫不足")
}
val total = request.quantity * request.unitPrice * 1.1 // 税計算
orderRepository.save(OrderEntity(...))
return ResponseEntity.ok(...)
}
Request/Response DTO 設計
Request と Response は別の型として定義する。ドメインモデルをそのままAPIに露出しない。
// Request: バリデーションアノテーション + init ブロック
data class OrderPostRequest(
@field:NotBlank val customerId: String,
@field:NotNull val items: List<OrderItemRequest>
) {
init {
require(items.isNotEmpty()) { "注文には1つ以上の商品が必要です" }
}
fun toInput() = PlaceOrderInput(customerId = customerId, items = items.map { it.toItem() })
}
// Response: ファクトリメソッド from() で変換
data class OrderGetResponse(
val orderId: String,
val status: String,
val customerName: String
) {
companion object {
fun from(detail: OrderDetail) = OrderGetResponse(
orderId = detail.orderId,
status = detail.status.name,
customerName = detail.customerName
)
}
}
| 基準 | 判定 |
|---|---|
| ドメインモデルをそのままレスポンスに返す | REJECT |
| Request DTOにビジネスロジック | REJECT。バリデーションのみ許容 |
| Response DTOにドメインロジック（計算等） | REJECT |
| Request/Responseが同一の型 | REJECT |
RESTful なアクション設計
状態遷移は動詞をサブリソースとして表現する。
POST /api/orders → 注文作成
GET /api/orders/{id} → 注文取得
GET /api/orders → 注文一覧
POST /api/orders/{id}/approve → 承認（状態遷移）
POST /api/orders/{id}/cancel → キャンセル（状態遷移）
| 基準 | 判定 |
|---|---|
| PUT/PATCH でドメイン操作（approve, cancel等） | REJECT。POST + 動詞サブリソース |
| 1つのエンドポイントで複数の操作を分岐 | REJECT。操作ごとにエンドポイントを分ける |
| DELETE で論理削除 | REJECT。POST + cancel 等の明示的操作 |
バリデーション戦略
バリデーションは層ごとに役割が異なる。すべてを1箇所に集めない。
| 層 | 責務 | 手段 | 例 |
|---|---|---|---|
| API層 | 構造的バリデーション | @NotBlank, init ブロック |
必須項目、型、フォーマット |
| UseCase層 | ビジネスルール検証 | Read Modelへの問い合わせ | 重複チェック、前提条件の存在確認 |
| ドメイン層 | 状態遷移の不変条件 | require |
「PENDINGでないと承認できない」 |
// API層: 「入力の形が正しいか」
data class OrderPostRequest(
@field:NotBlank val customerId: String,
val from: LocalDateTime,
val to: LocalDateTime
) {
init {
require(!to.isBefore(from)) { "終了日時は開始日時以降でなければなりません" }
}
}
// UseCase層: 「ビジネス的に許可されるか」（Read Model参照）
fun execute(input: PlaceOrderInput) {
customerRepository.findById(input.customerId)
?: throw CustomerNotFoundException("顧客が存在しません")
validateNoOverlapping(input) // 重複チェック
commandGateway.send(buildCommand(input))
}
// ドメイン層: 「今の状態でこの操作は許されるか」
fun confirm(confirmedBy: String): OrderConfirmedEvent {
require(status == OrderStatus.PENDING) { "確定できる状態ではありません" }
return OrderConfirmedEvent(orderId, confirmedBy)
}
| 基準 | 判定 |
|---|---|
| ドメインの状態遷移ルールがAPI層にある | REJECT |
| ビジネスルール検証がControllerにある | REJECT。UseCase層に |
| 構造バリデーション（@NotBlank等）がドメインにある | REJECT。API層で |
| UseCase層のバリデーションがAggregate内にある | REJECT。Read Model参照はUseCase層 |
エラーハンドリング
例外階層設計
ドメイン例外は sealed class で階層化する。HTTP ステータスコードへのマッピングは Controller 層で行う。
// ドメイン例外: sealed class で網羅性を保証
sealed class OrderException(message: String) : RuntimeException(message)
class OrderNotFoundException(message: String) : OrderException(message)
class InvalidOrderStateException(message: String) : OrderException(message)
class InsufficientStockException(message: String) : OrderException(message)
// Controller 層でHTTPステータスにマッピング
@RestControllerAdvice
class OrderExceptionHandler {
@ExceptionHandler(OrderNotFoundException::class)
fun handleNotFound(e: OrderNotFoundException) =
ResponseEntity.status(HttpStatus.NOT_FOUND).body(ErrorResponse(e.message))
@ExceptionHandler(InvalidOrderStateException::class)
fun handleInvalidState(e: InvalidOrderStateException) =
ResponseEntity.status(HttpStatus.CONFLICT).body(ErrorResponse(e.message))
@ExceptionHandler(InsufficientStockException::class)
fun handleInsufficientStock(e: InsufficientStockException) =
ResponseEntity.status(HttpStatus.UNPROCESSABLE_ENTITY).body(ErrorResponse(e.message))
}
| 基準 | 判定 |
|---|---|
| ドメイン例外にHTTPステータスコードが含まれる | REJECT。ドメインはHTTPを知らない |
| 汎用的な Exception や RuntimeException を throw | REJECT。具体的な例外型を使う |
| try-catch の空 catch | REJECT |
| Controller 内で例外を握りつぶして 200 を返す | REJECT |
ドメインモデル設計
イミュータブル + require
ドメインモデルは data class（イミュータブル）で設計し、init ブロックと require で不変条件を保証する。
data class Order(
val orderId: String,
val status: OrderStatus = OrderStatus.PENDING
) {
// companion object の static メソッドで生成
companion object {
fun place(orderId: String, customerId: String): OrderPlacedEvent {
require(customerId.isNotBlank()) { "Customer ID cannot be blank" }
return OrderPlacedEvent(orderId, customerId)
}
}
// インスタンスメソッドで状態遷移 → イベント返却
fun confirm(confirmedBy: String): OrderConfirmedEvent {
require(status == OrderStatus.PENDING) { "確定できる状態ではありません" }
return OrderConfirmedEvent(orderId, confirmedBy, LocalDateTime.now())
}
// イミュータブルな状態更新
fun apply(event: OrderEvent): Order = when (event) {
is OrderPlacedEvent -> Order(orderId = event.orderId)
is OrderConfirmedEvent -> copy(status = OrderStatus.CONFIRMED)
is OrderCancelledEvent -> copy(status = OrderStatus.CANCELLED)
}
}
| 基準 | 判定 |
|---|---|
| ドメインモデルに var フィールド | REJECT。copy() でイミュータブルに更新 |
| バリデーションなしのファクトリ | REJECT。require で不変条件を保証 |
| ドメインモデルが外部サービスを呼ぶ | REJECT。純粋な関数のみ |
| setter でフィールドを直接変更 | REJECT |
値オブジェクト
プリミティブ型（String, Int）をドメインの意味でラップする。
// ID系: 型で取り違えを防止
data class OrderId(@get:JsonValue val value: String) {
init { require(value.isNotBlank()) { "Order ID cannot be blank" } }
override fun toString(): String = value
}
// 範囲系: 複合的な不変条件を保証
data class DateRange(val from: LocalDateTime, val to: LocalDateTime) {
init { require(!to.isBefore(from)) { "終了日は開始日以降でなければなりません" } }
}
// メタ情報系: イベントペイロード内の付随情報
data class ApprovalInfo(val approvedBy: String, val approvalTime: LocalDateTime)
| 基準 | 判定 |
|---|---|
| 同じ型のIDが取り違えられる（orderId と customerId が両方 String） | 値オブジェクト化を検討 |
| 同じフィールドの組み合わせ（from/to等）が複数箇所に | 値オブジェクトに抽出 |
| 値オブジェクトに init ブロックがない | REJECT。不変条件を保証する |
リポジトリパターン
ドメイン層でインターフェースを定義し、adapter/outbound で実装する。
// domain/: インターフェース（ポート）
interface OrderRepository {
fun findById(orderId: String): Order?
fun save(order: Order)
}
// adapter/outbound/persistence/: 実装（アダプター）
@Repository
class JpaOrderRepository(
private val jpaRepository: OrderJpaRepository
) : OrderRepository {
override fun findById(orderId: String): Order? {
return jpaRepository.findById(orderId).orElse(null)?.toDomain()
}
override fun save(order: Order) {
jpaRepository.save(OrderEntity.from(order))
}
}
Read Model Entity（JPA Entity）
Read Model 用の JPA Entity はドメインモデルとは別に定義する。var（mutable）が許容される。
@Entity
@Table(name = "orders")
data class OrderEntity(
@Id val orderId: String,
var customerId: String,
@Enumerated(EnumType.STRING) var status: OrderStatus,
var metadata: String? = null
)
| 基準 | 判定 |
|---|---|
| ドメインモデルを JPA Entity として兼用 | REJECT。分離する |
| Entity に ビジネスロジック | REJECT。Entity はデータ構造のみ |
| Repository 実装がドメイン層にある | REJECT。adapter/outbound に |
認証・認可の配置
認証・認可は横断的関心事として適切な層で処理する。
| 関心事 | 配置 | 手段 |
|---|---|---|
| 認証（誰か） | Filter / Interceptor層 | JWT検証、セッション確認 |
| 認可（権限） | Controller層 | @PreAuthorize("hasRole('ADMIN')") |
| データアクセス制御（自分のデータのみ） | UseCase層 | ビジネスルールとして検証 |
// Controller層: ロールベースの認可
@PostMapping("/{id}/approve")
@PreAuthorize("hasRole('FACILITY_ADMIN')")
fun approve(@PathVariable id: String, @RequestBody request: ApproveRequest) { ... }
// UseCase層: データアクセス制御
fun execute(input: DeleteInput, currentUserId: String) {
val entity = repository.findById(input.id)
?: throw NotFoundException("見つかりません")
require(entity.ownerId == currentUserId) { "他のユーザーのデータは操作できません" }
// ...
}
| 基準 | 判定 |
|---|---|
| 認可ロジックが UseCase 層やドメイン層にある | REJECT。Controller層で |
| データアクセス制御が Controller にある | REJECT。UseCase層で |
| 認証処理が Controller 内にある | REJECT。Filter/Interceptor で |
テスト戦略
テストピラミッド
┌─────────────┐
│ E2E Test │ ← 少数: API全体フロー確認
├─────────────┤
│ Integration │ ← Repository, Controller の統合確認
├─────────────┤
│ Unit Test │ ← 多数: ドメインモデル、UseCase の独立テスト
└─────────────┘
ドメインモデルのテスト
ドメインモデルはフレームワーク非依存なので、純粋なユニットテストが書ける。
class OrderTest {
// ヘルパー: 特定の状態の集約を構築
private fun pendingOrder(): Order {
val event = Order.place("order-1", "customer-1")
return Order.from(event)
}
@Nested
inner class Confirm {
@Test
fun `PENDING状態から確定できる`() {
val order = pendingOrder()
val event = order.confirm("admin-1")
assertEquals("order-1", event.orderId)
}
@Test
fun `CONFIRMED状態からは確定できない`() {
val order = pendingOrder().let { it.apply(it.confirm("admin-1")) }
assertThrows<IllegalArgumentException> {
order.confirm("admin-2")
}
}
}
}
テストのルール:
- 状態遷移をヘルパーメソッドで構築（テストごとに独立）
@Nestedで操作単位にグループ化- 正常系と異常系（不正な状態遷移）を両方テスト
assertThrowsで例外の型を検証
UseCase のテスト
UseCase はモックを使ってテスト。外部依存を注入する。
class PlaceOrderUseCaseTest {
private val commandGateway = mockk<CommandGateway>()
private val customerRepository = mockk<CustomerRepository>()
private val useCase = PlaceOrderUseCase(commandGateway, customerRepository)
@Test
fun `顧客が存在しない場合はエラー`() {
every { customerRepository.findById("unknown") } returns null
assertThrows<CustomerNotFoundException> {
useCase.execute(PlaceOrderInput(customerId = "unknown", items = listOf(...)))
}
}
}
| 基準 | 判定 |
|---|---|
| ドメインモデルのテストにモックを使用 | REJECT。ドメインは純粋にテスト |
| UseCase テストで実DBに接続 | REJECT。モックを使う |
| テストがフレームワークの起動を必要とする | ユニットテストなら REJECT |
| 状態遷移の異常系テストがない | REJECT |
アンチパターン検出
以下を見つけたら REJECT:
| アンチパターン | 問題 |
|---|---|
| Smart Controller | Controller にビジネスロジックが集中 |
| Anemic Domain Model | ドメインモデルが setter/getter だけのデータ構造 |
| God Service | 1つの Service クラスに全操作が集中 |
| Repository直叩き | Controller が Repository を直接参照 |
| ドメイン漏洩 | adapter 層にドメインロジックが漏れる |
| Entity兼用 | JPA Entity をドメインモデルとして使い回す |
| 例外握りつぶし | 空の catch ブロック |
| Magic String | ハードコードされたステータス文字列等 |