그럼 RAML인가요 아니면 OAS(Swagger)인가요?

마이크로서비스의 역동적인 세계에서는 무엇이든 바뀔 수 있습니다. 모든 구성 요소는 다양한 프레임워크와 아키텍처를 사용하여 다른 언어로 다시 작성될 수 있습니다. 내부 변형에 관계없이 마이크로서비스가 외부에서 영구적으로 상호 작용할 수 있도록 계약만 변경되지 않은 상태로 유지되어야 합니다. 그리고 오늘 우리는 계약을 설명하는 형식을 선택하는 문제에 대해 이야기하고 우리가 찾은 아티팩트를 공유할 것입니다.

게시물 준비됨 안나 멜레코바 и 블라디미르 라파틴

마이크로서비스. Acronis Cyber ​​Cloud를 개발하면서 우리는 그것들에서 벗어날 수 없다는 것을 깨달았습니다. 그리고 마이크로서비스의 인터페이스를 나타내는 계약을 공식화하지 않고서는 마이크로서비스를 설계하는 것이 불가능합니다.

그러나 제품에 두 개 이상의 구성 요소가 포함되어 있고 계약 개발이 일상적인 활동이 되면 프로세스 최적화에 대해 생각하지 않을 수 없습니다. 인터페이스(계약)와 구현(마이크로서비스)이 서로 일치해야 하고, 서로 다른 구성 요소가 동일한 작업을 동일한 방식으로 수행해야 하며, 이러한 모든 결정에 대한 중앙 집중식 의사 결정이 없으면 각 팀은 다음을 수행해야 한다는 것이 분명해집니다. 그것들을 얻기 위해 계속해서 시간을 보내십시오.

Amazon 마이크로서비스 다이어그램 짹짹 베르너 보겔리스(Werner Vogelis) 아마존 CTO
딜레마는 무엇입니까? 실제로 마이크로서비스와 상호작용하는 방법에는 HTTP Rest와 Google의 gRPC 두 가지가 있습니다. Google의 기술 스택에 얽매이고 싶지 않기 때문에 우리는 HTTP Rest를 선택했습니다. HTTP REST 계약 주석은 이전에 Swagger로 알려진 RAML 및 OAS의 두 가지 형식 중 하나로 가장 자주 설명되므로 모든 개발 팀은 표준 중 하나를 선택해야 하는 상황에 직면합니다. 그러나 결과적으로 이러한 선택을 하는 것은 매우 어려울 수 있습니다.

주석이 필요한 이유는 무엇입니까?

외부 사용자가 HTTP 인터페이스를 통해 서비스로 수행할 수 있는 작업을 쉽게 파악할 수 있도록 주석이 필요합니다. 즉, 기본 수준에서 주석에는 최소한 사용 가능한 리소스 목록, 해당 HTTP 메서드, 요청 본문, 매개변수 목록, 필수 및 지원되는 헤더 표시, 반환 코드 및 응답 형식이 포함되어야 합니다. 계약 주석의 매우 중요한 요소는 구두 설명입니다("이 쿼리 매개변수를 요청에 추가하면 어떻게 될까요?", "어떤 경우에 코드 400이 반환됩니까?").

그러나 다수의 마이크로서비스를 개발하는 경우에는 작성된 주석에서 추가 가치를 추출하려고 합니다. 예를 들어 RAML/Swagger를 기반으로 수많은 프로그래밍 언어로 클라이언트 및 서버 코드를 모두 생성할 수 있습니다. 마이크로서비스에 대한 문서를 자동으로 받아 개발자 포털에 업로드할 수도 있습니다. :)

구조화된 계약 설명의 예

계약 설명을 기반으로 마이크로서비스를 테스트하는 관행은 덜 일반적입니다. 주석과 구성 요소를 모두 작성한 경우 다양한 유형의 입력 데이터로 서비스의 적합성을 확인하는 자동 테스트를 만들 수 있습니다. 서비스가 주석에 설명되지 않은 응답 코드를 반환합니까? 명백히 잘못된 데이터를 올바르게 처리할 수 있을까요?

또한 계약 자체뿐만 아니라 주석 시각화 도구의 고품질 구현을 통해 마이크로서비스 작업을 단순화할 수 있습니다. 즉, 아키텍트가 고품질의 계약서를 기술했다면, 이를 바탕으로 디자이너와 개발자는 추가 시간 비용 없이 다른 제품에 서비스를 구현하게 된다.

추가 도구를 활성화하기 위해 RAML과 OAS 모두 표준에서 제공하지 않는 메타데이터를 추가하는 기능이 있습니다(예를 들어, 이것이 OAS에서 수행되는 방식입니다.).

일반적으로 마이크로서비스 계약을 사용할 때 창의성의 범위는 엄청납니다...적어도 이론상으로는 말이죠.

