Net Core 의 Api 버 전 관리

머리말
.NET Core 는.NET Core 가 실 행 될 때 와.NET Core SDK 를 말 하 며 응용 프로그램 개발 에 필요 한 도 구 를 포함한다.NET Core SDK 는 이전 버 전의.NET Core 가 실 행 될 때 와 함께 사용 할 수 있다.
본 고 는 주로.Net Core Api 버 전 관리 에 관 한 내용 을 소개 하 였 으 며,다음은 더 이상 말 하지 않 겠 습 니 다.상세 한 소 개 를 살 펴 보 겠 습 니 다.
링크:API Versioning in .Net Core
저자:Neel Bhatt
간단 한 소개
Api 의 버 전 관리 란 Api 개발 에서 자주 발생 하 는 문제 로 대부분 중대 형 프로젝트 에서 Api 의 버 전 관리 에 사용 해 야 한다.
이 블 로그 에 서 는'Net Core Api 프로젝트 에서 Api 버 전 제 어 를 어떻게 사용 하 는 지 설명 한다.
이 블 로그 에서 테스트 프로젝트 의 개발 환경:

Visual Studio 2017

.Net Core 2.1 SDK

.Net Core Api 에서 Api 버 전 관리 사용
Api 프로젝트 만 들 기
우선.NET Core Api 프로젝트 를 만 듭 니 다.

Nuget 으로 Api 버 전 관리 라 이브 러 리 설치 하기
.NET Core Mvc 에서 마이크로소프트 는 공식 적 으로 사용 가능 한 Api 버 전 제어 라 이브 러 리 Microsoft.AspNetCore.Mvc.Versioning 을 제공 했다.여기 서 우 리 는 Nuget 을 사용 하여 이 가방 을 설치 할 수 있다.
PM> Install-Package Microsoft.AspNetCore.Mvc.Versioning
Startup 클래스 수정
Microsoft.AspNetCore.Mvc.Versioning 라 이브 러 리 설치 가 완료 되면 다음 단계 에 Api 버 전 관리 서 비 스 를 추가 합 니 다.
여기에 Startup 류 의 Configure Service 방법 에 다음 코드 를 추가 해 야 합 니 다.

 services.AddApiVersioning(o => {
 o.ReportApiVersions = true;
 o.AssumeDefaultVersionWhenUnspecified = true;
 o.DefaultApiVersion = new ApiVersion(1, 0);
 });

코드 해석
ReportApiVersion 속성 은 불 형식 입 니 다.true 로 설정 하면 Api 가 요청 한 응답 헤더 에 현재 Api 가 지원 하 는 버 전,예 를 추가 합 니 다.

Response Header
api-supported-versions: 1.0
content-type: application/json; charset=utf-8
date: Sat, 06 Oct 2018 05:24:21 GMT
server: Kestrel
status: 200
x-powered-by: ASP.NET

AssumeDefaultVersionWhenUnspecified 속성 은 클 라 이언 트 가 버 전 번 호 를 지정 하지 않 았 을 때 기본 버 전 번 호 를 사용 할 지 여 부 를 표시 하기 위 한 것 입 니 다.
DefaultApiVersion 속성 은 기본 버 전 번호 입 니 다.
다 중 버 전 만 들 기 Api
Net Core Mvc 의 Api 버 전 제어 라 이브 러 리 를 테스트 하기 위해 다음 두 개의 Controller 를 만 듭 니 다.

 [ApiVersion("1.0")]
 [Route("api/values")]
 [ApiController]
 public class ValuesV1Controller : ControllerBase
 {
 [HttpGet]
 public IEnumerable<string> Get()
 {
  return new string[] { "Value1 from Version 1", "value2 from Version 1" };
 }
 } 

 [ApiVersion("2.0")]
 [Route("api/values")]
 [ApiController]
 public class ValuesV2Controller : ControllerBase
 {
 [HttpGet]
 public IEnumerable<string> Get()
 {
  return new string[] { "value1 from Version 2", "value2 from Version 2" };
 }
 }

