TypeSpec: API 중심 개발을 위한 새로운 언어

• TypeSpec은 API 중심 개발을 위한 새로운 언어로, API 개발자, 설계자, 매니저의 요구사항을 충족시키기 위해 설계됨
  • 일관되게 높은 품질의 API와 관련 경험을 제공하는 것이 점점 더 복잡해지고 중요해지는 환경에서 개발됨
  • TypeSpec은 단순한 언어 이상이며, 추상화를 가능하게 하고 코드 재사용을 장려하며 신속한 개발을 위해 최신 도구를 활용하는 플랫폼임

TypeSpec의 주요 특징

• 상호 운용성
  • TypeSpec은 단순한 API 설명 언어가 아니라 API를 정의하고 다양한 프로토콜, 클라이언트, 서버, 문서 등을 동시에 출력할 수 있는 고수준 정의 언어임
  • 업계 표준 API 정의 언어와 상호 운용 가능하여 다양한 선택 사항 간의 격차를 해소함
• 생산성
  • TypeSpec은 데이터와 API 정의 프로세스를 즐겁고 생산적으로 만드는 우수한 개발자 경험을 제공함
  • 언어는 간결하고 최소한의 입력으로 복잡한 데이터와 API 모양을 정의할 수 있음
• API 패턴
  • TypeSpec은 일반적인 데이터 유형, API 패턴 및 지침을 팀 또는 에코시스템 전체에서 공유할 수 있는 고수준의 재사용 가능한 구성 요소로 캡슐화하여 API 품질을 향상시킴
• 익숙함
  • TypeSpec은 TypeScript와 C#에서 영감을 받아 배우기 쉽고 많은 개발자에게 친숙하게 느껴짐
• 확장성
  • TypeSpec은 사용자 정의 데코레이터 어휘 및 유형 템플릿으로 확장할 수 있어 비즈니스 또는 애플리케이션 로직 도메인에서 API를 모델링할 수 있음
• 생태계
  • TypeSpec을 사용하면 공통 유형, 언어 확장, 린터 및 에미터를 패키지로 묶어 조직 내부 또는 에코시스템 전반에 걸쳐 NPM에 배포할 수 있음

커뮤니티와 협업

• Microsoft에서 사용 중
  • Microsoft에서는 TypeSpec을 사용하여 API 개발 프로세스를 혁신하고 있음
  • 많은 Azure 서비스에서 TypeSpec을 채택하고 있으며, 그 수는 매일 증가하고 있음
  • Microsoft Graph 팀은 TypeSpec의 잠재력을 활용하여 생산성을 높이고 맞춤 설정을 단순화함
• 참여 요청
  • TypeSpec은 단순한 언어 이상이며 커뮤니티임
  • 모든 배경을 가진 개발자가 공개 베타에 참여하여 TypeSpec의 힘을 직접 경험할 수 있도록 초대함

GN⁺의 의견

• TypeSpec은 추상화 레벨이 높은 API 정의 언어로, API 개발 방식을 혁신적으로 개선할 수 있을 것으로 보임
  • "API First" 접근 방식을 지원하여 개발 효율성과 최종 제품 품질 향상에 도움이 될 것임
  • 다양한 프로토콜 지원, 확장성, 강력한 생태계 등으로 폭넓은 개발 시나리오에 적용 가능할 것으로 예상됨
• 하지만 새로운 언어 도입에는 항상 학습 비용이 발생하므로, 팀 내 도입 시 충분한 교육이 선행되어야 할 것임
  • TypeScript와 C#의 문법을 차용해 학습 곡선을 낮추려 노력한 점은 긍정적임
• 유사한 역할을 하는 기존 API 정의 언어들(Swagger, RAML, API Blueprint 등)과의 차별화 포인트를 좀 더 명확히 할 필요가 있어 보임
  • 기존 언어의 한계를 어떻게 극복하는지, 마이그레이션은 용이한지 등
• Microsoft 내부에서 먼저 사용하며 개선해 나가는 독푸딩 방식은 신뢰감을 줌
  • 하지만 아직 오픈소스 프로젝트로 공개된 지 얼마 되지 않았으므로, 향후 몇 년간 지속적인 발전과 커뮤니티 지원이 관건이 될 것으로 보임
• API 설계의 표준화와 재사용성 향상이라는 방향성은 올바르나, 너무 많은 것을 한꺼번에 해결하려 한다는 인상도 있음
  • 우선순위를 두고 단계적으로 기능을 강화해 나가는 것이 좋겠음

[GN⁺]

Hacker News 의견들

