Aqueduct란?
개념(Concepts)
자원(Resources)
자원은 응용프로그램(Application)이 HTTP API를 통해 제공하는 것입니다.
자원은 응용프로그램의 사용자 프로필, 남극 대륙의 온도 센서, 게임의 최고 점수 등등 어떤 것이든 될 수 있습니다.
예를들어 GitHub API의 경우 organization, repository, issue, pull request를,
소셜 네트워크 API의 경우 프로필, 게시물, 유저 관계를 제공합니다.
자원은 컬렉션(예 : 모든 게시물)으로 구성되어 해당 컬렉션 내의 개별 리소스(예 : 단일 게시물)를 고유하게 식별 할 수 있습니다.
자원의 상태를 검색하거나, 자원의 원하는 상태를 제공하기위해 응용프로그램에 요청(Request)합니다.
대부분의 경우, 자원은 JSON 배열 및 개체로 표시됩니다.
자원을 검색할 때 JSON 표현은 response body로 인코딩 됩니다.
자원의 원하는 상태를 제공할 때 클라이언트는 바라는 자원의 상태를 JSON 표현이 들어있는 request body를 보냅니다.
자원의 개념에대한 자세한 내용은 HTTP/1.1에 대한 RFC Specification을 참조
라우팅(Routing)
자원은 HTTP 요청의 경로로 식별됩니다.
예를들어 URL : http://example.com/organizations 은 http://example.com 의 조직 자원 컬렉션을 식별합니다.
URL : http://example.com/organizations/1은 단일 조직을 식별합니다.
응용 프로그램은 관리하는 각각의 리소스의 경로를 제공합니다.
경로(Route)는 Request Path와 일치하는 문자열입니다. Request Path가 경로와 일치하면 요청을 처리하기 위해 연관된 핸들러가 호출됩니다.
경로는 Path처럼 보이지만 몇가지 추가 구문이 있습니다.
예를들어 /organizations 경로는 /organizations의 Request Path와 일치시킵니다.
/organizations/:id 경로는 /organizations/1, /organizations/2등과 일치합니다.
추가 구문으로 복잡한 경로를 구성 할 수 있습니다. 자세한 사용법은 라우팅 가이드를 참조.
컨트롤러(Controllers)
컨트롤러는 요청을 처리하는 개체입니다.
예를들어 컨트롤러가 데이터베이스의 행을 가져와서 response body에 넣어 클라이언트에게 보낼 수 있습니다.
다른 컨트롤러가 요청의 Authorization Header의 사용자 이름 및 암호가 유효한지 확인할 수 있습니다.
컨트롤러는 서로 연결되어 요청에 대해 수행할 일련의 작업을 구성합니다.
이러한 서로 연결된 컨트롤러를 채널이라고 합니다. 위의 예제가 함께 연결된 경우 채널은 데이터베이스 행을 포함하는 응답(response)을 보내기전에 요청이 승인되었는지 확인합니다.
컨트롤러에는 두가지가 있습니다.
-
엔드포인트 컨트롤러(Endpoint Controller) : 자원 혹은 자원 컬렉션에서 작업을 수행하고, 항상 응답을 보냅니다. 자원 상태를 반환하거나 자원 상태를 변경하여 요청을 처리합니다.
-
미들웨어 컨트롤러(Middleware Controller) : 요청에 대한 조치를 취하지만 요청을 이행하지 않습니다. 여러가지 다양한 작업을 수행할 수 있으며 여러 채널에서 재사용할 수 있는 경우가 많습니다.
대부분의 경우 요청에 대한 유효성을 검사한 후 엔드포인트 컨트롤러에 도달하게 됩니다.
미들웨어 컨트롤러는 요청에 대한 응답을 보낼 수 있으며 이렇게하면 해당 채널의 다른 컨트롤러가 요청을 처리하지 못하게됩니다.
채널에는 엔드포인트 컨트롤러가 하나만 있어야 합니다. 0개 이상의 미들웨어 컨트롤러가 선행될 수 있습니다.
자세한 사용 정보는 컨트롤러 및 리소스 컨트롤러 가이드를 참조
Application Channel
Application Channel은 응용 프로그램의 모든 컨트롤러를 포함하는 개체입니다.
이것은 진입점(Entry Point)이라고 불리는 모든 요청을 수신하는 첫번째 컨트롤러를 지정합니다.
컨트롤러들은 진입점(직접적으로 혹은 간접적으로) 연결되어 전체 Application Channel을 구성합니다.
거의 모든 응용프로그램에서 진입점은 라우터이며, 이 컨트롤러는 이 컨트롤러는 지정된 경호에 대한 하위 채널로 채널을 분할합니다.
또한 Application Channel은 응용 프로그램의 서비스 초기화, 구성 파일 읽기 및 기타 시작 관련 작업도 담당합니다.
자세한 내용은 Application Channel의 가이드를 참조
서비스(Services)
서비스는 복잡한 작업 또는 알고리즘, 외부 통신, 응용 프로그램에서 재사용되는 작업을 캡슐하는 개체입니다. 서비스 개체의 목적은 복잡한 동작에 대한 간단한 인터페이스를 제공하는 것입니다. 예를들어 데이터베이스 연결은 서비스 개체입니다.
데이터베이스 연결 사용자는 연결 방법이나 쿼리를 와이어에 인코딩하는 방법에 대한 세부 정보를 알 수 없지만 쿼리를 실행할 수 있습니다.
서비스 개체의 주 사용자는 컨트롤러입니다. 서비스는 컨트롤러의 생성자에 인수로 전달되어 컨트롤러에 주입됩니다. 컨트롤러는 요청을 처리할 때 사용할 수 있도록 서비스에 대한 참조를 유지합니다.
서비스 주입에 대한 자세한 내용은 Application Channel의 가이드를 참조.
Isolates
Isolates는 메모리 격리 스레드입니다. 하나의 Isolates에서 생성된 개체는 다른 Isolates에서 참조할 수 없습니다.
응용 프로그램이 시작될 때 코드의 복제본이 포함된 하나 이상의 Isolates가 생성됩니다.
이 동작은 여러 스레드에서 응용 프로그램을 효과적으로 로드밸런싱합니다.
이 구조의 이점은 각 Isolates에서 데이터 베이스 연결과 같은 서비스의 자체 집합을 가지는 것입니다.
전체 응용프로그램이 효과적으로 풀링되기 때문에 데이터 베이스 연결 풀링기법이 필요하지 않습니다.
바인딩(Bindings)
요청에는 컨트롤러 코드에서 구문 분석, 분석되어야하는 경로 매개변수, 바디, 쿼리 매개변수 헤더 등이 포함될 수 있습니다. 바인딩은 이 구문 분석 및 검증을 자동으로 수행하는 변수에 추가된 어노테이션입니다. 바인딩 된 값을 예상 유형으로 구문 분석할 수 없거나 유효성 검사가 실패할 경우 적절한 오류 응답이 전송됩니다.
바인딩은 보일러 플레이트 코드를 줄이고 테스트 범위(serface)를 줄여 개발 속도를 높이고 코드를 추론하기 쉽게 만듭니다. 바인딩에 대한 자세한 내용은 리소스 컨트롤러에 대한 가이드를 참조
쿼리 및 데이터 모델(Queries and Data Models)
응용 프로그램은 지속성을 위해 정보를 데이터베이스에 저장합니다.
손으로 데이터베이스 쿼리를 작성하는 것은 오류가 발생하기 쉬우며 Dart 응용 프로그램에서 매우 중요한 정적 분석 도구를 활용하지 않습니다.
Aqueduct의 객체 관계형 매핑(ORM : Object-Relational Mapping)은 작성 및 테스트하기 쉬운 정적 타입의 쿼리를 제공합니다.
응용 프로그램의 데이터 모델은 Dart 클래스를 생성하여 정의됩니다. 각 클래스는 데이터 베이스 테이블에 매핑되고, 해당 클래스의 각 속성은 테이블의 열에 매핑됩니다.
Aqueduct의 명령 줄 도구는 데이터 모델의 변경 사항을 감지하여 라이브 버전 데이터베이스에 적용할 수 있는 데이터베이스 마이그레이션 파일을 생성합니다.
데이터 모델은 또한 응용 프로그램 상단에 빌드 도구에 JSON 개체로 표현될 수 있습니다.
자세한 내용은 데이터베이스가이드를 참조.
권한 부여(Authorization)
OAuth 2.0은 표준화된인증 프레임워크 입니다. Aqueduct는 응용 프로그램에 직접 통합되거나 단독으로 작동하여 연합 서비스를 위한 권한 부여 서버를 제공하는 OAuth2.0 서버의 규격 준수 구현(specification-compliant implementation)이 포함되어 있습니다.
구현은 쉽게 사용자 정의할 수 있습니다. 토큰 및 클라이언트 식별자와 같은 인증 아티팩트를 다른 유형의 데이터베이스에 저장하거나 JWT같은 상태 비 저장 인증 메커니즘을 사용할 수 있습니다.
기본 구현은 Aqueduct ORM을 활용하여 PostgreSQL에 아티팩트를 저장합니다.
자세한 내용은 권한 부여가이드를 참조.
문서화(Documentation)
OpenAPI 3.0은 HTTP API에 대한 표준화 된 문서화 방식입니다.
많은 Aqueduct의 내장 객체들은 자동 문서화를 지원합니다.
응용 프로그램에 고유한 개체는 이를 기반으로 빌드하여 모든 변경 사항에 대해 응용프로그램을 즉시 문서화 할 수 있습니다.
자세한 내용은 OpenAPI 문서화가이드를 참조.
참조
https://aqueduct.io/docs/core_concepts/
후기
페이지에 있는 영어를 눈으로만 보면 제대로 이해가 안되서 Google번역기와 Papago를 이용해서 번역해봤다. 원래도 아는 지식이 많지는 않다고 생각했지만 생각보다 모르는 영어 단어, 개발 용어들이 많았다.
다음에는 Dart를 설치하고 Aqueduct 환경 세팅을 진행해야지
