API 개발

Lino의 Minimal APIs

Lino는 ASP.NET 코어를 채택합니다. Minimal APIs Clean Architecture의 경계를 깨지 않으면서 코드를 직접적이고 명시적이며 성능을 유지하기 때문에 endpoint 생성을 위한 표준으로 사용됩니다.

현재 Lino 프로젝트에서 생성된 endpoint는 구현하는 Minimal APIs 클래스입니다. IEndpoint. 각 endpoint는 정적 메서드를 노출합니다. MapEndpoint(IEndpointRouteBuilder app) 그리고 다음을 사용하는 핸들러 메소드 ISender 생성된 명령이나 쿼리를 애플리케이션 계층으로 전달합니다.

생성된 주요 부품

• *Endpoint.cs: 매핑 방법 HTTP, 경로, 메타데이터, 권한 부여, 테넌트 요구 사항, 속도 제한 및 버전.
• *Request.cs: 본문, 쿼리 문자열, 경로 매개변수 또는 양식 데이터에서 나오는 입력을 나타냅니다.
• *Extensions.cs: 요청을 명령/쿼리로 변환하고 애플리케이션 결과를 응답 HTTP로 변환합니다.
• *Response.cs: 끝점과 형식화된 클라이언트에서 반환된 강력한 형식의 contracts을 정의합니다.

내장된 기능

Lino는 다음을 사용합니다. TypedResults 그리고 Results<...> 성공 및 오류 응답이 코드에 명시적으로 표시되고 OpenAPI에 올바르게 표시됩니다. 응용 프로그램 계층에서 발생하는 오류는 다음으로 변환됩니다. ProblemDetails 놓다 result.MapToProblemDetails().

• WithTags: OpenAPI 및 Scalar의 모듈, 엔터티 또는 기능별로 endpoint를 그룹화합니다.
• WithName: 해당하는 경우 일관된 OperationId를 설정합니다.
• WithSummary: endpoint의 목적을 명확하게 설명합니다.
• Produces(statusCode, schema): 상태 코드와 응답 contracts을 지정합니다.
• MapToApiVersion(1, 0): endpoint를 API 버전과 연결합니다.
• RequirePermission, RequireAuthorization, AllowAnonymous 그리고 RequireTenant: 프로젝트 옵션에 따라 보안을 적용합니다.
• 구성에 따라 인증된 정책이나 익명 정책을 사용하여 그룹 또는 endpoint 수준에서 속도를 제한합니다.

요청과 응답

기본적으로 Lino는 다음을 사용합니다. 기록 요청과 응답을 위해. 이는 간결하고 기본적으로 변경할 수 없으며 API, 형식화된 클라이언트 및 외부 소비자 간의 명시적 contracts으로 잘 작동합니다.

• endpoint를 통해 수신된 요청은 명령 또는 쿼리로 변환됩니다.
• 명령이나 쿼리의 결과는 응답으로 변환됩니다.
• 도메인 엔터티는 contracts HTTP로 직접 노출되어서는 안 됩니다.

public record CreatePersonRequest(string Name, int Age);
public record CreatePersonResponse(Guid Id, string Name, int Age);

새 API 생성

도메인 모델과 사용 사례가 이미 HTTP에 의해 노출될 만큼 명확할 때 CLI로 API를 생성합니다. API는 Minimal APIs, contracts, typed responses 및 문서 메타데이터를 통해 명령과 쿼리를 프레젠테이션 계층에 연결합니다.

lino api new
lino api new --name <ApiName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino api list --service <ServiceName> --module <ModuleName> --entity <EntityName>

대화형 마법사는 다음 메시지를 표시합니다.

• 서비스: API가 생성될 서비스입니다.
• 기준 치수: 해당되는 경우 서비스 모듈입니다.
• 엔터티 또는 열거형: 끝점과 연결된 도메인 요소입니다.
• API의 이름: 일반적으로 다음과 같은 작업의 동사와 정렬됩니다. CreatePerson.
• 작업 유형: GET, POST, PUT, PATCH, DELETE, 업로드, 다운로드 또는 endpoint 옵션.
• 노선:경로 패턴, 예: /people/{id:guid}.
• 속성: 실제로 HTTP 경계를 넘어야 하는 요청 및 응답 필드입니다.

마법사가 구성할 수 있는 사항

• 얻다: 단일 결과, 목록, 페이지 목록 및 옵션/선택 시나리오.
• 우편: 명령 유형 및 선택한 속성을 포함한 생성 및 비즈니스 작업입니다.
• 놓다 그리고 반점: 전체 또는 부분 업데이트.
• 삭제: 제거는 삭제 명령에 매핑됩니다.
• 업로드: 끝점 IFormFile 그리고 DisableAntiforgery() 필요할 때.
• 다운로드:endpoint 반환 FileStreamHttpResult; 인증된 프로젝트는 안전한 파일 액세스를 위해 토큰 endpoint를 생성할 수 있습니다.
• 열거: 생성된 쿼리 및 응답별로 유효한 옵션을 노출하는 endpoint입니다.

권장 흐름

1. 사용 사례를 나타내는 엔터티, 명령 및 쿼리를 생성하거나 검토합니다.
2. 달리다 lino api new 올바른 서비스, 모듈 및 엔터티를 선택합니다.
3. 원하는 HTTP 동사뿐만 아니라 사용 사례별로 작업 유형을 선택하세요.
4. 다음과 같은 제약 조건을 사용하여 안정적인 경로를 정의합니다. {id:int} 또는 {id:guid} 적절한 경우.
5. HTTP 경계를 넘어야 하는 속성만 선택하세요.
6. 승인, 권한, 테넌트 요구 사항, 속도 제한 및 예상 상태 코드를 정의합니다.
7. 빌드를 실행하고 Scalar/OpenAPI를 검사하여 생성된 경로, 요약, 버전, 보안 및 응답을 확인합니다.

