Golang 서비스에서 API 버전 작성에 대한 모범 사례는 무엇입니까?

명확하고 라우팅 가능하며 개발자 친화적 인 버전을 위해 /API /V1과 같은 URL 경로 버전을 사용하십시오. 2. 라우팅 복잡성을 방지하기 위해 v1.1과 같은 미세 버전을 피하면서 주요 버전 (v1, v2)만으로 시맨틱 버전을 적용하십시오. 3. 이미 성숙한 콘텐츠 협상을 사용하는 경우 수락 헤더를 통해 컨텐츠 협상을 선택적으로 지원하지만 URL 버전을 선호합니다. 4. 개별 패키지 (예 :/내부/API/V1)로 버전의 핸들러 및 DTO를 분리하여 변경 사항을 방지하고 안전한 리팩토링을 가능하게합니다. 5. 감가 상각 헤더를 보내고, 정의 된 기간 동안의 지원을 유지하고, 채택을 추적하기위한 사용법을 기록하여 오래된 버전을 우아하게 사용하지 않습니다. 6. OpenApi와 같은 도구를 사용하여 버전 별 설명서를 제공하고 버전 당 별도의 사양 및 문서를 호스팅합니다 (예 : Docs.example.com/v1). 7. 쿼리 매개 변수 버전이 모호하고 캐시하기 어려우며 모니터링을 복잡하게하지 않으므로 피하십시오. 권장되는 접근 방식은 클라이언트가 API 버전을 명확하게 알 수 있도록 유지하면서 유지 관리 가능하고 확장 가능하며 후진 호환 API 진화를 가능하게합니다.

공개 또는 진화하는 API로 Golang 서비스를 구축 할 때 버전싱은 후진 호환성을 유지하고 점진적인 업데이트를 지원하는 데 필수적입니다. GO에서 API 버전 관리에 대한 모범 사례는 다음과 같습니다.

1. URL 경로 버전 사용 (가장 일반적이고 명확함) 사용

가장 널리 채택 된 접근 방식은 URL 경로에 버전을 포함시키는 것입니다.

 /API/V1/사용자
/API/V2/사용자

좋은 이유 :

• 구현하고 이해하기 쉽습니다.
• 개발자에게 명시적이고 보입니다.
• gorilla/mux , chi 또는 gin 과 같은 표준 HTTP 라우터를 사용하여 쉽게 노선합니다.

chi 의 예 :

 r : = chi.newrouter ()
v1 : = R.Group (nil)
v1.use (addversionheader ( "v1"))
v1.get ( "/user", getUsersv1)

v2 : = R.Group (nil)
v2.use (addversionheader ( "v2"))
v2.get ( "/user", getUsersv2)

R.mount ( "/api/v1", v1)
r.mount ( "/api/v2", v2)

✅ 모범 사례 : 로직 믹싱을 피하기 위해 버전의 경로 마운트를 별도로 유지하십시오.

2. 선호 시맨틱 버전싱 (Semver-Inspired)

라이브러리를 공개하지 않더라도 호환성을 나타내는 버전 작성 체계를 사용하십시오.

• v1 , v2 - 주요 중단 변경을위한.
• URL에서 v1.1 , v1.2 를 피하십시오 - 라우팅 및 클라이언트 가정을 복잡하게하십시오.

대신에:

• 변경 사항이있는 주요 버전 에는 v1 , v2 등을 사용하십시오.
• v1 내에 후진 호환 추가 (새 필드, 엔드 포인트)를 사용하십시오.
• 기존 동작을 제거하거나 변경할 때 버전 만 부딪칩니다.

✅ 모범 사례 : 과도하게 버리지 마십시오. URL에서 v1.0 , v1.1 피하십시오. v1 , v2 를 고수하십시오.

3. 컨텐츠 협상 지원 (선택 사항이지만 강력한)

HTTP 헤더를 사용하여 버전, 특히 Sateoas를 따르는 REST API 또는 서비스에 의해 소비되는 REST API를 사용하십시오.

 수락 : 응용 프로그램/vnd.myapp.v1 JSON
수락 : 응용 프로그램/vnd.myapp.v2 json

장점 :

• URL을 깨끗하게 유지합니다.
• 이론적으로 더 "편안한".

단점 :

• 테스트하기가 더 어렵습니다 (예 : 헤더가없는 브라우저 또는 컬).
• 디버깅은 덜 직관적이됩니다.

✅ 모범 사례 : 이미 성숙한 콘텐츠 협상 시스템이있는 경우에만 헤더 버전을 사용하십시오. 그렇지 않으면 URL 버전을 고수하십시오.

4. 버전 처리 된 핸들러 및 DTO를 분리합니다

버전간에 요청/응답 문자를 공유하지 마십시오. 대신, 그들을 복제하고 분리하십시오.

 // v1/dto.go
UserResponse struct {를 입력하십시오.
    Id String`json : "id"`
    이름 문자열`json : "name"`
}

// v2/dto.go
UserResponse struct {를 입력하십시오.
    Id String`json : "id"`
    첫 번째 문자열`json : "첫 번째"`
    마지막 문자열`json : "마지막"`
}

왜?

• 우발적 인 파괴 변경을 방지합니다.
• 리팩토링을 더 안전하게 만듭니다.
• 버전 당 독립 문서를 활성화합니다.

✅ 모범 사례 : 버전 별 코드 구성 :

 /내부/API/V1/
/내부/API/V2/

5. 우아하게 감가 상각됩니다

버전을 은퇴 할 때 :

• Warning 또는 Deprecation 헤더를 반환하십시오.

   경고 : 299 "API" "V1은 더 이상 사용되지 않습니다. 2025 년 1 월까지 V2를 사용하십시오."

• 합리적인 기간 동안 이전 버전을 유지하십시오.
• API 문서의 일몰 날짜를 문서화하십시오.

✅ 모범 사례 : 홀드 아웃을 식별하기 위해 더 이상 사용되지 않은 버전의 로그 사용.

6. 각 버전을 명확하게 문서화하십시오

버전 당 OpenApi (Swagger)를 사용하십시오.

• /api/v1/swagger.json 및 /api/v2/swagger.json 에 대해 별도의 사양을 생성하십시오.
• 버전 별 댓글과 함께 swaggo/swag 와 같은 도구를 사용하십시오.

✅ 모범 사례 : 버전 당 호스트 문서 (예 : docs.example.com/v1 , docs.example.com/v2 ).

7. 쿼리 매개 변수에서 버전을 피하십시오

절대하지 마십시오 :

 /API/사용자? 버전 = v1

나쁜 이유 :

• 캐시 친화적이지 않습니다.
• 노선 및 모니터링하기 어렵습니다.
• 문제를 혼합합니다 (매개 변수 대 구조).

❌ 피하십시오 : 쿼리 매개 변수 버전화-모호하고 오류가 발생하기 쉽습니다.

요약 : 권장 접근법

• URL 경로 버전화 ( /api/v1/... )를 사용하십시오.
• ✅ 버전 패키지 의 구조 코드 ( api/v1 , api/v2 ).
• dtos와 핸들러를 버전 당 격리 하십시오.
• semant 시맨틱 주요 버전을 사용하고 미세한 버전을 피하십시오.
• ✅ 헤더 및 시간대로 감가 상각됩니다 .
• ✅ 버전 별 문서를 제공합니다.

기본적으로 고객이 사용중인 버전을 쉽게 알 수있게하고 두려움없이 여러 버전을 쉽게 유지할 수 있도록하십시오.

위 내용은 Golang 서비스에서 API 버전 작성에 대한 모범 사례는 무엇입니까?의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!