고슴도치와 뱀의 비교

현재 Acronis의 우선 개발 영역은 Acronis Cyber ​​​​플랫폼 개발입니다. Acronis Cyber ​​​​플랫폼은 Acronis Cyber ​​​​Cloud 및 에이전트 부분과 타사 서비스를 통합하는 새로운 지점입니다. RAML에 설명된 내부 API에 만족했지만 API를 다시 게시해야 했기 때문에 선택에 대한 질문이 제기되었습니다. 작업에 가장 적합한 주석 표준은 무엇입니까?

처음에는 두 가지 솔루션이 있는 것처럼 보였습니다. 가장 일반적인 개발은 RAML과 Swagger(또는 OAS)였습니다. 그러나 실제로는 적어도 2개의 대안이 아니라 3개 이상의 대안이 있는 것으로 밝혀졌습니다.

한편으로는 강력하고 효율적인 언어인 RAML이 있습니다. 계층 구조와 상속을 잘 구현하므로 이 형식은 설명이 많이 필요한 대기업, 즉 하나의 제품이 아니라 계약의 공통 부분(인증 체계, 동일한 데이터 유형, 오류 본문)이 있는 많은 마이크로서비스에 더 적합합니다. .

그러나 RAML의 개발자인 Mulesoft가 Open API 컨소시엄에 합류했습니다. 멋진. 따라서 RAML은 개발을 중단했습니다. 이벤트의 형식을 상상해 보려면 주요 Linux 구성 요소의 유지 관리 담당자가 Microsoft에서 일하기 위해 떠났다고 상상해 보세요. 이러한 상황은 동적으로 개발되고 있는 Swagger를 사용하기 위한 전제 조건을 생성하며 최신 세 번째 버전에서는 유연성과 기능 측면에서 실질적으로 RAML을 따라잡습니다.

한가지만 아니라면...

알고 보니 모든 오픈 소스 유틸리티가 OAS 3.0으로 업데이트된 것은 아닙니다. Go의 마이크로서비스에서 가장 중요한 것은 적응력이 부족하다는 것입니다. 허풍쟁이 최신 버전의 표준에 대한 것입니다. 그러나 Swagger 2와 Swagger 3의 차이점은 다음과 같습니다. 거대한. 예를 들어, 세 번째 버전에서 개발자는 다음을 수행합니다.

• 인증 체계에 대한 설명 개선
• 완료 JSON 스키마 지원
• 예시 추가 기능 업그레이드

상황은 재미있습니다. 표준을 선택할 때 RAML, Swagger 2 및 Swagger 3을 별도의 대안으로 고려해야 합니다. 그러나 Swagger 2만이 OpenSource 도구를 잘 지원합니다. RAML은 매우 유연하고 복잡하며 Swagger 3은 커뮤니티에서 제대로 지원되지 않으므로 꽤 비싼 경향이 있는 독점 도구나 상용 솔루션을 사용해야 합니다.

게다가 이미 만들어진 포털처럼 Swagger에 좋은 기능이 많다면 editor.swagger.io, 주석을 업로드하고 자세한 설명, 링크 및 연결을 통해 시각화를 얻을 수 있으며, 더 기본적이고 덜 친숙한 RAML의 경우 그러한 기회가 없습니다. 예, GitHub의 프로젝트 중에서 무언가를 검색하고 거기에서 유사한 항목을 찾아 직접 배포할 수 있습니다. 그러나 어떤 경우에도 누군가는 포털을 유지 관리해야 하므로 이는 기본 사용이나 테스트 요구 사항에 비해 그리 편리하지 않습니다. 또한 swagger는 더 "원칙적이지" 않거나 더 자유적입니다. 이는 코드의 주석에서 생성될 수 있습니다. 물론 이는 API 첫 번째 원칙에 위배되며 RAML 유틸리티에서는 지원되지 않습니다.

한때 우리는 좀 더 유연한 언어인 RAML을 사용하여 작업하기 시작했고 그 결과 우리 스스로 많은 일을 해야 했습니다. 예를 들어, 프로젝트 중 하나가 유틸리티를 사용합니다. 산란 RAML 0.8만 지원하는 단위 테스트에서. 따라서 유틸리티가 RAML 버전 1.0을 "먹을" 수 있도록 목발을 추가해야 했습니다.

꼭 선택해야 하나요?

RAML용 솔루션 생태계를 완성하기 위해 노력한 결과, RAML을 Swagger 2로 변환하고 여기에서 모든 자동화, 검증, 테스트 및 후속 최적화를 수행해야 한다는 결론에 도달했습니다. 이는 RAML의 유연성과 Swagger의 커뮤니티 도구 지원을 모두 활용하는 좋은 방법입니다.