코드 해석

Value1Controller 와 Value2Controller 는 같은 경로 로'/api/values'

를 사용 했다.

Value1Controller 클래스 의 머리 는 ApiVersion 특성 을 사용 하여 현재 Controller 의 Api 버 전 번 호 를 1.0

으로 표시 합 니 다.

Value2Controller 클래스 의 머리 는 ApiVersion 특성 을 사용 하여 현재 Controller 의 Api 버 전 번 호 를 2.0 으로 표시 합 니 다.
-Value1 controller 와 Value2 controller 는 같은 방법 으로 서명 하 는 Get 방법 을 가지 고 있 으 며,단지 2 개의 Get 에서 다른 문자열

을 되 돌려 주 었 을 뿐이다.
현재 프로젝트 를 시작 하면 다음 과 같은 결 과 를 얻 을 수 있 습 니 다.Api 버 전 번 호 를 지정 하지 않 았 을 때 프로젝트 는 1.0 버 전의 Api,즉 ValuesV1controller 의 Get 방법 을 자동 으로 사용 합 니 다.

검색 문자열(Query String)에서 버 전 관리 사용 방법
Microsoft.AspNetCore.Mvc.Versioning 은 QueryString 형식 으로 Api 를 요청 하 는 버 전 번 호 를 지정 할 수 있 습 니 다.개발 자 는 Url 에서 api-version 인 자 를 지정 하여 호출 된 Api 버 전 번 호 를 선택 할 수 있 습 니 다.
현재 항목 을 예 로 들다
요구 하 다https://localhost:44319/api/values?api-version=2.0 시 결 과 를 되 돌려 줍 니 다.

["value1 from Version 2","value2 from Version 2"]

요구 하 다https://localhost:44319/api/values?api-version=1.0 시 결 과 를 되 돌려 줍 니 다.

["Value1 from Version 1","value2 from Version 1"]

요청 한 Api 버 전 을 루트 제약 조건 에서 지정 하 는 방법
Microsoft.AspNetCore.Mvc.Versioning 은 Api 를 요청 하 는 버 전 번 호 를 제약 조건 으로 사용 하 는 것 도 지원 합 니 다.
예:[루트("api/{v:apiVersion}/값")]
우 리 는 이전 두 개의 Controller 코드 를 다음 과 같이 수정 합 니 다.

 [ApiVersion("1.0")]
 [Route("api/{v:apiVersion}/values")]
 [ApiController]
 public class ValuesV1Controller : ControllerBase
 {
  [HttpGet]
  public IEnumerable<string> Get()
  {
   return new string[] { "Value1 from Version 1", "value2 from Version 1" };
  }
 } 

 [ApiVersion("2.0")]
 [Route("api/{v:apiVersion}/values")]
 [ApiController]
 public class ValuesV2Controller : ControllerBase
 {
  [HttpGet]
  public IEnumerable<string> Get()
  {
   return new string[] { "value1 from Version 2", "value2 from Version 2" };
  }
 }

현재 우 리 는 다음 두 개의 Url 을 통 해 Api 를 요청 합 니 다.돌아 온 결 과 는 다음 과 같 습 니 다.
/api/2.0/values

["value1 from Version 2","value2 from Version 2"]

/api/1.0/values

["Value1 from Version 1","value2 from Version 1"]

요청 헤더(HTTP Header)에서 버 전 제 어 를 사용 하 는 방법
위의 두 가지 방식 은 요청 한 Url 을 수정 해 야 합 니 다.이 두 가지 방식 이 마음 에 들 지 않 으 면 Microsoft.AspNetCore.Mvc.Versioning 은 세 번 째 로 Api 버 전 번 호 를 지정 하 는 방식 도 제공 합 니 다.즉,HTTP 요청 헤더 에 버 전 번 호 를 추가 하 는 것 입 니 다.
이러한 방식 을 사용 하기 위해 서 는 먼저 Startup.cs 에서 Microsoft.AspNetCore.Mvc.Versioning 의 설정 을 수정 해 야 합 니 다.코드 는 다음 과 같 습 니 다.

 services.AddApiVersioning(o =>
 {
  o.ReportApiVersions = true;
  o.AssumeDefaultVersionWhenUnspecified = true;
  o.DefaultApiVersion = new ApiVersion(1, 0);
  o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");
 });

