애플리케이션 사용 사례 정의

사용 사례 개요

사용 사례는 사용자 또는 외부 시스템과 애플리케이션 간의 완전한 상호작용을 나타내며, 특정 비즈니스 시나리오를 설명합니다. Lino에서는 각 사용 사례가 다음과 같이 나뉩니다:

• 명령(Command): 시스템 상태를 변경하려는 의도(생성, 업데이트, 삭제 등)를 나타냅니다.
• 쿼리(Query): 도메인 상태를 변경하지 않고 데이터를 조회하려는 의도를 나타냅니다.

이러한 분리는 코드의 명확성을 높이고, 테스트를 용이하게 하며, 읽기 및 쓰기 작업의 독립적인 확장성을 가능하게 하고, 클린 아키텍처 원칙과 도메인 주도 설계 (DDD)의 모범 사례에 부합합니다.

명령(Commands)

명령(Command)은 시스템 상태를 변경하는 작업을 수행하는 데 필요한 데이터만 담고 있는 불변 메시지입니다(예: CreateInvoice, DeactivateUser). 명령은 작업 수행에 필수적인 정보만 포함해야 합니다.

명령의 특징

• 불변성: record 또는 공개 set자가 없는 get만 있는 클래스 형태로 구현됩니다.
• 명령형 이름: 실행될 작업을 반영하며 예를 들어 CreateOrder, UpdateCustomerAddress 등이 있습니다.
• 최소한의 데이터: 작업 실행에 필요한 필드만 포함하며 대량의 데이터를 반환하지 않습니다.
• 독립적인 검증: 각 명령은 자체 검증 규칙을 가지며, 핸들러(Handler)에 전달되기 전에 일관성을 보장합니다.

명령 검증기(Command Validators)

명령 검증기는 명령이 올바르게 형성되었는지 및 비즈니스 요구 사항을 충족하는지 핸들러에 전달하기 전에 확인합니다. Lino에서는 .NET 프로젝트에서 널리 사용되고 규칙 작성에 Fluent API를 제공하는 FluentValidation 라이브러리를 사용합니다.

일반 검증 규칙

• NotEmpty, NotNull - 필수 필드용
• InclusiveBetween - 숫자 범위용(예: 금액, 최소/최대 수량)
• MaximumLength, MinimumLength - 문자열 길이용
• RuleForEach - 컬렉션(List<T>) 항목 검증용
• Must - 사용자 정의 규칙용(예: 문서 형식, 날짜 검증)

명령 핸들러(Command Handlers)

명령 핸들러는 해당 명령과 관련된 도메인 로직을 실행하는 책임이 있습니다. 리포지토리, 작업 단위(IUnitOfWork), 보조 서비스들을 조율하고 필요 시 도메인 이벤트를 발생시킵니다.

핸들러 구현 패턴

• 의존성 주입을 통해 리포지토리, 외부 서비스, UnitOfWork 등의 의존성을 받습니다.
• 도메인 엔티티를 매핑하고 인스턴스화하여 초기 일관성을 보장합니다.
• 비즈니스 규칙 적용(추가 검증, 값 계산, 도메인 이벤트 트리거)
• IUnitOfWork 또는 직접 리포지토리를 통해 변경사항을 영속화합니다.
• 성공 또는 실패를 나타내는 명령 결과(Command Result)(Result<T>)를 반환합니다.

명령 결과와 Result 패턴

명령 결과는 호출자(예: API 또는 프런트엔드)가 계속 진행하는 데 필요한 최소한의 데이터만 포함하는 간단한 DTO여야 합니다. 일반적으로 생성되거나 업데이트된 엔티티의 식별자(Id)와 실패 시 오류에 대한 표준화된 정보를 포함합니다.

명령이 실패할 수 있는 시나리오에서는 Result 패턴을 사용합니다. 이 패턴은 성공 또는 실패일 수 있는 작업 결과를 캡슐화하는 추상화입니다. .NET에서는 Result<T>와 같은 타입(또는 유사 라이브러리)을 주로 사용하며:

• 성공 시 Value를 설정할 수 있습니다(예: 단순 DTO).
• 실패 시 표준화된 코드 또는 메시지(Error)를 저장하며, HTTP 코드, 검증 세부사항 등 추가 메타데이터가 포함될 수 있습니다.
• API 전체에서 오류 처리 흐름을 통합하여 계층 간 일관성을 유지합니다.

CLI를 사용한 명령 생성

Lino는 다음 명령어를 통해 새 명령에 필요한 모든 아티팩트를 쉽게 생성할 수 있습니다:

lino command new

이 명령을 실행하면 대화형 마법사가 다음을 요청합니다:

• 서비스 — 명령이 생성될 서비스 이름
• 모듈 — 모듈화된 서비스의 경우 대상 모듈 정의
• 엔티티 — 명령과 관련된 도메인 엔티티(선택 사항이지만 권장)
• 명령 이름 — 최종 명령 이름(예: CreateOrder)

확인 후 Lino가 자동으로 다음 파일들을 생성합니다:

