API 개발

Minimal APIs

Lino는 엔드포인트 생성 시 기본적으로 Minimal API 스타일을 사용하며, 다음을 우선시합니다:

• 명확성 – 간결하고 직관적이며 표현력이 있는 코드.
• 성능 – 불필요한 오버헤드 없이 최적화된 응답.

통합 기능

TypedResults: 강력한 타입의 응답을 보장하여 가독성과 OpenAPI 생성에 도움을 줍니다.

API 버전 관리: 엔드포인트는 호환성을 깨지 않고 확장할 수 있습니다.

풍부한 문서화: 구성 가능한 메타데이터가 OpenAPI에 직접 포함되며, 다음을 포함합니다:

• WithTags → OpenAPI에서 엔드포인트를 논리적 섹션으로 그룹화합니다.
• WithName → operationId를 일관되게 정의합니다.
• WithSummary → 엔드포인트 목적을 명확히 설명합니다.
• Produces(statusCode, schema) → 상태 코드와 응답 계약을 지정합니다.
• MapToApiVersion → 동일한 엔드포인트의 다른 버전을 노출할 수 있습니다.

Requests 및 Responses

Record classes는 기본적으로 Requests와 Responses에 사용됩니다:

• 불변(부작용과 버그 감소)
• 간결하고 읽기 쉬움

CQRS와의 통합:

• 엔드포인트를 통해 수신된 요청은 Commands 또는 Queries로 변환됩니다.
• Commands/Queries의 결과는 Responses로 변환되어 아키텍처 일관성을 유지합니다.

간단한 예:
public record CreatePersonRequest(string Name, int Age);
public record CreatePersonResponse(Guid Id, string Name, int Age);

새로운 API 만들기

Lino CLI를 사용하여 엔드포인트를 만드는 것은 매우 간단합니다:

lino new api

대화형 마법사가 다음을 요청합니다:

• 서비스 – API가 생성될 서비스.
• 모듈 – 서비스의 모듈(해당되는 경우).
• 엔터티 – 엔드포인트와 연결된 엔터티.
• API 이름 – 일반적으로 작업 동사와 일치 (예: CreatePerson).
• 작업 유형 – POST, PUT, PATCH, DELETE 또는 GET.
• 라우트 – 라우트 패턴 (예: /people/{id}).

예시:

Person 엔터티와 연결된 CreatePerson이라는 POST API를 생성하면, CLI는 자동으로 다음을 생성합니다:

• HTTP 매핑이 포함된 엔드포인트.
• 요청/응답 DTO.
• OpenAPI 통합 및 버전 관리를 위한 확장.
• 다른 서비스에서 내부적으로 사용할 수 있는 타입 지정 HttpClient.

생성된 구조:

MyApp/
└── src/
    ├── Services/
    │   └── MyService/
    │       └── Presentation.API/
    │           ├── MyApp.MyService.Presentation.API.csproj
    │           └── Endpoints/
    │               └── People/
    │                   └── CreatePerson/
    │                       ├── CreatePersonEndpoint.cs
    │                       ├── CreatePersonExtensions.cs
    │                       ├── CreatePersonRequest.cs
    │                       └── CreatePersonResponse.cs
    └── Integrations/
        └── MyService/
            └── Http/
                ├── Contracts/
                │   └── Apis/
                │       └── People/
                │           ├── IPersonHttpClient.cs
                │           └── CreatePerson/
                │               ├── CreatePersonRequest.cs
                │               └── CreatePersonResponse.cs
                └── Clients/
                    └── Apis/
                        └── PersonHttpClient.cs

Source Generators를 사용한 엔드포인트 등록

Lino는 엔드포인트를 수동으로 매핑하거나 런타임에 Reflection을 많이 사용하는 필요성을 제거합니다.
대신, Source Generators를 사용하여 컴파일 시 자동으로 등록 코드를 생성합니다.

작동 방식

생성된 각 엔드포인트에 대해 제너레이터는 MapGet, MapPost, MapPut, MapDelete 등 호출하는 클래스/부분 클래스를 생성합니다.

이는 Program.cs에 모든 매핑을 수동으로 추가할 필요를 대체합니다.

장점:

• 컴파일 타임 등록 → 런타임 오류 방지.
• 간결한 Program.cs → 수동 구성 범위 감소.
• AOT 호환성 → Reflection 의존성 제거.
• 통합 문서 → 메타데이터(tags, summary, produces)가 매핑과 함께 생성됨.

이 모델은 Lino에서 생성된 API가 다음을 보장합니다:

• 자동 문서화
• 높은 성능
• 프레임워크의 CQRS 아키텍처와 일치