애플리케이션 Use Cases 정의

Use Cases 개요

Use Case는 애플리케이션의 완전한 작업을 나타냅니다. 입력 모델을 받고, 데이터를 검증하고, 의존성을 조율하고, 필요할 때 도메인 동작을 호출하고, 데이터를 저장하거나 조회한 뒤 표준화된 결과를 반환합니다. 이는 도메인 모델 밖으로 불변식을 옮기지 않으면서 애플리케이션이 비즈니스 흐름을 오케스트레이션하는 위치입니다.

Lino가 생성한 솔루션에서 use cases는 예측 가능한 구조로 애플리케이션 프로젝트에 그룹화됩니다:

src/Services/<ServiceName>/<ModuleName>/Application/UseCases/<EntityName>/
├── Commands/
│   └── <CommandName>/
└── Queries/
    └── <QueryName>/

이 구성은 각 feature가 어떤 서비스, 모듈, 엔티티에 속하는지 명확하게 보여 줍니다. 또한 화면, API, 통합 또는 background process가 동작의 한쪽 면만 필요로 할 때 유용하도록 쓰기 모델과 읽기 모델을 독립적으로 유지합니다.

Command 또는 Query?

애플리케이션 use case에 속하는 것

• 입력 contract: 작업에 필요한 데이터만 가진 command 또는 query record.
• Validation: handler가 흐름을 실행하기 전에 요청 형식, 필수 필드, 범위, 식별자, filters 및 기타 입력 제약을 확인하는 규칙.
• Handler 오케스트레이션: 의존성 호출, repository 접근, context 조회, Unit of Work 사용, 결과 구성, logging, tracing.
• 결과 contract: caller가 계속 진행하는 데 정확히 필요한 것을 전달하는 작은 응답 객체 또는 content 없는 결과.

use case 밖에 있어야 하는 것

• 도메인 불변식은 엔티티, Value Objects, domain services, 도메인 메서드에 남아 있어야 합니다.
• Infrastructure 세부 사항은 abstractions, repositories, database contexts, file services, messaging integrations, external clients 뒤에 있어야 합니다.
• Presentation 관심사, 예를 들어 UI 상태, labels, layouts, component 동작은 web app 계층에 남아 있어야 합니다.

좋은 use case는 명시적이고, 이해할 수 있을 만큼 작으며, 경계에 엄격합니다. 작업을 조율하지만 시스템의 모든 규칙이 뒤섞이는 장소가 되지는 않습니다.

Commands

Command는 시스템 상태를 변경하는 동작을 실행하는 데 필요한 데이터만 담는 불변 메시지입니다. 일반적인 예로는 CreateCustomer, UpdateVehicle, DeleteMaintenance, ConfirmOrder, SavePermissionsByRoleId가 있습니다. Commands는 애플리케이션에 무언가를 수행하라고 지시하므로 동작 이름으로 명명해야 합니다.

Lino에서 생성된 Commands는 command 추상화를 구현하고 표준화된 결과를 반환하는 records입니다. 생성 Commands는 보통 caller가 요구하는 식별자나 최소 정보를 담은 결과 객체를 반환하고, 업데이트와 삭제 commands는 작업이 성공적으로 완료되면 일반적으로 no-content를 반환합니다.

Command의 특징

• 불변성: record 또는 get만 있는 클래스처럼 공개 mutable setters 없이 구현됩니다.
• 명령형 이름: CreateOrder, UpdateCustomerAddress, ChangeProductPrice처럼 비즈니스 동작을 반영합니다.
• 최소 데이터: 전체 엔티티나 대량 데이터를 운반하지 않고 작업 실행에 필요한 필드만 포함합니다.
• 분리된 검증: 각 Command는 요청이 handler에 도달하기 전에 일관성을 보장하는 자체 규칙을 가집니다.
• UI 독립성: Command는 작업을 시작한 버튼, 폼 또는 컴포넌트가 아니라 애플리케이션의 의도를 나타냅니다.