예: CreatePerson

API를 생성할 때 POST 부르다 CreatePerson, 엔터티와 연결됨 Person, CLI는 endpoint, request/response contracts, 매핑 확장, OpenAPI 메타데이터 및 해당 명령과의 통합을 생성합니다.

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Api/
                └── Endpoints/
                    └── People/
                        └── CreatePerson/
                            ├── CreatePersonEndpoint.cs
                            ├── CreatePersonExtensions.cs
                            ├── CreatePersonRequest.cs
                            └── CreatePersonResponse.cs

contracts서 및 typed clients

프로젝트에 웹 앱 Blazor가 있는 경우 Lino는 API의 형식화된 소비를 위한 아티팩트(공유 contracts, 클라이언트 인터페이스 및 HTTP 구현)도 생성합니다. 이를 통해 Blazor는 간단하고 일관되며 강력한 형식의 방식으로 endpoint를 사용할 수 있습니다.

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            ├── Api.Contracts/
            │   └── Features/
            │       └── People/
            │           ├── CreatePerson/
            │           │   ├── CreatePersonRequest.cs
            │           │   └── CreatePersonResponse.cs
            │           └── IPersonApiClient.cs
            └── Api.Client/
                └── Features/
                    └── PersonApiClient.cs

클라이언트 인터페이스는 종속성 주입을 위해 등록되었으며 구현에서는 다음을 사용합니다. HttpClientProvider Tolitech의 HTTP 도우미를 사용하여 강력한 형식의 방식으로 생성된 API를 호출합니다.

출판 전 체크리스트

• 사용 GET 독서를 위해, POST 생성/작업을 위해, PUT/PATCH 변화를 위해 그리고 DELETE 의미가 있을 때 제거합니다.
• 도메인 엔터티를 외부 contracts으로 직접 노출하지 마세요.
• 문서 유효성 검사, 충돌, 찾을 수 없음 및 액세스 거부 오류.
• 사용 api list 동일한 사용 사례에 대해 중복 경로나 경쟁 endpoint를 방지합니다.

Source Generators로 endpoint 등록

Lino는 Source Generators를 사용하여 대용량 파일을 수동으로 매핑하는 것을 방지합니다. 끝점을 하나씩 나열하는 대신 Program.cs, 컴파일 중에 로그가 생성됩니다.

생성된 endpoint 클래스 구현 IEndpoint ~의 Tolitech.MinimalApis.Generators.Abstractions. endpoint 그룹 호출 MapEndpointsGenerated(), 제작사: Tolitech.MinimalApis.Generators, 생성된 코드를 통해 새 endpoint가 등록됩니다.

이것이 왜 중요한가요?

• 수동 배선 감소: 개발자는 각 endpoint를 수동으로 매핑하는 것을 기억할 필요가 없습니다.
• 컴파일 시간 일관성: endpoint는 동일한 구조를 따르며 생성된 코드에 의해 검색됩니다.
• 클리너 시작: Program.cs 서비스, ​​미들웨어 및 확장 방법 구성을 위한 설정을 위임합니다.
• AOT 호환성: 런타임 시 리플렉션에 대한 종속성을 줄입니다.
• OpenAPI 일관성: 태그, 요약, 상태 코드 및 버전이 endpoint에서 생성됩니다.
• 아키텍처 정렬: HTTP는 API에 있고, 오케스트레이션은 MediatR을 통해 이루어지며, contracts은 클라이언트와 공유될 수 있습니다.

런타임 시 흐름

1. Program.cs 애플리케이션을 빌드하고 서비스 또는 모듈 endpoint에서 확장을 호출합니다.
2. 확장은 API 버전 세트와 endpoint 그룹을 생성하고 권한 부여/속도 제한을 적용하고 호출합니다. MapEndpointsGenerated().
3. 생성된 매퍼는 메소드를 호출합니다. MapEndpoint 각 endpoint의
4. 각 끝점은 경로, OpenAPI 메타데이터, 권한, 테넌트 요구 사항 및 처리기를 매핑합니다.
5. 핸들러는 입력 HTTP를 수신하고 이를 명령/쿼리로 변환한 후 MediatR로 보내고 형식화된 결과를 반환합니다.

오류 정의

오류 정의는 알려진 도메인 및 애플리케이션 오류를 표준화합니다. 이는 API, 처리기, 로그 및 프런트엔드가 각 끝점에서 길 잃은 메시지, 중복 문자열 또는 임시 결정에 의존하지 않고 예측 가능한 문제를 처리하는 데 도움이 됩니다.

lino error-definition new --name <ErrorDefinitionName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino error-definition list --service <ServiceName> --module <ModuleName> --entity <EntityName>

생성된 API에서 명령 및 쿼리에 의해 반환된 예상 오류는 다음으로 변환되어야 합니다. ProblemDetails 상태 코드, 오류 코드 및 보안 메시지가 포함되어 있습니다. 서버는 자세한 기술 로그를 기록할 수 있지만 HTTP 응답은 일관되고 안전하며 현지화 가능해야 합니다.

모범 사례

• 예상되고 재사용 가능한 오류에 대한 오류 정의를 만듭니다.
• 기술적 예외나 인프라 세부정보를 클라이언트에 반환하지 마세요.
• 프런트엔드, 입력된 클라이언트 및 테스트가 안전하게 반응할 수 있도록 안정적인 오류 코드를 유지하세요.
• endpoint가 생성할 수 있는 상태 코드를 OpenAPI에 문서화합니다.
• 공개 응답에서 진단 세부정보 및 보안 메시지를 확인하려면 서버 측 로그를 사용하세요.