다음을 통해 공유

TypeSpec이란?

TypeSpec 은 API를 디자인하기 위한 강력하고 유연한 언어입니다. 이를 통해 개발자는 확장 가능하고 이해하기 쉬운 언어로 API를 정의할 수 있습니다. 이 컴파일은 내보내기를 사용하여 API 사양, 클라이언트 코드 및 서버 쪽 API 코드를 생성합니다. TypeSpec은 Microsoft에서 개발하고 커뮤니티에서 지원하는 오픈 소스 프로젝트 입니다.

TypeSpec 및 생성된 사양을 보여 주는 다이어그램은 API 생성 전에 발생합니다.

TypeSpec을 사용하면 간결하고 API 지침을 준수하는 모듈식 재사용 가능한 구성 요소를 만들 수 있습니다. 표준 TypeSpec 라이브러리에는 기존 도구 및 워크플로와의 호환성을 보장하는 OpenAPI 방출기가 포함되어 있습니다.

오픈 소스 언어인 TypeSpec은 Azure API뿐만 아니라 모든 API를 설명할 수 있습니다. 이러한 다재다능함은 복잡하고 진화하는 환경에서 고품질 API를 제공해야 하는 API 개발자, 설계자 및 관리자에게 유용한 도구입니다.

TypeSpec의 이점

  • API 개발간소화: API를 정의할 수 있는 명확하고 간결한 방법을 제공하여 개발자가 논리 및 기능에 집중할 수 있도록 합니다.
  • 배포가속화: TypeSpec은 단일 API 정의에서 신속한 서비스 및 클라이언트 코드를 생성하여 배포를 간소화하고 일관성을 보장합니다.
  • 규정 준수보장: 재사용 가능한 구성 요소를 사용하여 설정된 지침 및 표준을 준수하여 오류 및 불일치를 줄입니다.
  • 호환성향상: 기존 도구 및 워크플로와의 호환성을 위해 OpenAPI 방출기를 포함하므로 통합이 더 쉬워질 수 있습니다.
  • 확장성지원: 유연하고 확장 가능하여 다양한 시나리오에 대한 API 정의의 사용자 지정 및 확장을 허용합니다.
  • 마이그레이션가속화: OpenApiMigration 도구 채택 속도를 높이려면 TypeSpec으로의 전환을 용이하게 합니다.

오픈 소스 프로젝트TypeSpec은 커뮤니티 기여 및 피드백의 이점을 활용하여 실제 사용 사례에 따라 지속적인 개선을 보장합니다.

API 디자인이 어렵습니다.

TypeSpec은 API 디자인, 거버넌스 및 구현의 일반적인 문제를 해결합니다.

  • 복잡한 사양: API 사양 작성, 검토 및 유지 관리는 번거로울 수 있습니다. 간단한 API라도 수백 줄의 사양 코드가 생성될 수 있습니다.
  • 프로토콜 다양성: 각 프로토콜에는 프로토콜 간 공유 디자인 언어가 없는 고유한 사양 형식이 있습니다. 이 조각화는 개발 프로세스를 복잡하게 만듭니다.
  • 거버넌스 문제: 통합 디자인 언어가 없으면 API를 관리하는 것이 어려워져서 구현 및 품질이 일치하지 않습니다.
  • 확장성 문제: API 또는 API 버전 수가 증가함에 따라 더 많은 엔지니어링 팀이 필요하며, 이로 인해 조정 과제와 비효율성이 발생할 수 있습니다.

TypeSpec은 이러한 문제를 해결하여 API 디자인 프로세스를 간소화하고, 다양한 프로토콜 간에 일관성을 보장하며, 전반적인 거버넌스 및 확장성을 향상시킵니다.

TypeSpec API 개발 워크플로

