Controller：HTTP境界を薄く保つ

Payment APIの2つの入口

@RequestMappingが共通パス、@PostMappingが個別操作を定義します。@RequestBodyはJSON、@RequestHeaderはHTTPヘッダー、@PathVariableはURL内の値を受け取ります。

入力検証は入口で早く失敗させる

@ValidによりDTOの制約が検査されます。OTPは空でなく6桁の数字、金額は1以上の整数、memoは最大200文字という形式契約があります。

形式が正しくても、本人の振込依頼か、期限内か、残高があるかは分かりません。それらはDB側の業務検査です。

public record ConfirmPaymentOtpRequest(
    @NotBlank
    @Pattern(regexp = "^\\d{6}$")
    String otpCode
) {}

認証情報と冪等キーもAPI契約

• AuthorizationはBearer形式であることをControllerが確認
• Bearer tokenの本人性と権限は転送先のPostgREST・PostgreSQLが判断
• Idempotency-KeyはUUIDとして解析し、不正な形式を拒否
• 振込先の銀行名・支店名・名義はクライアントから受け取らず、DB側で解決

例外変換を一か所へ集める

@RestControllerAdviceのGlobalExceptionHandlerが、ApiException、入力エラー、想定外例外を統一JSONへ変換します。

想定外例外はサーバーログへ記録しますが、クライアントへスタックトレースや生のPostgreSQLメッセージを返しません。requestIdによって利用者の応答と内部ログを結びます。