Command를 만들어야 하는 경우

• 데이터가 생성, 변경, 제거, 연결, 가져오기, 승인, 취소되거나 어떤 방식으로든 변경될 때 Command를 사용합니다.
• payload는 작업에 집중되게 유지합니다. 몇 개의 필드만 충분하다면 전체 엔티티를 전달하지 않습니다.
• 시작한 시각적 이벤트가 아니라 비즈니스 동작을 설명하는 이름을 선호합니다.
• 동작이 현재 모듈에 속하는지, 아니면 다른 모듈의 통합, 이벤트 또는 shadow entity로 표현되어야 하는지 검토합니다.

Command Validators

Command Validators는 Command가 handler로 전송되기 전에 잘 구성되어 있고 입력 요구 사항을 충족하는지 보장합니다. Lino에서 이러한 검증은 규칙을 만들기 위한 유창하고 읽기 쉬운 API를 제공해 .NET 프로젝트에서 흔히 쓰이는 라이브러리인 FluentValidation으로 구현됩니다.

일반적인 검증 규칙

• 필수 필드에는 NotEmpty 및 NotNull.
• 숫자 범위, 금액, 백분율, 최소 및 최대 수량에는 InclusiveBetween.
• 문자열 길이에는 MaximumLength, MinimumLength, Length.
• List<T>와 같은 컬렉션 항목 검증에는 RuleForEach.
• 문서 형식, 날짜 일관성, 잘못된 필드 조합 같은 사용자 지정 규칙에는 Must.

validator는 입력 경계를 보호합니다. 상태 제한, 허용된 전이, caller와 무관하게 항상 성립해야 하는 규칙 같은 실제 도메인 불변식은 계속 aggregate, 엔티티, Value Object 또는 domain service에 속합니다.

Command Handlers

Command Handler는 Command와 연결된 애플리케이션 로직을 실행합니다. 필요할 때 repository, context, IUnitOfWork, 보조 서비스, logging, tracing, 통합 호출, 도메인 이벤트를 오케스트레이션합니다.

handler 구현 패턴

• repository, 외부 서비스, context, Unit of Work 같은 의존성을 dependency injection으로 받습니다.
• 작업에 필요한 데이터의 존재 여부와 사용 가능성을 검증합니다.
• 작업이 기존 상태에 의존할 때 올바른 aggregate 또는 엔티티를 로드합니다.
• handler에서 불변식을 중복하지 않고 도메인 메서드를 호출합니다.
• IUnitOfWork 또는 프로젝트의 persistence 추상화를 통해 변경 사항을 저장합니다.
• 작업이 시스템의 다른 부분과 통신해야 할 때 도메인 이벤트, Outbox 또는 통합을 등록합니다.
• 성공, 알려진 실패 또는 최소 응답 데이터를 담아 Result 또는 Result<T>를 반환합니다.

Command Results 및 Result Pattern

Command Result는 caller가 계속 진행하는 데 필요한 데이터만 가진 단순 DTO여야 합니다. 생성에서는 보통 생성된 Id를 포함합니다. 업데이트나 삭제에서는 payload가 없을 수 있습니다. 작업이 예상된 조건으로 실패하면 반환값은 표준화된 오류 정보를 담아야 합니다.

Result Pattern은 작업 결과를 성공 또는 실패로 캡슐화합니다. 엔티티를 찾을 수 없음, 잘못된 상태, 비즈니스 검증 같은 예측 가능한 시나리오에 예외를 던지는 대신, handler는 필요할 때 값, 오류, 메타데이터를 포함한 Result<T> 같은 타입을 반환합니다.

• 성공 시 결과는 작은 DTO 또는 생성된 식별자 같은 Value를 노출할 수 있습니다.
• 실패 시 결과는 재사용 가능한 error definitions에 자주 정의되는 표준화된 코드나 메시지를 저장합니다.
• 오류 처리 흐름은 Application, API, typed clients, UI 전반에서 일관되게 유지됩니다.

