Skip to content

Commit d3df6aa

Browse files
author
yeongseon
committed
docs: sync General Guidelines Implementation with upstream
Update three sections in implementation.md to reflect upstream changes: Parameter validation (#169): - Add missing requirement general-params-server-defaults - Clarify that service parameter default values can change between api-versions Distributed Tracing (#170): - Update reference from [Tracing Conventions] to [OpenTelemetry Conventions] - Replace span naming format from <client> <method> to {Namespace}.{Interface}.{OperationName} - Add backward compatibility note for stable libraries Dependencies (#171): - Improve translation consistency and terminology - Update phrasing for MUST/MUSTNOT requirements - Polish Azure SDK Architecture Board translation All changes verified with Jekyll build (3.333 seconds). Closes #169, #170, #171
1 parent 41c7b36 commit d3df6aa

1 file changed

Lines changed: 9 additions & 7 deletions

File tree

docs/general/implementation.md

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,8 @@ sidebar: general_sidebar
6868

6969
{% include requirement/MUSTNOT id="general-params-server-validation" %} 서비스 매개변수의 유효성을 검사하지 마세요. 여기에는 널 검사, 빈 문자열, 그리고 기타 일반적인 유효성 검사 조건들이 포함됩니다. 서비스에서 모든 요청 매개변수들의 유효성을 검사하도록 합니다.
7070

71+
{% include requirement/MUSTNOT id="general-params-server-defaults" %} 서비스 매개변수에 대한 기본값을 인코딩하지 마세요. 서비스 매개변수 기본값은 api-version 간에 변경될 수 있습니다. 필수 매개변수는 클라이언트 인터페이스에 값을 전달하도록 요구해야 하며, 선택적 매개변수는 지정되지 않은 경우 생략되어야 하므로 서비스가 요청된 api-version에 대한 기본값을 사용하게 됩니다.
72+
7173
{% include requirement/MUST id="general-params-check-devex" %} 서비스 매개변수가 유효하지 않은 경우 개발자 경험의 유효성을 검사하여 서비스에서 적절한 오류 메시지가 생성되는지 확인하세요. 만약 서비스 측 오류 메시지로 인해 개발자 경험이 손상된 경우 서비스 팀과 협력하여 릴리스 전에 수정하세요.
7274

7375

@@ -194,9 +196,9 @@ HTTP 파이프라인은 여러 정책에 의해 감싸지는 HTTP 전송으로
194196

195197
{% include requirement/MUST id="general-tracing-suppress-client-spans-for-inner-methods" %} 클라이언트 메서드가 새 스팬을 생성하고 동일하거나 다른 Azure SDK의 다른 공개(public) 클라이언트 메서드를 내부적으로 호출하는 경우, 내부 클라이언트 메서드에 대해 생성된 스팬은 반드시 억제되어야 하며, 해당 속성 및 이벤트는 무시되어야 합니다. REST 호출을 위해 만들어진 중첩된 스팬은 외부 클라이언트 호출 스팬의 자식이어야 합니다. 억제(Suppression)는 일반적으로 Azure Core에 의해 수행됩니다.
196198

197-
{% include requirement/MUST id="general-tracing-new-span-per-method-conventions" %} [Tracing Conventions]에 따라 스팬 속성을 채우세요.
199+
{% include requirement/MUST id="general-tracing-new-span-per-method-conventions" %} [OpenTelemetry Conventions]에 따라 스팬 속성을 채우세요.
198200

199-
{% include requirement/MUST id="general-tracing-new-span-per-method-naming" %} 네임스페이스 또는 비동기 접미사 없이 메서드별 스팬의 이름으로 `<client> <method>`를 사용해주세요. 대소문자(casing) 또는 구분자에 대한 언어별 규칙을 따르세요.
201+
{% include requirement/MUST id="general-tracing-new-span-per-method-naming" %} 서비스 메서드의 경우, 비동기 접미사 없이 기본 TypeSpec 작업 정의를 기반으로 한 언어 독립적 명명 형식 `{Namespace}.{Interface}.{OperationName}`을 각 메서드의 스팬 이름으로 사용하세요. 단일 서비스 작업에 매핑되지 않는 계측된 편의 메서드의 경우, 비동기 접미사 없이 `{Namespace}.{Interface}.{Method}`를 사용하세요. 참고: 이전 버전의 가이드에서는 언어별 `<client> <method>` 패턴을 권장했습니다. 새로운 형식은 안정적인 라이브러리에서 역호환되지 않는 변경사항을 도입하지 않는 한 새 코드에서 사용할 수 있습니다.
200202

201203
{% include requirement/MUST id="general-tracing-new-span-per-method-duration" %} 요청을 전송하거나 실패할 수 있는 시간 소요가 큰 코드를 호출하기 전에 메서드별 스팬을 시작하세요. 모든 네트워크, IO 또는 기타 불안정하고 시간 소모가 많은 작업이 완료된 후에만 스팬을 종료하세요.
202204

@@ -225,15 +227,15 @@ Azure 서비스는 고객에게 HTTP와 JSON(여기서 JSON 문자열은 "순수
225227
* **호환성** - 종종 의존성을 제어하지 않아 원래의 사용과 호환되지 않는 방향으로 비약할 수 있습니다.
226228
* **보안** - 의존성에서 보안 취약점이 발견되었다면, Microsoft가 의존성의 코드 기반(code base)을 제어하지 않는 경우 취약점을 수정하는 데 어려움이 있거나 시간이 오래 걸릴 수 있습니다.
227229

228-
{% include requirement/MUST id="general-dependencies-azure-core" %} 모든 클라이언트 라이브러리에서 공통되는 기능은 Azure Core 라이브러리에 의존하세요. 이 라이브러리에는 HTTP 연결, 글로벌 구성, 자격증명 처리를 위한 API들이 포함되어 있습니다.
230+
{% include requirement/MUST id="general-dependencies-azure-core" %} 모든 클라이언트 라이브러리에서 공통되는 기능은 Azure Core 라이브러리에 의존해야 합니다(depend on). 이 라이브러리에는 HTTP 연결, 글로벌 구성, 자격 증명 처리를 위한 API가 포함되어 있습니다.
229231

230-
{% include requirement/MUSTNOT id="general-dependencies-approved-only" %} 클라이언트 라이브러리 배포 패키지 내의 다른 패키지에 의존하지 마세요. 의존성은 예외적인 경우이며 아키텍처 검토를 통해 철저한 심사가 필요합니다. 이는 허용 가능하고 일반적으로 사용되는, 빌드 의존성에는 적용되지 않습니다.
232+
{% include requirement/MUSTNOT id="general-dependencies-approved-only" %} 클라이언트 라이브러리 배포 패키지 내의 다른 패키지에 의존해서는 안 됩니다. 의존성은 예외사항이며 아키텍처 검토를 통해 철저한 심사가 필요합니다. 이는 허용 가능하며 일반적으로 사용되는 빌드 의존성에는 적용되지 않습니다.
231233

232-
{% include requirement/SHOULD id="general-dependencies-vendoring" %} 생태계(ecosystem)와 충돌할 수 있는 다른 패키지에 의존성을 갖지 않으려면 클라이언트 라이브러리에 필요한 코드를 복사하거나 연결(link)하는 것을 고려해야 합니다. 라이선스 계약을 위반하지 않았는지 확인하고 복제된 코드에 필요할 유지보수를 고려하세요. ["A little copying is better than a little dependency"][1] (YouTube).
234+
{% include requirement/SHOULD id="general-dependencies-vendoring" %} 생태계와 충돌할 수 있는 다른 패키지에 대한 의존성을 피하기 위해 클라이언트 라이브러리에 필요한 코드를 복제하거나 링크하는 것을 고려해야 합니다. 라이선스 계약을 위반하지 않는지 확인하고, 복제된 코드에 필요한 유지보수 비용을 고려하세요. ["A little copying is better than a little dependency"][1] (YouTube).
233235

234-
{% include requirement/MUSTNOT id="general-dependencies-concrete" %} 구체적인 로깅, 의존성 주입, 또는 구성 기술에 의존하지 마세요 (Azure Core 라이브러리에서 구현된 경우 제외). 클라이언트 라이브러리는 애플리케이션에서 자체적으로 선택한 로깅, 의존성 주입(DI), 구성 기술을 사용할 애플리케이션에서 사용될 것입니다.
236+
{% include requirement/MUSTNOT id="general-dependencies-concrete" %} 구체적인 로깅, 의존성 주입 또는 구성 기술에 의존해서는 안 됩니다 (Azure Core 라이브러리에 구현된 경우는 제외). 클라이언트 라이브러리는 사용자가 직접 선택한 로깅, DI, 구성 기술을 사용하는 애플리케이션에서 사용될 것입니다.
235237

236-
위의 고려사항은 언어마다 정도가 다를 수 있으므로, 설계 단계 초기에 특정 언어에 대해 승인된 종속성 및 지침을 확인하는 것이 중요합니다. (또한, 일부 드문 경우이지만, 상당한 검토를 거친 결과, 이사회가 그렇게 함으로써 지속적인 방식으로 고객을 지원하는 데 극히 적은 위험만이 존재한다고 판단한 경우 Azure SDK Architecture Board가 추가 서드파티 라이브러리에 대한 하드 종속성을 채택할 수도 있음에 유념하세요.)
238+
위의 고려 사항은 언어마다 정도가 다를 수 있으므로, 설계 단계 초기에 특정 언어에 대해 승인된 의존성 및 지침을 확인하는 것이 중요합니다. (또한 드문 경우지만, 상당한 검토를 거친 이사회가 그렇게 함으로써 고객을 지속적으로 지원하는 데 따른 위험이 최소화된다고 판단할 경우, Azure SDK 아키텍처 위원회는 추가적인 서드파티 라이브러리에 대한 하드 의존성을 갖도록 결정할 수도 있습니다.)
237239

238240

239241
## 서비스별 공통 라이브러리 코드

0 commit comments

Comments
 (0)