장고 프로젝트 코드 작성법 제안

[Kirade]

Abstract

이 논의는 저희들이 어떻게 장고 프로젝트를 개발해 나가면 좋을지에 대한 제안을 담고 있습니다.
처음 프로젝트에 투입되는 개발자는 물론, 숙련된 개발자들도 '이 코드는 장고 프로젝트 어느곳에 두어야 하는가?' 에 대한 고민을 가지게 될텐데요. 이런 고민에 대한 최대한 적절한 답을 찾을수 있도록 안내하는 것이 주요 목표입니다.

이어지는 상세는 장고 프로젝트를 구성하는 여러 구성 요소들을 나열하고, 각 요소에 기대하는 역할과 특징에 대해 설명합니다.

Rationale

장고 프로젝트는 잘 작성된 개발 문서를 통해 원하는 프레임 워크를 활용하는데 필요한 부분을 잘 설명해주고 있습니다.
따라서 대부분의 프로젝트는 개발 문서에서 제공하는 기본적인 스타일 가이드에 따라 어렵지 않게 비즈니스의 요구사항을 관리할 수 있습니다.

하지만 저희들의 비즈니스의 형태와 규모가 지속적으로 변화함에 따라 장고의 기본적인 스타일 가이드로 관리하기에 어려운 지점들이 발생하기 시작되었습니다.
그래서 장고의 기본적인 스타일 가이드 이외에 추가적인 규칙들을 통해서 문제가되는 관리 지점들을 정리해야 할 필요가 있다고 판단했습니다.

이 제안을 통해 다음과 같은 긍정적인 변화를 얻을수 있을것을 기대합니다.

• 코드를 작성하는 위치에 대한 합의를 통한 개발 생산성 향상
  서로 합의된 위치에 코드를 작성하게 되면, 코드 위치에 대한 불필요한 커뮤니케이션이 줄어듭니다.
  비즈니스 코드를 찾을 일이 생겼을 때, 어떤 위치에 정의되어 있을지 쉽게 예상할 수 있게 됩니다.

• 테스트 방식의 구체화
  모듈의 역할에 따라 테스트 방식과 범위를 합의하여 맞춰 일관된 방식으로 테스트를 할 수 있게됩니다.

Specification

App

장고 프로젝트 안에서 앱은 일반적으로 웹 서비스를 위한 하나의 독립적인 기능을 수행하곤 합니다.
따라서, 필요에 따라 장고의 앱은 쉽게 패키징 되어 다른 장고 프로젝트에 쉽게 재사용 될 수 있는 구조를 가집니다.

데이터베이스를 활용하면서 기존에 존재하지 않던 새로운 도메인을 설계하는경우 앱을 신규로 작성하는 것을 권장합니다.
현재 작성된 많은 앱은 이미 기능이 충분히 많고 도메인의 경계가 불분명한 경우가 많습니다. 이런 경우 새로운 기능을 위해 명확하게 앱을 분리하는것이 기존의 앱에 얹는것보다 좋은 선택이 될 수 있습니다.

Model

• 일반적으로 장고의 모델은 데이터베이스 테이블가 1:1 로 매핑됩니다. 즉 하나의 모델은 하나의 데이터베이스 테이블을 의미합니다.
• 모델 클래스의 인스턴스는 데이터베이스 테이블에 한 개의 레코드를 의미합니다.
  • 따라서 어떤 레코드 하나에 대한 여러 기능들은 모델의 인스턴스 메서드로 정의합니다.
• 장고에서는 Fat Model 을 지향합니다. 저희들은 이러한 디자인 결정을 존중하지만 모델이 비정상적으로 커지는것을 지양합니다.

  이후 설명되겠지만, 비정상적으로 코드가 모델 클래스에 몰리는것을 방지하기 위해 코드의 목적에 따라 QuerySet, Manager, Operation, Service 등의 레이어를 나누어 위치시킵니다.

class User:
    first_name = models.CharField(max_length=20)
    last_name = models.CharField(max_length=20)
    age = models.PositiveIntegerField()
    is_active = models.BooleanField()
    is_staff = models.BooleanField()

    def inactivate(self):
        self.is_active = False
        self.save()

    @property
    def full_name(self)
        return f'{first_name} {last_name}'