CLI로 Command 만들기

Lino는 다음 command를 통해 새 Command에 필요한 artifacts 생성을 단순화합니다:

lino command new

CLI는 마법사의 질문을 줄이기 위한 옵션도 허용합니다:

lino command new --service <ServiceName> --module <ModuleName> --entity <EntityName> --name <CommandName>
lino command new --name <CommandName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino command list --service <ServiceName> --module <ModuleName> --entity <EntityName>

• -s 또는 --service: 대상 서비스.
• -m 또는 --module: 모듈화된 서비스의 대상 모듈.
• -e 또는 --entity: Command와 연결된 엔티티.
• -n, --name, -c 또는 --command: Command 이름.

대화형 흐름 중 Lino는 서비스, 모듈, 엔티티, Command 이름, Command 타입, 그리고 생성 또는 업데이트 작업의 경우 요청에 포함될 속성을 확인합니다. CLI가 노출하는 타입은 Create, Update, Delete입니다.

확인 후 Lino는 다음과 같은 파일을 생성합니다:

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

생성된 구조 예시

CreatePerson Command를 고려해 보세요. 생성된 구조는 다음과 비슷합니다:

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Application/
                ├── <ProjectName>.<ServiceName>.Application.csproj
                └── UseCases/
                    └── People/
                        ├── Commands/
                        │   └── CreatePerson/
                        │       ├── CreatePersonCommand.cs
                        │       ├── CreatePersonCommandValidator.cs
                        │       ├── CreatePersonCommandHandler.cs
                        │       └── CreatePersonCommandResult.cs
                        └── Queries/
                            └── ...

Fleet의 사용자 지정 Command도 같은 패턴을 따릅니다:

Application/UseCases/Vehicles/Commands/UpdateVehicle/
├── UpdateVehicleCommand.cs
├── UpdateVehicleCommandValidator.cs
├── UpdateVehicleCommandHandler.cs
└── UpdateVehicleCommandResult.cs

Command 파일의 책임

• Command: 작업 입력을 담는 불변 요청 contract.
• Validator: 일반적으로 필수 여부, 길이, 범위, 식별자, 컬렉션 규칙을 포함하는 입력 검증.
• Handler: repository, Unit of Work, context, 도메인 메서드, logging, tracing, 결과 생성을 오케스트레이션합니다.
• Result: 데이터를 반환해야 하는 성공 작업을 위한 최소 응답 contract.

구현 체크리스트

1. lino command new를 실행하고 올바른 서비스, 모듈, 엔티티, 타입, 속성을 선택합니다.
2. 생성된 Command를 열고 작업 contract에 속하지 않는 필드를 제거합니다.
3. 자동으로 추론할 수 없는 비즈니스 입력 규칙으로 validator를 강화합니다.
4. handler를 검토하고 애플리케이션 계층에서 불변식을 중복하지 않고 도메인 동작을 호출하는지 보장합니다.
5. persistence에는 IUnitOfWork를 사용하고, 작업이 신뢰할 수 있는 이벤트 또는 Outbox도 요구할 때는 transactional save를 선호합니다.
6. 예상된 비즈니스 결과에는 예외가 아니라 Result 오류로 실패를 반환합니다.
7. Command를 호출할 endpoint, page 또는 integration을 컴파일하고 테스트합니다.

Queries

Query는 도메인 상태를 변경하지 않고 데이터를 얻으려는 의도를 나타냅니다. Queries는 효율적인 읽기를 위해 설계되며, 필요하지 않을 때 전체 엔티티를 로드하지 않고 caller에게 필요한 필드만 정확히 반환합니다.

일반적인 예로는 GetCustomerById, ListCustomers, ListPhoneTypes, ListOrdersByDateRange, 그리고 GetVehicleAvailability 같은 사용자 지정 query가 있습니다. Query는 애플리케이션의 특정 질문에 답해야 합니다.

