RESTFul API 패키지 구조 설계안 ( 버전 우선, 도메인 우선 등 방식 비교 )

RESTFul API 설계시 패키지 구조를 어떤 방식으로 잡을지 많은 고민을 합니다. 

다음과 같이 버전이 특정되어 있는 형태일 때, 몇가지 효과적인 방법을 생각해볼 수 있습니다.

 

인증 API

/api/v1/auth

 

대출 조회 API

/api/v1/loan

 

대략 위와 같은 형태로 API가 설계된다면, 버전에 종속적인 패키지 구조를 고려할수도, 혹은 업무에 따라 구분하는 방법도 고려할 수 있습니다.

 

1. 버전 우선

-src
    -main
        -java
            -com.example
                -api
                    -config (for swagger configuration)
                    -controller
                        -v1
                            -AuthController.java (handles authentication-related endpoints for version 1 of the API)
                            -UserController.java (handles user-related endpoints for version 1 of the API)
                        -v2
                            -AuthController.java (handles authentication-related endpoints for version 2 of the API)
                            -UserController.java (handles user-related endpoints for version 2 of the API)
                    -model
                        -Auth.java (model for authentication)
                        -User.java (model for user)
                    -repository
                        -AuthRepository.java (JPA repository for auth)
                        -UserRepository.java (JPA repository for user)
                    -service
                        -AuthService.java (service for auth)
                        -UserService.java (service for user)
                -Application.java

- 버전에 따라 분리하는 방법으로 각 도메인 혹은 업무 로직에 따라 중복된 코드가 발생 할 수 있습니다.

2. 도메인(업무) 우선

-src
    -main
        -java
            -com.example
                -api
                    -auth
                        -controller
                            -AuthController.java (handles authentication-related endpoints for version 1 of the API)
                        -model
                            -Auth.java (model for authentication)
                        -repository
                            -AuthRepository.java (JPA repository for auth)
                        -service
                            -AuthService.java (service for auth)
                    -user
                        -controller
                            -UserController.java (handles user-related endpoints for version 1 of the API)
                        -model
                            -User.java (model for user)
                        -repository
                            -UserRepository.java (JPA repository for user)
                        -service
                            -UserService.java (service for user)
                    -config (for swagger configuration)
                -Application.java

- 업무에 기반하여 패키지를 나누었으나 버전이 증가할수록 객체의 크기가 늘어나 관리하기 어려울 수 있습니다.

- 특히 각 레이어에 어떤 버전에 대한 함수 혹은 객체인지 구분하기 어려울 수 있습니다.

3. 복합 방식

-src
    -main
        -java
            -com.example
                -api
                    -v1
                        -auth
                            -controller
                                -AuthController.java (handles authentication-related endpoints for version 1 of the API)
                            -model
                                -Auth.java (model for authentication)
                            -repository
                                -AuthRepository.java (JPA repository for auth)
                            -service
                                -AuthService.java (service for auth)
                        -user
                            -controller
                                -UserController.java (handles user-related endpoints for version 1 of the API)
                            -model
                                -User.java (model for user)
                            -repository
                                -UserRepository.java (JPA repository for user)
                            -service
                                -UserService.java (service for user)
                    -v2
                        -auth
                            -controller
                                -AuthController.java (handles authentication-related endpoints for version 2 of the API)
                            -model
                                -Auth.java (model for authentication)

- 위 두 방식을 섞은 방식이지만, 디렉토리, 객체등이 불필요하게 늘어날 수 있습니다. 

4. 간결한 방식

-src
  - main
     - java
         - com.example
             - api
                - v1
                    - auth
                        - AuthController.java
                        - AuthService.java
                        - AuthRepository.java

- 위의 모든 방식을 함축적으로 표현하면서 엔드포인트를 찾기 쉽습니다

- 각 서비스 레이어(Controller, Model, Repository)를 굳이 디렉토리로 나누지 않고 클래스 네이밍 수준에서 관리함으로 패키지 및 클래스 객체 관리가 더욱 용이합니다. ( 수 많은 도메인(업무)가 존재한다고 생각해보세요. )