QuerySet

• 데이터베이스의 데이터를 가져와서 읽거나(SELECT), 주석(Annotation)을 달거나, 계산(Aggregate)을 하는 등의 기능을 쿼리셋의 메서드로 정의합니다.
  • filter(), aggregate(), annotation(), etc.
• 쿼리 결과에 chaining 이 필요한 경우에 활용합니다.
• 장고 앱 패키지 내부에 querysets.py 라는 모듈로 관리됩니다.

class UserQuerySet:
    def active(self):
        return self.filter(is_active=True)

    def total_age(self):
        return self.aggregate(sum=Sum('age'))

Manager

• 매니저는 쿼리셋과 유사하게 장고의 데이터베이스 쿼리 동작들을 정의합니다.
• 모델의 인스턴스를 생성하는 경우 매니저 메서드로 정의합니다.
• 쿼리셋과 다르게 읽기가 아닌 쓰기 / 수정 동작을 수행하는데 초점을 맞춥니다.
  • create(), update(), delete(), etc.
• 장고 앱 패키지 내부에 managers.py 라는 모듈로 관리됩니다.

class UserManager:
    
    def create_staff(self, first_name, last_name, age):
        return self.create(
            first_name=first_name,
            last_name=last_name,
            age=age,
            is_staff=True,
        )

    def remove_user(self, user_id):
        user = User.objects.get(id=user_id)
        user.delete()

        logger.info(f'User ID: {user_id} is removed from database')

UseCase

• 유즈케이스는 비즈니스를 수행하기 위해 필요한 기능들을 정의합니다. 저희들은 이것을 업무 규칙의 의미로 활용하고 있습니다.
• 업무 규칙은 비즈니스의 요구사항에 따라 정의되며, 비즈니스의 변화에 따라 추가, 변경, 제거 될 수 있습니다.
• 주요 비즈니스 코드들을 모델에 작성하는 일반적인 장고 스타일(Fat Model)에 따르면 업무규칙은 Model 에 작성되어야 합니다.
• 위 방식은 단일 모델을 포함하는 단순한 업무규칙인 경우 효율적일 수 있지만, 여러개의 모델들에 영향을 주는 업무 규칙인 경우 모델 내부에 업무규칙을 정의하는것은 여러 모델 중에 어떤 모델에 업무 규칙을 넣어야 하는가에 대한 고민을 발생시킵니다.
• 저희들은 이것을 해결하기 위해 별도의 레이어를 만들었고 Operation 그리고 Service 로 이름을 붙였습니다.
• Operation, Service 는 여전히 어떤 앱 내부에 존재합니다. 여러 앱의 모델들을 활용해야 하는 경우, 의미상 가장 근접한 앱 내부에 업무 규칙을 정의하도록 합니다.
• 미래에는 업무 규칙이 특정 앱에 종속되지 않고 완전히 분리되어 장고 프로젝트 내부의 업무규칙을 모아두는 별도의 공간을 마련할 수 있습니다.

Operation

• 업무 규칙에 대한 구체적인 구현이 이루어지는 곳 입니다.
• operations 라는 모듈 혹은 패키지를 내부에 작성합니다.
• 구현의 방식은 함수나 클래스 중 특정한 한 가지로 제약하지 않습니다. 구현 상황에 가장 적절한 방식을 채택하면됩니다.
• Operation 의 이름은 업무 규칙을 잘 나타낼 수 있는 이름을 짓습니다.
  • Operation 이라는 접미사는 붙이지 않아도 괜찮습니다. 왜냐하면 operations 라는 모듈 혹은 패키지의 namespace 가 이미 존재하기 때문입니다.

class StaffCreator:

    def create(self, first_name, last_name, age):
        user = User.objects.create_staff(
            first_name=first_name,
            last_name=last_name,
            age=age,
        )
        logger.info(f'스태프 등록: {user}')

Service