다음 다이어그램에서는 TypeSpec을 사용하여 API를 개발하는 데 관련된 주요 단계를 보여 줍니다. 프로세스는 새 API 사양을 처음부터 만들거나 기존 OpenAPI 사양에서 마이그레이션하는 두 가지 옵션으로 시작합니다. 시작되면 API는 모듈식 및 재사용 가능한 구성 요소를 사용하여 TypeSpec을 사용하여 정의됩니다. 그런 다음 TypeSpec 컴파일러는 강력한 내보내기 집합을 사용하여 이러한 정의를 처리하여 API 사양, 클라이언트 코드 및 서버 쪽 스텁 코드를 자동으로 생성합니다. 마지막으로 생성된 아티팩트가 기존 도구 체인과 통합되어 원활하고 일관된 워크플로를 보장합니다.

TypeSpec 워크플로를 보여 주는 다이어그램

워크플로 단계

단계 설명
시작 먼저 TypeSpec을 사용하여 새 API 사양을 작성하거나 기존 OpenAPI 사양에서 마이그레이션합니다.
"TypeSpec" 정의 TypeSpec을 사용하여 API를 정의합니다. 재사용 가능한 구성 요소는 API를 간결하게 만들고 지침 준수를 보장합니다.
TypeSpec 컴파일러 컴파일러는 TypeSpec 정의를 처리하여 코드 생성을 준비합니다.
세대 전용 내보내기는 API 사양, 클라이언트 코드 및 서버 쪽 스텁 코드를 자동으로 생성합니다.
통합 생성된 출력은 기존 API 도구 체인에 원활하게 통합됩니다.

TypeSpec 컴파일러의 경로:
TypeSpec 컴파일러는 필요한 경우 OpenAPI 사양, 클라이언트 코드 및 서버 쪽 스텁 코드에 대한 출력을 동시에 생성할 수 있지만 프로젝트 요구 사항에 따라 각 출력을 독립적으로 트리거할 수 있습니다.

  1. OpenAPI 사양을 생성
    OpenAPI 방출기는 표준화된 API 설명 형식을 생성합니다.

  2. Client-Side 코드 생성
    클라이언트 코드 방출기는 API를 사용하는 코드를 만듭니다.

  3. Server-Side 스텁 코드 생성
    서비스 쪽 방출기는 API 구현을 시작하는 서버 스텁 코드를 생성합니다.

TypeSpec을 사용하여 포괄적인 코드 생성

클라이언트 코드 생성

TypeSpec은 TypeSpec 정의에서 직접 API를 사용하는 코드를 자동으로 만들어 클라이언트 코드 생성을 간소화합니다. 이 프로세스는 원활한 통합을 보장하는 표준 런타임 인터페이스, 특정 클라이언트 요구 사항에 맞게 출력을 조정하는 사용자 지정 코드 확장성 및 전체 개발 스택에 걸친 포괄적인 생성과 같은 주요 기능을 활용합니다. 따라서 개발자는 애플리케이션 간에 일관성을 유지하고, 수동 코딩 작업을 줄이며, API를 기존 도구 체인과 빠르게 통합하면서 보다 효율적이고 확장 가능한 개발 워크플로를 누릴 수 있습니다.

지원되는 언어:

  • 닷넷
  • 자바
  • JavaScript
  • 파이썬

서버 코드 생성

TypeSpec은 TypeSpec 정의에서 직접 서버 쪽 스텁 코드 생성을 지원합니다. 이렇게 하면 개발 프로세스가 간소화되고 클라이언트 및 서버 구현 간에 일관성이 보장됩니다.

지원되는 언어:

  • 닷넷
  • JavaScript

주요 기능:

  • 표준 런타임 인터페이스: 표준 방출기는 처음에 런타임 인터페이스를 생성하여 다양한 런타임 스택과 유연성과 간편한 통합을 보장하는 데 중점을 둡니다.
  • 사용자 지정 코드 확장성: TypeSpec 내보내기는 사용자 지정 코드 확장성을 제공하므로 개발자는 생성된 코드를 특정 요구 사항에 맞게 조정하여 다양한 환경에 맞게 조정할 수 있습니다.
  • 포괄적인 코드 생성: TypeSpec은 다양한 프로토콜 및 자산 형식을 포함하여 클라이언트에서 서버까지 전체 개발 스택에서 코드 생성을 지원하여 통합 개발 방식을 보장합니다.