ApiVersionReader 속성 을 통 해 Api 버 전 번 호 를 지정 합 니 다.요청 한 머리의 x-api-version 속성 에서 나 온 것 입 니 다.
Tips:o.ApiVersionReader = new HeaderApiVersionReader("x-api-version");를 사용 하면 검색 문자열 에서 버 전 번 호 를 지정 하 는 방식 을 사용 할 수 없습니다.두 가지 방식 을 동시에 지원 하고 싶다 면o.ApiVersionReader = ApiVersionReader.Combine(new QueryStringApiVersionReader(), new HeaderApiVersionReader() { HeaderNames = { "x-api-version" }});(seamaswang 의 수정 에 감 사 드 립 니 다)
다음은 Postman 을 통 해 2.0 의 Api 를 요청 한 결과 올 바 르 게 돌 아 왔 습 니 다.

다른 기능 은 Api(Deprecated)기능 을 버 립 니 다.
때때로,우 리 는 오래된 Api 를 버 려 진 상태 로 표시 해 야 하지만,이 버 전의 Api 를 완전히 제거 하 는 것 을 원 하지 않 습 니 다.우 리 는 Deprecated 기능 을 사용 할 수 있 습 니 다.
예:우 리 는 현재 ValuesV1controler 를 버 리 고 싶 습 니 다.Deprecated 특성의 값 을 true 로 지정 할 수 있 습 니 다.

 [ApiVersion("1.0", Deprecated = true)]
 [Route("api/values")]
 [ApiController]
 public class ValuesV1Controller : ControllerBase
 {
  [HttpGet]
  public IEnumerable<string> Get()
  {
   return new string[] { "Value1 from Version 1", "value2 from Version 1" };
  }
 }

이 api 를 요청 할 때 응답 헤더 에 api-deprecated-versions 와 api-supported-versions 2 개의 속성 이 나타 납 니 다.

Response Header
api-deprecated-versions: 1.0
api-supported-versions: 2.0
content-type: application/json; charset=utf-8
date: Sat, 06 Oct 2018 06:32:18 GMT
server: Kestrel
status: 200
x-powered-by: ASP.NET

이 응답 은 1.0 버 전의 Api 가 만 료 되 었 고 2.0 버 전에 같은 Api 가 있어 2.0 버 전의 Api 로 바 꿀 수 있다 는 뜻 이다.
ApiVersionneytral 을 사용 하여 버 전 관리 가 필요 없 는 Api 를 지정 합 니 다.
Api 를 작성 할 때 아주 간단 한 Api 에 대해 서 는 건강 검진 Api 와 같은 Api 버 전 번 호 를 지정 할 필요 가 없 을 수도 있 습 니 다.Api 버 전 관리 에서 Api Versionneytral 기능 을 제거 할 수 있 습 니 다.
예:

 [ApiVersionNeutral]
 [Route("api/[controller]")]
 [ApiController]
 public class HealthCheckController : ControllerBase
 {
  public string Get()
  {
   return "Good";
  }
 }

원본 코드  （ 로 컬 다운로드 ）
총결산
이상 은 이 글 의 전체 내용 입 니 다.본 논문 의 내용 이 여러분 의 학습 이나 업무 에 어느 정도 참고 학습 가치 가 있 기 를 바 랍 니 다.궁금 한 점 이 있 으 시 면 댓 글 을 남 겨 주 셔 서 저희 에 대한 지지 에 감 사 드 립 니 다.