• Service 는 Operation 에서 구현된 업무 규칙을 활용할수 있는 인터페이스를 외부에 노출합니다.
• Service 는 Operation 을 사용하기위한 여러 규칙들을 알고 있으며, 이것을 인터페이스를 활용할 사용자에게 친절하게 안내해야합니다.
• 일반적으로 사용자는 Operation 의 구현을 직접 사용해서는 안되며, Service 에 노출된 인터페이스를 활용해서 업무 규칙을 수행해야 합니다.

class RegistrationService:

    def register_staff():
        StaffCreator().create(
            first_name='GilDong',
            last_name='Hong',
            age=20,
        )

API

저희 서비스는 Django Rest Framework 라이브러리를 활용하여 REST API 를 구현하고 있습니다.
라이브러리에서 제공하는 여러 기능들을 통해 편의성을 최대한 높이되, 업무 규칙들이 API 영역에 구현되는것은 지양합니다.

Serializer

• 직렬화기 / 반직렬화기 의 기능을 합니다.
• 통신을 위해 데이터를 가공하는 기능들이 이곳에 정의됩니다.
• 업무 규칙을 위한 구체적인 구현이 포함되어서는 안됩니다.

API View

• 요청과 응답을 위한 일련의 규칙(권한, 인증 등)들이 작성됩니다.
• 업무 규칙을 위한 구체적인 구현이 포함되어서는 안됩니다.

---

##Reference
https://docs.djangoproject.com/ko/4.0/misc/design-philosophies/
https://www.b-list.org/weblog/categories/django/
https://github.com/HackSoftware/Django-Styleguide

[donghyun0218]

전반적인 내용에 동의합니다.

[twins1040]

지금 돌이켜 생각해보면 왜 api 와 app 을 나누었을까 생각이 듭니다.
현재 최상위 api 디렉토리 내 어떤 api 도 app 없이 동작할 수 없어보이거든요.
말씀하신대로, api 가 사라지고(혹은 app 이 사라지고), 각 장고 앱들이 각자의 view, url 을 가지게 되고, DB 자체도 분리되게 된다면, 독립적으로 관리 가능한 kcb 나 nice 같은 것들은 코드, 서버까지 분리시켜서 따로 운영할 수 있겠네요. 코어 뱅킹과 서비스를 분리하는 수준까지도 가능할지도?

[jseop-lim]

DB 쓰기 동작을 수행하는 ORM의 배치에 대한 의견이 있습니다.
QuerySet에서 DB 쓰기 연산 사용이 허용되어야 하는 경우가 존재합니다.

Manager에 정의된 메서드는 모델이름.objects.매니저메서드() 형태로 objects 객체를 통해서만 사용 가능합니다.
한편 QuerySet은 모델이름.objects.filter(...).쿼리셋메서드()처럼 Django QuerySet API의 반환값에서 모두 호출할 수 있습니다. 같은 이유로 ORM의 update() 또한 models.QuerySet의 메서드로 정의되어 있습니다.

Manager나 QuerySet 메서드 정의는 특정 조합의 ORM에 대한 인터페이스를 제공하고 코드 중복을 방지하는 효과가 있습니다. 더욱 유연한 인터페이스를 제공하여 효과를 극대화하기 위해, QuerySet에 DB 쓰기 연산이 허용되어야 한다고 생각합니다.

허용할 쓰기 연산의 종류로는 update()나 delete()를 사용하는 연산이 적당해 보입니다.
create()는 다른 쿼리셋 메서드와 함께 사용할 일이 없고 이 둘은 다른 QuerySet 메서드와 혼용될 여지가 있기 때문입니다.

[Kirade]

update, delete 와 같은 경우에 장고의 기본 QuerySet 에 정의되어 있다는 점에서 저희도 같은 방식을 따라도 괜찮다고 생각합니다.

[donghyun0218]

동의합니다

[twins1040]

좋습니다. 다만 비즈니스로직 전체를 끌어오는 수준으로 작성하기보다, 재사용성이 높은 함수 위주로 작성되는것이 좋을 것 같습니다.
QuerySet 메서드 안에서 다른 모델을 변형한다거나 하는 것은 지양해야 할 것 같습니다.