개발자는 TypeSpec의 서비스 쪽 코드 생성 기능을 사용하여 수동 코딩을 줄이고 일관성을 개선하며 전반적인 생산성을 향상시킬 수 있습니다.

업계 도구 체인과의 상호 운용성

TypeSpec은 기존 산업 도구 체인과 원활하게 통합되어 상호 운용성을 보장하고 생산성을 향상합니다. TypeSpec 정의에서 OpenAPI 사양을 생성하면 개발자는 API용 Swagger 설명서, API 테스트용 Postman 및 API 배포를 위한 Azure API Management와 같은 OpenAPI용으로 설계된 방대한 도구 에코시스템을 사용할 수 있습니다. 여기에는 API 게이트웨이 구성, 클라이언트 및 서버 코드 생성, API 데이터 유효성 검사 등이 포함됩니다. 이 호환성을 통해 팀은 TypeSpec에서 제공하는 구조적이고 일관된 API 디자인의 이점을 활용하면서 현재 워크플로를 유지할 수 있습니다.

뛰어난 개발자 환경

개발자 통합에는 Visual Studio Code 확장 및 Visual Studio포함됩니다. 이러한 통합은 자동 완성, 구문 강조 표시, 빌드 시간 오류 식별, 기호 이름 바꾸기 및 문서 서식과 같은 기능을 통해 효율적이고 오류 없는 코딩을 제공합니다. 예를 들어 Visual Studio Code에서 TypeSpec 정의를 작성할 때 확장은 실시간 자동 완성 및 구문 강조 표시를 제공하여 정확하고 일관된 API 정의를 더 쉽게 작성할 수 있도록 합니다.

자동 완성 및 구문 강조 표시를 제공하는 TypeSpec용 Visual Studio Code 확장의 스크린샷 애니메이션입니다.

또한 TypeSpec Playground 개발자가 TypeSpec 구문 및 기능을 실시간으로 실험할 수있는 대화형 환경을 제공합니다. 이 웹 기반 도구는 TypeSpec을 더 쉽게 학습하고 채택할 수 있도록 즉각적인 피드백과 유효성 검사를 제공합니다. TypeSpec Playground에서 제공하는 대화형 실습 환경은 개발자의 이해와 숙련도를 심화시켜 궁극적으로 보다 일관되고 고품질의 API 디자인을 만듭니다. 이러한 도구는 개발 프로세스를 간소화하고 오류 가능성을 줄이며 새 팀 구성원의 학습 곡선을 가속화하여 개발자 환경을 전체적으로 개선합니다.

Swagger UI로 내보내는 샘플 HTTP 서비스가 있는 TypeSpec 플레이그라운드 스크린샷

기존 API에서 전환하는 개발자를 지원하기 위해 OpenApiMigration 도구 OpenAPI 사양을 TypeSpec 정의로 변환하는 효율적인 방법을 제공합니다. 이 마이그레이션 도구는 기존 API 설명서의 무결성을 유지하면서 TypeSpec 채택을 간소화하고 가속화합니다. 세 가지 마이그레이션 예제는 다음과 같습니다.

Real-World 사용

TypeSpec은 API 디자인 및 개발을 간소화하기 위해 다양한 산업에서 성공적으로 사용되었습니다. 다음은 몇 가지 예입니다.

  • 전자 상거래: 온라인 소매 플랫폼은 TypeSpec을 사용하여 API를 디자인하고 문서화하여 타사 서비스와 원활하게 통합하고 전체 개발자 환경을 개선했습니다.
  • Finance: 금융 서비스 회사는 API 전반에서 일관성과 규정 준수를 보장하기 위해 TypeSpec을 채택하여 API 거버넌스에 필요한 시간과 노력을 줄입니다.
  • 의료: 의료 공급자는 TypeSpec을 사용하여 환자 데이터 관리를 위한 API를 설계하여 시스템 전체에서 데이터 일관성과 보안을 보장했습니다.

시작하기

오픈 소스 지원

더 알아보세요

TypeSpec에 대해 자세히 알아보려면 다음 YouTube 동영상을 즐겨보세요.

관련 콘텐츠