backend-api-design

バックエンド API 設計 — クイックリファレンス

URL パターン

GET  /api/v1/employees              # List (plural)
GET  /api/v1/employee               # Get one (?id=xxx)
POST /api/v1/employee               # Create
POST /api/v1/employee/update        # Update (?id=xxx)
POST /api/v1/employee/delete        # Soft delete (?id=xxx)
POST /api/v1/employee/restore       # Restore (?id=xxx)
POST /api/v1/sync/employees         # Action

厳守ルール

• パスパラメーターは使用しません — 常に @QueryValue を使い、@PathVariable は使用しません
• 単一リソースには単数形を使用します — /employees/{id} ではなく /employee
• コレクションには複数形を使用します — /employees
• アクションには動詞のサブパスを使用します — /delete、/restore、/sync

レイヤードアーキテクチャ

Controller  →  thin, just delegates
    ↓
Manager     →  business logic, transactions, Either returns
    ↓
Repository  →  data access only, no business logic

コントローラー：薄いラッパー

• デフォルト値を指定してクエリパラメーターを解析します
• マネージャーに処理を委譲します
• .throwOrValue() で Either をアンラップします
• ビジネスロジックは禁止、リポジトリーへのアクセスは禁止です

マネージャー：ビジネスロジック

• Either<ClientException, T> を返します
• DB 操作を transaction(db.primary) { } でラップします
• 複数のリポジトリーをオーケストレーションします
• ビジネスルールを検証します

リポジトリー：データアクセス

• エンティティまたは null を返します
• 読み取りには db.replica、書き込みには db.primary を使用します
• 常に deletedAt.isNull() を確認します

クイックコードリファレンス

コントローラーでの基本的な委譲パターン：

@Get("/employee")
suspend fun getEmployee(@QueryValue id: UUID): EmployeeResponse {
  return employeeManager.findById(id).throwOrValue()
}

• レスポンスモデル — module-client/response/{domain}/ 内に companion object { fun from(entity) } を定義します
• ページネーション — オフセットベースです。マネージャーは items、total、page、limit、hasMore を持つ EmployeeListResponse を返します
• エラー — マネージャーから ClientError.NOT_FOUND.asException().left() を返し、例外をスローしないでください
• ファクトリービーン — @Factory クラスに @Singleton メソッドを定義し、リポジトリーと db をマネージャーに接続します

コントローラー、レスポンスモデル、ページネーション、エラー処理、ファクトリービーンのテンプレートについては、code-patterns.md を参照してください。

注意点

• 複数単語からなる @QueryValue パラメーターには、明示的な snake_case 名が必須です。 フロントエンドの axios インターセプターは project_id を送信しますが、Micronaut はパラメーター名を文字どおりに照合します。@QueryValue projectId: UUID のように省略せず、@QueryValue("project_id") projectId: UUID と記述してください。
• @Put、@Delete、@Patch は使用しないでください。 これは RPC スタイルです。すべての変更操作には @Post を使用します。読み取りに使用する @Get は 1 つだけです。
• リポジトリーを注入するコントローラーは、コードの問題を示す兆候です。 コントローラー内に private val fooRepository: FooRepository がある場合は、マネージャーに移動してください。
• 2 つ目の .where {} ではなく andWhere {} を使用します。 .where {} を 2 回呼び出すと、最初の条件が置き換えられます。条件をつなげるには .andWhere {} を使用してください。
• @ExecuteOn(TaskExecutors.IO) を忘れないでください。 これがないと、suspend 関数が停止したり、誤ったスレッドプールで実行されたりする場合があります。すべてのコントローラーに必要です。