• API용 TypeScript 타입이 이미 있어서, 소스에서 바로 JSON 스키마를 생성하는 https://github.com/vega/ts-json-schema-generator를 만들었음
  두 언어의 기능 집합이 조금 달라서 이상한 부분도 있지만, 몇 년째 잘 쓰고 있음. TypeScript가 없거나 API 표면적이 작아서 다시 타입을 작성해도 괜찮은 상황이라면 TypeSpec도 살펴볼 만함. 손으로 JSON 스키마를 쓰는 것보다는 확실히 낫다

• OpenAPI의 YAML 옆에 두면 뭐든 좋아 보이니 좀 반칙처럼 느껴짐. 그래도 OpenAPI는 여전히 가장 좋은 변화 중 하나라고 봄
  한편으로는 TypeScript가 스키마 언어로 자리 잡기를 꽤 기대해 왔음. 정확히는 놀라울 정도로 큰 비명령형·비함수형 부분집합 말임. 첫인상으로는 “TypeScript에서 JavaScript를 제거해서 JSON용 타입만 남기고, OpenAPI와 WSDL의 실질적 후계가 되도록 엔드포인트 메타데이터 설명을 추가하면 어떨까”에 가까워 보임

  • “OpenAPI의 YAML 옆에 두면 뭐든 좋아 보인다”니, 도전해보겠음
    https://github.com/bufbuild/protovalidate/blob/main/examples...
  • TypeScript 타입 시스템은 매우 고급이라서, 모든 주요 언어에 대응 바인딩을 만들면서도 각 언어답게 유지하기는 불가능할 것 같음. API 언어는 아주 단순하고 직관적인 쪽이 더 좋다

• 최근 API에 TypeSpec을 쓰고 있는데, GraphQL처럼 API를 설명하면서도 설계 우선으로 접근할 수 있는 도구를 찾고 있었음
  OpenAPI 편집기들은 전부 너무 둔하고, API 안의 데이터 관계가 잘 드러나지 않았음. TypeSpec은 딱 찾던 도구였고 여기서 정말 도움이 됐다

• Microsoft가 자사 제품을 직접 쓰는 “도그푸딩”의 가치를 믿는다고 하지만, 네이티브 Windows 데스크톱 개발의 난잡한 생태계나 모바일 앱에서 Xamarin/MAUI 채택을 보면 그렇게 보이지는 않음

  • Windows는 네이티브 앱 개발 선택지를 전부 동시에 도그푸딩하고 있음
  • 도그푸딩이 새 기술이 나올 때마다 모든 것을 처음부터 다시 작성하라는 뜻은 아님
  • 새 정책이거나, 이 제품에만 해당해서 마케팅하기 좋은 경우일 수도 있음
    Microsoft Graph로 이메일을 관리해 봤는데, Outlook이 그걸 쓴다면 꽤 놀랄 것 같음

• Microsoft에서 나온 것이니 GraphQL에 대한 답변처럼 보임. 내부에서 도그푸딩한다면 오픈소스 컨소시엄이 급조한 것보다 도구 품질이 어느 정도 괜찮을 수도 있음
  아직 확신은 없지만, 더 큰 관심을 받을 가능성은 있어 보인다

  • 팀에서 일하고 있는데, TypeSpec을 GraphQL과 같다고 보기는 어렵고 그래서 TypeSpec만으로 그런 위치가 되기는 힘듦
    GraphQL은 구체적인 애플리케이션을 만들기 위해 필요한 프로토콜, 오류 처리, 질의 의미론 같은 강한 전제들이 많음. 반면 TypeSpec의 핵심은 API를 설명하는 전제 없는 DSL에 가까움. 특정 프로토콜 바인딩은 라이브러리로 추가되고, GraphQL 라이브러리도 오래전부터 검토해 온 대상임
    요약하면 Microsoft가 GraphQL과 비슷한 시나리오를 해결하는 전제 묶음을 만든다면, 그 맥락에서 API 설명 언어로 TypeSpec을 쓸 수는 있음. 하지만 그 전제들을 TypeSpec 자체와 동일시하는 것은 맞지 않다

• 핵심 질문인 지원 출력 언어를 찾지 못했음. OpenAPI로 내보낸 뒤 그쪽의 끔찍한 생성기 중 하나를 쓰는 수밖에 없는 건가?

  • 직접 이미터를 만들 수 있고, 문서에 방법이 나와 있음. 우리 팀은 TypeSpec용 커스텀 이미터를 만들어 SDK와 라이브러리 묶음을 출력했음