• CreateOrderCommand.cs
• CreateOrderCommandValidator.cs
• CreateOrderCommandHandler.cs
• CreateOrderCommandResult.cs

생성된 구조 예시

CreatePerson 명령을 예로 들어 보겠습니다. 생성된 구조는 다음과 유사합니다:

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Application/
                ├── MyApp.MyService.Application.csproj
                └── UseCases/
                    └── People/
                        ├── Commands/
                        │   └── CreatePerson/
                        │       ├── CreatePersonCommand.cs
                        │       ├── CreatePersonCommandValidator.cs
                        │       ├── CreatePersonCommandHandler.cs
                        │       └── CreatePersonCommandResult.cs
                        └── Queries/
                            └── ...

쿼리(Queries)

쿼리는 도메인의 상태를 변경하지 않고 데이터를 조회하려는 의도를 나타냅니다. 쿼리는 읽기 효율성을 위해 설계되었으며, 요청되지 않은 경우 전체 엔티티를 로드하지 않고 필요한 필드만 정확히 반환합니다.

쿼리의 특징

• 불변성 — 커맨드와 마찬가지로, 쿼리는 생성된 후 변경되어서는 안 됩니다.
• 설명적인 이름 — 예: GetCustomerById, ListOrdersByDateRange 등과 같이 요청하는 정보를 잘 설명해야 합니다.
• 필터 및 페이징 — 날짜, 상태, 페이지, 정렬 등 특정 조건에 맞는 검색을 위한 파라미터를 포함할 수 있습니다.
• 프로젝션 — 도메인 객체 전체를 로드하지 않고, 필요한 필드만 포함된 DTO 또는 뷰 모델을 반환해야 합니다.

쿼리 유효성 검사기

쿼리 유효성 검사기는 필터, 페이징 값(page, pageSize), 보안 규칙(사용자 권한, 데이터 가시성) 등의 입력 파라미터를 검증하는 역할을 합니다. 또한 FluentValidation으로 구현됩니다.

쿼리에서의 일반적인 유효성 검사 규칙

• GreaterThanOrEqualTo 또는 LessThanOrEqualTo — 날짜 등의 범위 필터에 사용됩니다.
• Length — 이름이나 이메일 등 텍스트 필터에 사용됩니다.
• InclusiveBetween — 페이지당 항목 수와 같은 페이징 파라미터에 사용됩니다.

쿼리 핸들러

쿼리 핸들러는 리포지터리나 데이터베이스 컨텍스트를 조회하고 최적화된 프로젝션을 반환하는 역할을 하며, 도메인 엔티티 전체를 로드하는 것을 피해야 합니다. Lino에서는 .Select()와 같은 메서드를 사용하여 데이터를 원하는 DTO 형식으로 직접 매핑하는 프로젝션 방식을 권장합니다. 이는 효율성과 성능 향상에 도움이 됩니다.

쿼리 결과

Lino에서는 쿼리 결과가 항상 QueryResult 접미사가 붙은 record로 표현됩니다. 이 규칙은 응답 유형이 목록(페이징 포함 여부와 관계없이)이든, 단일 상세 항목이든 상관없이 적용됩니다.

CLI로 쿼리 생성하기

커맨드와 마찬가지로, Lino는 다음 명령어를 제공합니다:

lino query new

마법사는 다음 정보를 요청합니다:

• 서비스 — 쿼리를 생성할 서비스입니다.
• 모듈 — 해당되는 경우 도메인 모듈을 지정합니다.
• 엔티티 — 쿼리가 연결될 엔티티 또는 애그리게이트 (선택 사항).
• 쿼리 이름 — 예: GetOrderById 또는 ListProductsByCategory.

Lino는 다음 파일들을 자동으로 생성합니다:

• GetOrderByIdQuery.cs
• GetOrderByIdQueryValidator.cs
• GetOrderByIdQueryHandler.cs
• GetOrderByIdQueryResult.cs

쿼리에 대한 생성된 구조 예시

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Application/
                ├── MyApp.MyService.Application.csproj
                └── UseCases/
                    └── Orders/
                        ├── Commands/
                        |   └── ...
                        └── Queries/
                            └── GetOrderById/
                                ├── GetOrderByIdQuery.cs
                                ├── GetOrderByIdQueryValidator.cs
                                ├── GetOrderByIdQueryHandler.cs
                                └── GetOrderByIdQueryResult.cs

결론

Lino에서 Use Cases(Commands 및 Queries)를 정의하고 구조화하는 방법을 이해한 후, 쓰기와 읽기 로직을 명확하게 분리하여 견고하고 확장 가능한 비즈니스 시나리오를 만들 준비가 된 것입니다. 개발 속도를 높이기 위해 CLI를 사용하되, 도메인의 특정 요구 사항에 따라 구현을 항상 검토하고 조정하세요.

다음으로는 데이터 지속성, 도메인 이벤트 및 인프라 서비스 처리 방법을 탐구하여 애플리케이션 아키텍처 전체를 구성하세요.