Query의 특징

• 불변: Commands와 마찬가지로 Query는 생성된 후 변경을 허용하지 않아야 합니다.
• 설명적인 이름: GetCustomerById 또는 ListOrdersByDateRange처럼 찾는 정보를 반영합니다.
• Filters 및 pagination: dates, status, page, page size, search text, ordering 및 기타 읽기 parameters를 담을 수 있습니다.
• Projection: 도메인 엔티티를 직접 노출하지 않고 필요한 필드만 가진 DTO 또는 view model을 반환해야 합니다.
• 부작용 없음: 상태를 변경하는 메서드를 호출하거나 database에 변경 사항을 저장해서는 안 됩니다.

Query를 만들어야 하는 경우

• 작업이 데이터를 읽고 상태를 변경해서는 안 될 때 Query를 사용합니다.
• 상세 화면, 식별자 검색, availability checks 또는 단일 객체 응답에는 단일 결과 Query를 사용합니다.
• grids, option lists, child collections, selection controls에는 list Query를 사용합니다.
• grids 및 잠재적으로 큰 데이터 세트에는 pagination을 사용합니다.
• 작은 reference data, enumerations, options endpoints에는 단순 lists를 사용합니다.

Query Validators

Query Validators는 filters, pagination values, date ranges, identifiers, visibility rules 같은 입력 parameters를 검증합니다. 이들도 FluentValidation으로 구현됩니다.

Queries의 일반적인 검증 규칙

• 시작일과 종료일 같은 range filters에는 GreaterThanOrEqualTo 및 LessThanOrEqualTo.
• 이름, email, search term 같은 text filters에는 Length, MaximumLength, MinimumLength.
• page 및 pageSize를 제한하는 pagination에는 InclusiveBetween.
• detail queries의 필수 identifiers에는 NotEmpty.
• 종료일이 시작일보다 빠른 경우처럼 잘못된 filter 조합에는 Must.

Query Handlers

Query Handler는 repositories 또는 database context를 조회하고 최적화된 projections를 반환합니다. Lino에서는 적절할 때 Select를 사용한 projections, 명시적 filters, 예측 가능한 ordering, no-tracking reads를 권장합니다.

Query handler는 read-only여야 합니다. 상태를 변경하는 도메인 메서드를 호출하지 않고, 영속 변경을 발생시키지 않으며, SaveChanges를 실행하지 않습니다. 읽기 작업이 audit을 기록하거나 integration을 시작하거나 상태를 재계산해야 한다면, 이는 보통 다른 use case 또는 별도 process가 필요하다는 신호입니다.

Query Results

Lino에서 Queries의 결과는 QueryResult suffix가 붙은 records로 표현됩니다. 이 convention은 단일 응답, 단순 list, paginated list, 또는 화면, API, integration, background process용 특정 DTO 모두에 적용됩니다.

query results는 안정적인 read contracts여야 합니다. 도메인 엔티티를 직접 노출하기 위한 shortcut이 아니라 consumer를 위해 설계된 DTOs로 다루세요.

CLI로 Query 만들기

Commands와 비슷하게 Lino는 다음 command를 제공합니다:

lino query new

CLI는 다음과 같은 옵션도 허용합니다:

lino query new --service <ServiceName> --module <ModuleName> --entity <EntityName> --name <QueryName>
lino query new --name <QueryName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino query list --service <ServiceName> --module <ModuleName> --entity <EntityName>

• -s 또는 --service: 대상 서비스.
• -m 또는 --module: 대상 모듈.
• -e 또는 --entity: Query와 연결된 엔티티.
• -n, --name, -q 또는 --query: Query 이름.

대화형 흐름 중 Lino는 Query가 단일 결과를 반환하는지 list를 반환하는지 묻습니다. 응답이 list이면 pagination이 필요한지도 묻습니다. 마지막으로 반환되거나 생성된 projection에서 사용될 속성을 선택할 수 있게 합니다.

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

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