• TypeScript 버전의 WSDL처럼 보임
  https://en.wikipedia.org/wiki/Web_Services_Description_Langu...
  WSDL보다 오래 살아남을 수 있을까?

  • 아직도 WSDL을 쓰고 있고, 정확히는 내가 일하는 플랫폼이 씀. 새 기술로는 인기 없을지 몰라도 여전히 살아 있음. 욕해도 좋지만, YAML을 생성하는 것보다는 생성된 XML이 낫다
  • 이미 알 수도 있지만, 더 정확한 비유는 WSDL+SOAP에 가까움
    WSDL과 SOAP는 XML로 정의되고, SOAP는 XML을 설명함. 이 기술들의 인기는 XML 전반의 인기 상승과 하락을 따라갔음. TypeSpec은 JSON과 protobuf를 설명하니, 그 포맷들의 인기가 식으면 TypeSpec도 인기를 잃을 가능성이 큼
  • WSDL의 문제는 여러 거대 기업 위원회가 설계했다는 데 있었음. 그래서 일관성이 없고 비대했음. 많은 XML 관련 표준도 마찬가지였고
    요즘 대기업들은 함께 일하기보다 자기 해법을 시장에 던져 점유하려는 쪽을 선호함. 그 결과 한 팀이 단일 목표에 집중해서 만들기 때문에 품질이 더 나은 접근이 나오기도 함. 각자 의제가 다른 10개 벤더를 만족시키려는 것보다 낫다

• TypeSpec 파일을 TypeScript나 다른 언어에서 그냥 가져와서 TypeScript 타입을 자동으로 얻을 수 있으면 좋겠음
  코드 생성은 번거롭고 오류가 나기 쉽다

  • 대체로 코드 생성을 선호함. 왜 다른 방식보다 더 오류가 나기 쉬운지 모르겠음
    오히려 오류가 두 단계 추상화 속에 숨지 않아서 디버깅이 쉬워질 수 있음. 생성된 코드는 생성기의 부족한 점이나 버그를 우회하는 빌드 단계를 추가할 수도 있지만, 그렇지 않은 방식이면 그대로 감수해야 할 때가 많음
    “번거롭다”는 부분은 이해함. 즉각적인 피드백이 빌드 재실행보다 당연히 좋으니, 많이 반복 수정하는 영역에서는 반대쪽 장점도 커짐
  • TypeScript와도 매우 비슷해 보임. 애초에 API 설명에 TypeScript를 쓰면 안 되는 이유가 뭘까? TypeScript 타입을 얻고, /openapi에서 제공할 OpenAPI 스키마도 즉석 생성하면 될 텐데

• YAML을 원하는 도구 체인용으로 변환해줄 수 있을까?
  25년 전 CORBA IDL이 해줬던 것처럼, 여러 언어의 스키마와 스텁 생성을 해주는 고수준 IDL이 있으면 반가울 것 같음

  • 며칠 전에 내 OpenAPI 3 기반 코드 생성기에 TypeSpec을 입력 명세로 지원하도록 추가했음
    OpenAPI 문서로 변환하는 API를 제공해서 꽤 수월했음 (https://github.com/mnahkies/openapi-code-generator/pull/158)
    클라이언트 SDK와 서버 스텁 생성을 둘 다 하는 데 집중하고 있지만, 아직은 TypeScript만 지원함. TypeScript 템플릿 완성도에 만족하면 언젠가 다른 언어도 추가하고 싶다
  • OpenAPI와 JSON Schema 이미터는 YAML을 만들 수 있음

• 전용 언어는 설득하기 어렵고, 이를 만드는 팀에도 상당한 추가 노력이 듦
  사람들은 전용 언어를 배우고 싶어 하지 않음. 또 컴파일러, 문서, 언어 서버, IDE 통합, 의존성 관리 같은 언어 생태계 도구를 전부 만들어야 함
  비슷한 시도로 WaspLang과 DarkLang이 있는데, 실제 현장이나 HN에서 의미 있게 쓰이는 것을 아직 못 봤음. 기존 언어를 쓰고 부가 가치에 집중하는 편이 낫다
  개인적으로도 비슷한 가치, 즉 “진실의 원천 -> 모든 것”을 만드는 작업을 해봤고 이런 고통을 일부 겪었음
  https://github.com/hofstadter-io/hof
  아이디어는 CUE + text/template = API에 한정되지 않는 생성 도구임

  • 이걸 쓰거나 OpenAPI YAML을 직접 쓰거나 둘 중 하나임. YAML을 아는 사람에게도 기본 OpenAPI 정의를 잡고 쓰는 데는 이쪽이 손으로 OpenAPI 문서를 작성하는 것보다 훨씬 단순함. 직접 작성은 정말 고통스럽다
  • 생성형 AI 프로그래밍이 떠오르면서 새 언어는 더 큰 불리함을 갖게 됨. 객관적으로 더 나은 새 프레임워크라도 AI가 학습하지 않았다면 실제 생산성은 더 낮을 수 있음
  • hof 고마움. 한 프로젝트에 써볼까 생각 중임. 지금 프로젝트 상태는 어떤가? 최근 커밋이 줄어든 것 같아서, 현재 안정적이고 그대로 써도 되는지 궁금함