Allra バックエンド API 設計およびパッケージ構造

Allra バックエンドチームの API 設計、DTO 命名、パッケージ構造の標準を定義します。

プロジェクト基本情報

このガイドは、次の環境を基準に作成されました。

• Java: 17 以上
• Spring Boot: 3.2 以上
• 主要技術: JPA/Hibernate, QueryDSL, JWT

参考: プロジェクトごとに使用する技術スタックやバージョンが異なる場合があります。プロジェクトに合わせて調整して使用してください。

パッケージ構造規則

ドメイン別のパッケージ構造を推奨します。

└── {domain}
    ├── api          // コントローラレイヤ
    ├── dto          // データ転送オブジェクト
    ├── entity       // JPA エンティティ
    ├── enums        // Enum 定義 (選択)
    ├── repository   // データアクセス階層
    └── service      // ビジネスロジック

参考: プロジェクトによっては controller、model、dao など、異なる名前を使用する場合があります。重要なのは、レイヤ別の責任を明確に分離することです。

例

└── user
    ├── api
    │   └── UserController.java
    ├── dto
    │   ├── UserSignUpEventDto.java  // 内部使用
    │   ├── request
    │   │   └── SignUpRequest.java
    │   └── response
    │       └── SignUpResponse.java
    ├── entity
    │   └── User.java
    ├── repository
    │   ├── UserRepository.java
    │   └── UserRepositorySupport.java
    └── service
        └── UserService.java

DTO 命名規則

1. クライアント通信 DTO

• Request: {Operation}Request
  • 例: SignUpRequest, UpdateUserRequest
• Response: {Operation}Response
  • 例: SignUpResponse, UserDetailResponse

2. 内部使用 DTO

内部でのみ使用する DTO は Dto 接尾辞を追加します。

• Repository Layer QueryDSL Fetch DTO
• Internal Layer Transfer DTO
• 例: UserSignUpEventDto, UserSummaryDto

3. Record 使用

DTO のような単純なクラスは、可能であればほとんど record で生成

// Request/Response
public record SignUpRequest(
    String email,
    String password,
    String name
) {}

public record SignUpResponse(
    Long userId,
    String email
) {}

// 内部使用 DTO
public record UserSignUpEventDto(
    Long userId,
    String email,
    LocalDateTime signUpAt
) {}

API コントローラ設計ガイド

1. REST API 命名規則

@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    // GET /api/v1/users - 一覧照会
    @GetMapping
    public List<UserResponse> getUsers() { }

    // GET /api/v1/users/{id} - 単件照会
    @GetMapping("/{id}")
    public UserDetailResponse getUser(@PathVariable Long id) { }

    // POST /api/v1/users - 生成
    @PostMapping
    public SignUpResponse createUser(@RequestBody @Valid SignUpRequest request) { }

    // PUT /api/v1/users/{id} - 全体修正
    @PutMapping("/{id}")
    public UserResponse updateUser(
        @PathVariable Long id,
        @RequestBody @Valid UpdateUserRequest request
    ) { }

    // PATCH /api/v1/users/{id} - 部分修正
    @PatchMapping("/{id}")
    public UserResponse patchUser(
        @PathVariable Long id,
        @RequestBody @Valid PatchUserRequest request
    ) { }

    // DELETE /api/v1/users/{id} - 削除
    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) { }
}

参考: API バージョニング(/api/v1/...)は、プロジェクトのポリシーに応じて選択的に適用します。

2. Request Validation

すべての Request DTO は Bean Validation を使用します。

public record SignUpRequest(
    @NotBlank(message = "이메일은 필수입니다")
    @Email(message = "올바른 이메일 형식이 아닙니다")
    String email,

    @NotBlank(message = "비밀번호는 필수입니다")
    @Size(min = 8, message = "비밀번호는 최소 8자 이상이어야 합니다")
    String password,

    @NotBlank(message = "이름은 필수입니다")
    String name
) {}

3. 応答形式

Allra 標準形式 (例):

成功応答:

{
  "data": { ... },
  "message": "요청이 성공적으로 처리되었습니다"
}

エラー応答:

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "사용자를 찾을 수 없습니다",
    "details": []
  }
}

参考: 応答形式はプロジェクトごとに異なる場合があります。一貫性のある形式を維持することが重要です。

When to Use This Skill

この skill は、次の状況で自動的に適用されます。

• 新しい API エンドポイントの生成
• DTO クラスの作成
• コントローラの実装
• ドメインパッケージ構造の設計
• Request/Response オブジェクトの命名

Examples

例 1: 新しいドメイン API の生成

// 1. パッケージ構造生成
kr.co.allra.product/
├── api/ProductController.java
├── dto/
│   ├── request/CreateProductRequest.java
│   └── response/ProductResponse.java
├── entity/Product.java
├── repository/ProductRepository.java
└── service/ProductService.java

// 2. Request DTO
public record CreateProductRequest(
    @NotBlank String name,
    @NotNull BigDecimal price
) {}

// 3. Response DTO
public record ProductResponse(
    Long id,
    String name,
    BigDecimal price,
    LocalDateTime createdAt
) {}

// 4. Controller
@RestController
@RequestMapping("/api/v1/products")
public class ProductController {

    @PostMapping
    public ProductResponse createProduct(
        @RequestBody @Valid CreateProductRequest request
    ) {
        return productService.createProduct(request);
    }
}

例 2: 内部 DTO の生成

// QueryDSL 結果のための内部 DTO
public record ProductSummaryDto(
    Long id,
    String name,
    Long orderCount
) {
    @QueryProjection
    public ProductSummaryDto {}
}

// イベント伝達用の内部 DTO
public record ProductCreatedEventDto(
    Long productId,
    String productName,
    LocalDateTime createdAt
) {}

Checklist

新しい API を作成する際の確認事項:

• [ ] ドメイン別のパッケージ構造に従っているか?
• [ ] Request/Response DTO の命名が規則に従っているか?
• [ ] DTO が record で作成されているか?
• [ ] Request DTO に Validation が適用されているか?
• [ ] REST API 命名規則に従っているか?
• [ ] 内部使用 DTO に Dto 接尾辞があるか?