API 우선 순위를 사용하여 Restful API-계약 테스트 설계

며칠 전에 "API를 사용하는 첫 번째 방법으로 Restful API를 설계합니다"시리즈의 두 번째 부분을 썼습니다. 두 번째 문장을 보셔서 어떻게 진행하는지 알아보시기 바랍니다.
오늘 우리는 계약 테스트와 API가 제시한 설계를 만족시킬 수 있도록 어떻게 확보하는지 토론할 것이다.

우리가 API를 이야기할 때, 우리는 계약 정의를 이야기하기 때문에, API가 사용된 후에 정의된 계약은 반드시 API 공급자가 지원해야 한다는 것을 기억해야 한다.
API가 사용 가능한 후에도 계속 발전하고 있기 때문에 API 라이프 사이클에서 가장 큰 도전 중 하나는 API의 발전이다.때때로 업무 수요의 변화가 너무 커서 현재 계약이 새로운 수요를 만족시키지 못하기 때문에 돌파적인 변경이 필요하다.

😈 변화를 깨다--만악의 근원

내가 통상적으로 말한 바와 같이 API는 계약의 정의이다. 우리는 어떠한 불량한 결과도 없이 계약을 파괴할 수 없다.
새로운 기능이 계약의 현재 상태를 파괴할 때, 만약 당신이 그것을 잘 관리하지 못한다면, 당신의 고객은 문제에 직면하게 되고, 당신의 API가 발표된 후에 그들의 고객은 파괴될 것이다.
따라서 API 개발 과정에서 신속한 피드백을 얻기 위해서는 변경이 파괴적인 변경을 도입하는지 알아야 합니다.

🧪 가능한 방법

변경 중단에 대한 피드백을 신속하게 얻을 수 있는 두 가지 방법이 있습니다.

단원 테스트

API 실행 단위 테스트는 테스트가 실패하기 때문에 계약이 언제 파괴되는지 알려 줍니다.
이것은 매우 쉽게 시작할 수 있는 전략이고 거의 응용 프로그램에 단원 테스트 세트가 있다. 주문서에서 이런 방법은 너무 쉽게 돌아갈 수 있다. 왜냐하면 개발자는 테스트를 복구하기만 하면 성공하고 앞으로 추진할 수 있기 때문이다.

API 버전 제어

새 버전마다 API의 새 버전을 만들고 고객이 새 버전으로 이동할 때까지 이전 버전을 유지합니다.
우리는 API 버전 제어가 최선의 실천이라는 것을 알고 있지만, 모든 버전에 새로운 API 버전을 만들면 의심할 여지없이 매우 혼란스러워지고 모든 버전을 함께 유지하기 어려울 것입니다.

계약 테스트

API 설계 기간 동안 설계된 내용과 개발된 내용 간의 차이를 검사하고 연속 통합 파이프라인에서 실행하면 우리에게 신속한 피드백을 제공할 수 있으며 이것은 매우 유연하고 효과적인 방법이다.

나는 어떤 방법을 사용해야 합니까?

만약 우리가 앞의 두 가지 옵션을 보면 뚜렷한 단점을 발견할 수 있다. 절차가 돌아가거나 유지보수할 수 있는 문제이다.
계약 테스트를 다른 두 가지 방법과 비교해 보면 원시 OpenAPI 문서를 변경하지 않으면 개발자가 이 과정을 돌아갈 수 없으며 귀하의 팀과 API 이해관계자(가능하다면)를 위해 이 변경 사항을 심사해야 한다는 것을 알 수 있습니다.
그것은 자동화를 실현하기 쉬워서 무엇이 떨어지고 왜 실패하는지 똑똑히 알 수 있다.

🤖 계약 테스트 실시

상기에서 말한 바와 같이 계약 테스트는 구축 시 중단성 변경을 검사하는 가장 좋은 해결 방안인 것 같습니다. 이 간행물 기간에 openapi-diff라는 도구를 사용하도록 도와주기 위해서입니다. 이것은 npm 패키지입니다. 이것은 두 개의 OpenApi 문서를 비교하고 삭제하거나 추가한 내용을 찾습니다.
OpenAPI diff는 변경 사항을 두 그룹으로 나누어 변경 내용을 중단하고 부드럽게 변경합니다. 예를 들어 다음과 같습니다.

변경 내용 중단

경로 또는 매개변수 삭제

경로 또는 매개변수 이름 바꾸기

필요한 매개변수 추가

응답 항목 수정

부드러운 변경 내용

경로 또는 매개변수 추가