Queries용 생성 구조 예시

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Application/
                ├── <ProjectName>.<ServiceName>.Application.csproj
                └── UseCases/
                    └── Orders/
                        ├── Commands/
                        |   └── ...
                        └── Queries/
                            └── GetOrderById/
                                ├── GetOrderByIdQuery.cs
                                ├── GetOrderByIdQueryValidator.cs
                                ├── GetOrderByIdQueryHandler.cs
                                └── GetOrderByIdQueryResult.cs

Vehicle availability용 사용자 지정 Query도 같은 패턴을 따릅니다:

Application/UseCases/Vehicles/Queries/GetVehicleAvailability/
├── GetVehicleAvailabilityQuery.cs
├── GetVehicleAvailabilityQueryValidator.cs
├── GetVehicleAvailabilityQueryHandler.cs
└── GetVehicleAvailabilityQueryResult.cs

Query 파일의 책임

• Query: identifiers, filters, ordering, pagination 또는 date ranges를 담는 불변 요청 contract.
• Validator: identifiers, pagination, required filters, date ranges, search criteria 검증.
• Handler: application context, projections, filters, ordering, pagination, logging, tracing, 결과 생성을 사용한 read orchestration.
• Result: caller를 위해 모델링된 response DTO이며, list items를 위한 내부 records를 자주 포함합니다.

구현 체크리스트

1. lino query new를 실행하고 서비스, 모듈, 엔티티, Query 이름, 반환 타입, pagination mode, 속성을 선택합니다.
2. 요청 contract를 검토하고 caller에게 실제로 필요한 filters만 유지합니다.
3. 특히 필수 identifiers, date ranges, page size limits, 잘못된 filter 조합에 대해 validator를 강화합니다.
4. handler projection을 조정해 UI, API, integration 또는 background process가 요구하는 필드만 반환하게 합니다.
5. Query를 read-only로 유지합니다. 상태를 변경하는 도메인 메서드를 호출하지 않고 handler에서 변경 사항을 저장하지 않습니다.
6. 적절할 때 기존 표준 오류를 사용해 예상된 실패를 Result로 전파합니다.
7. API endpoint, Blazor page, in-process integration 또는 typed client처럼 Query를 호출하는 consumer를 컴파일하고 테스트합니다.

사용자 지정 Query 예시

SaaS의 모듈 간 integration 흐름에서는 lino query new로 vehicle availability에 대한 사용자 지정 Query를 만들 수 있습니다. 생성된 구조는 Query, Handler, Result, Validator를 제공합니다. 그 다음 개발자는 vehicle identifier, start date, end date 같은 필요한 입력을 추가하고, range가 올바른지 검증하고, handler logic을 구현합니다. 이것이 기대되는 흐름입니다. 먼저 일관된 구조를 생성한 뒤 명시적인 코드로 도메인별 동작을 완성합니다.

결론

Lino에서 use cases를 정의한다는 것은 도메인 모델을 명확한 애플리케이션 작업으로 바꾸는 것입니다. Commands는 상태 변경을 처리하고, Queries는 읽기를 처리하며, validators는 입력 경계를 보호하고, handlers는 흐름을 오케스트레이션하며, 결과 객체는 출력을 표준화합니다.

가장 빠른 흐름은 보통 도메인을 모델링하고, 필요한 Commands와 Queries를 생성하고, 생성된 파일을 검토하고, 비즈니스 동작을 완성하고, 필요할 때 API 또는 page로 use case를 노출한 뒤 build와 tests로 모두 검증하는 것입니다. 이렇게 하면 architectural control을 잃지 않으면서 개발 속도를 유지할 수 있습니다.

프로젝트가 커질수록 각 use case를 하나의 비즈니스 의도에 집중시키고, 서비스와 모듈 경계를 존중하며, 다른 모듈이 프로세스에 참여해야 할 때는 이벤트, 통합 또는 shadow entities를 사용합니다.