이 문제를 해결하기 위해 계약 변환을 제공해야 하는 두 가지 OpenSource 도구가 있습니다.

1. oas-raml-변환기 현재 지원되지 않는 유틸리티입니다. 작업하는 동안 우리는 다수의 파일에 걸쳐 "확산"되는 복잡한 RAML에 여러 가지 문제가 있음을 발견했습니다. 이 프로그램은 JavaScript로 작성되었으며 구문 트리의 재귀 순회를 수행합니다. 동적 타이핑으로 인해 이 코드를 이해하기 어려워지기 때문에 우리는 죽어가는 유틸리티에 대한 패치를 작성하는 데 시간을 낭비하지 않기로 결정했습니다.
2. webapi 파서 - 모든 것을 어떤 방향으로든 변환할 준비가 되어 있다고 주장하는 동일한 회사의 도구입니다. 현재까지 RAML 0.8, RAML 1.0 및 Swagger 2.0에 대한 지원이 발표되었습니다. 그러나 우리가 연구할 당시에는 그 효용성이 여전히 낮았습니다. 극도로 습해서 사용할 수 없습니다. 개발자는 일종의 IR, 향후 새로운 표준을 신속하게 추가할 수 있습니다. 그러나 지금까지는 작동하지 않습니다.

그리고 이것이 우리가 겪은 어려움의 전부는 아닙니다. 파이프라인의 단계 중 하나는 저장소의 RAML이 사양에 비해 올바른지 확인하는 것입니다. 우리는 여러 유틸리티를 사용해 보았습니다. 놀랍게도 그들은 모두 다른 장소에서 완전히 다른 나쁜 말로 우리의 주석에 대해 맹세했습니다. 그리고 항상 요점은 아닙니다 :).

결국 우리는 많은 문제가 있는 오래된 프로젝트에 합의했습니다(때때로 갑자기 충돌이 발생하고 정규식 작업 시 문제가 발생함). 따라서 우리는 무료 도구를 기반으로 유효성 검사 및 변환 문제를 해결할 방법을 찾지 못하고 상용 유틸리티를 사용하기로 결정했습니다. 앞으로 OpenSource 도구가 더욱 성숙해짐에 따라 이 문제를 해결하기가 더 쉬워질 수 있습니다. 그 동안 "마무리"에 드는 인건비와 시간 비용은 상용 서비스 비용보다 더 중요해 보였습니다.

결론

결국 우리는 경험을 공유하고 계약 설명 도구를 선택하기 전에 해당 도구에서 원하는 것과 투자할 예산을 명확하게 정의해야 한다는 점에 주목하고 싶었습니다. OpenSource를 잊어버리더라도 확인, 변환, 검증하는 데 도움이 되는 서비스와 제품이 이미 많이 있습니다. 그러나 그것들은 비싸고 때로는 매우 비쌉니다. 대기업이라면 이 정도 비용은 감수할 수 있지만, 스타트업이라면 큰 부담이 될 수 있다.

나중에 사용할 도구 세트를 결정하십시오. 예를 들어, 계약서를 표시해야 한다면 아름다운 API를 갖춘 Swagger 2를 사용하는 것이 더 쉬울 것입니다. 왜냐하면 RAML에서는 서비스를 직접 구축하고 유지해야 하기 때문입니다.
작업이 많을수록 도구에 대한 필요성이 더 넓어지고 플랫폼마다 다르므로 향후 비용을 최소화하는 선택을 하려면 사용 가능한 버전에 즉시 익숙해지는 것이 좋습니다.

그러나 오늘날 존재하는 모든 생태계가 불완전하다는 점은 인식할 가치가 있습니다. 따라서 회사 내에 “생각을 좀 더 유연하게 표현할 수 있다”는 이유로 RAML에서 일하는 것을 좋아하거나, 반대로 “더 명확하다”는 이유로 Swagger를 선호하는 팬들이 있다면, 그들을 맡겨두는 것이 최선이다. 모든 형식의 도구는 파일 수정이 필요하기 때문에 익숙하고 원합니다.

우리의 경험에 따르면 다음 게시물에서는 RAML-Swagger 아키텍처를 기반으로 수행하는 정적 및 동적 검사와 계약에서 생성하는 문서 및 작동 방식에 대해 설명합니다.

등록된 사용자만 설문 조사에 참여할 수 있습니다. 로그인제발

마이크로서비스 계약에 주석을 달기 위해 어떤 언어를 사용합니까?

• RAML 0.8

• RAML 1.0

• 스웨거 2

• OAS3(일명)

• 청사진

• 다른

• 사용하지 않음

100명의 사용자가 투표했습니다. 24명의 사용자가 기권했습니다.

출처 : habr.com