응답 항목 추가

설명 추가 또는 업데이트

설치openapi-diff는 너무 간단합니다. 다음 명령 중 하나만 실행하면 됩니다.

// using npm
npm install openapi-diff

// using yarn
yarn add openapi-diff

뭘 테스트해?

너 자신에게 물어보고 있을지도 모르지만, 우리는 차이를 대조해서 검사할 것이다.
우리가 다음 단계를 계속하기 전에 매우 중요한 단계는 코드를 추출하여 생성하는 것이다. 이것은 당신이 응용 프로그램을 작성하는 데 사용하는 플랫폼에 달려 있다.
이 블로그에서 나는 ASP를 사용할 것이다.이 시리즈에서 사용하는 동일한 저장소에 있는 NET 핵심 API입니다.
간단하게 말하자면, 나는 ASP에 어떻게 허세를 부리는지 보여주지 않을 것이다.NET 핵심 프로젝트입니다. 하지만 이 점을 어떻게 정확하게 하는지 보고 싶으시면 아래에 논평을 주십시오. 저는 이 설정을 전문적으로 소개하는 글을 쓸 수 있습니다.

ASP。NET Core 및 Swashback CLI

이미 ASP에 Swashback을 구성했기 때문입니다.NET 핵심 프로젝트, swagger.json라는 Dotnet 도구를 설치할 수 있습니다. 이것은 매우 간단한 도구입니다. 프로젝트 DLL 추출 Swashbuckle.AspNetCore.Cli 을 사용하십시오. 이 도구에 대해 더 알고 싶으면 Github Document 을 확인하십시오.
공식 문서의 설명에 따라 이 도구를 설치한 후 다음 명령을 실행하기만 하면 됩니다.

swagger tofile --yaml --output ./bin/swagger.yaml ./api/TodoApp.Api/bin/Debug/netcoreapp3.1/TodoApp.Api.dll v1

위의 명령은 흔들림을 추출할 것입니다.json은 이를 YAML 파일로 변환합니다. 이 문서는 우리가 API 설계 과정에서 작성한 OpenAPI 문서처럼 보입니다.

OpenAPI Diff 실행 중

현재 우리는 디자인된 OpenAPI 문서와 코드를 통해 생성된 OpenAPI 문서를 가지고 있으며, 이 파일들을 비교하고 출력을 검사할 때가 되었다.
위의 명령을 실행하고 컨트롤러 출력을 보기만 하면 됩니다.

openapi-diff ./bin/api.yaml ./bin/swagger.yaml

변화가 없다

변화가 있다

나는 단지 코드에서 약간의 변경을 했을 뿐이다. swagger.json 단점에 새로운 검색 문자열 파라미터를 추가하고 GET /tasks 단점에서 상태 코드를 삭제했다. 우리는 아래의 출력을 볼 수 있다.

위에서 보듯이 검색 문자열 매개 변수의 변경 사항은 기록되지 않았지만 상태 코드 삭제의 변경 사항은 중단 변경으로 검출되었습니다.
이제 API 파이프라인에 OpenAPI Diff를 추가하면 API를 변경할 때마다 발생할 수 있는 중단 변경 사항을 감지하고 저장소로 전송할 수 있습니다.
이 정책은 개발자가 로컬 기기에서 같은 스크립트를 실행하여 파이프가 끊기지 않도록 하고 빠른 실패를 검증할 수 있도록 합니다.

🏁 결론

내가 보기에 변경을 피하는 것은 API 생명주기에서 가장 어려운 임무이다. 대부분의 경우 디자인 단계에서 우리가 디자인을 주목하여 사용 수명을 연장하고 API가 해결하기 위한 분야에서 발생할 수 있는 구석진 상황을 이해하면 새로운 업무 수요가 발생할 때 API 계약을 파괴하는 필요성을 줄일 수 있다.
파괴적인 변경을 통제하기 위해 계약 테스트 전략은 저희가 빠른 피드백을 제공하여 계약을 안전하게 파괴하고 API 고객에게 문제를 만드는 데 도움을 줄 수 있습니다.
일반적으로 모든 코드는 Github Repository 에서 업데이트되어 실행될 수 있으며, 이를 본문의 보충으로 합니다.
나로 하여금 네가 이 전략에 대해 어떤 견해를 가지고 있는지 알게 해라.
당신은 이미 알고 있습니까?
다음은 경험을 공유할 수 있는 평론을 드리겠습니다.
좋아해 주셨으면 좋겠어요. 안녕히 계세요.