每日突破性工具推薦｜Microsoft TypeSpec 1.16

Microsoft TypeSpec 1.16：把 API 規格從「文件」提升成可編譯的型別來源

Microsoft TypeSpec 1.16.0 於 2026-09-09 發布。這次推薦它，不只是因為版本新，而是因為 TypeSpec 採取了一條和傳統 OpenAPI-first 不同的路線：先用具型別、可組合、可擴充的描述語言定義 API，再由 compiler 與 emitters 產生 OpenAPI、JSON Schema、Protocol Buffers，以及各種 SDK／server artifacts。

這使 API specification 從「需要人工維護的一份 YAML/JSON 文件」轉變成「可以編譯、檢查、重用與生成多種輸出的原始碼」。對 API 數量大、跨語言 SDK 多、需要長期版本治理的團隊尤其有價值。

工具定位與適用情境

TypeSpec 是一套 API design language + compiler toolchain。它最適合處理以下情境：

大型 REST API，需要產生 OpenAPI 3.x。
同一份 domain model 需要輸出 JSON Schema、REST contract 或 Protobuf。
API 有多版本演進需求，需要明確描述某個 model／operation 在哪個版本加入、移除或改變。
平台團隊希望建立共用 API design rules、decorators、lint rules 與自訂 emitter。
需要從 API contract 進一步產生 SDK、server stub、文件或其他內部 artifacts。

它不是 Web framework，也不負責 HTTP server runtime；它處理的是更上游的「API contract source of truth」。

突破性重點

1. 把 specification 變成真正可編譯的語言

OpenAPI 通常是 YAML/JSON document model；TypeSpec 則提供 model、scalar、union、interface、template、decorator、namespace 等語言結構。

因此 API schema 可以像程式碼一樣抽象與重用，而不是大量複製 properties、responses 與 schema fragments。

最終流程變成：

TypeSpec source → compiler type graph → protocol libraries → emitters → OpenAPI / JSON Schema / Protobuf / SDK artifacts

這種模式本質上比較接近 compiler frontend，而不是 schema formatter。

2. 一份 semantic model 可以對應多種協定

TypeSpec 官方 emitter 能輸出 OpenAPI、JSON Schema 與 Protocol Buffers。Emitter 並不是單純字串模板，而是透過 compiler API 讀取已解析完成的 type graph，再選擇與目標協定相關的資訊產生 artifact。

這讓同一個 domain model 可以被多種 transport 或 tooling 使用，而不必讓 OpenAPI 本身成為所有系統的最底層資料模型。

3. API versioning 被納入語言模型

TypeSpec 提供 versioning library，可描述版本、@added 等演進資訊。這對大型 API 特別重要，因為版本差異不再只能透過維護多份 spec 或外部 script 解決。

4. 1.16 開始強化「TypeSpec 作為工具平台」的能力

1.16 新增 experimental $provideTypeInfo provider 與 program.getTypeInfo(type) API。Library 可以針對 type 提供額外 domain-specific 資訊，而 language server 或其他 tooling 可以按需查詢。

HTTP library 已利用這個機制提供 operation 的 resolved HTTP route、method 與 response status 等資訊。

值得注意的是 provider 採 lazy/on-demand 模式，而且不允許修改 type graph。這比把所有 tooling logic 塞進 compiler validation lifecycle 更乾淨，顯示 TypeSpec 正逐步把 compiler、IDE、library ecosystem 分層。

5. 可共享的 lint policy

1.16 支援從獨立 YAML 檔案載入 linter ruleset。對 monorepo 或企業 API governance 很實用：不同 repo 可以共享並版本化同一組規範，而不必為單純的 lint policy 額外發布 library package。

6. Union constraint 開始變得更強

1.16 加入 experimental union extends，允許要求 union 的每個 variant 都 assignable 到共同 base type。

這不是傳統 OOP inheritance，而是一個 compiler constraint；emitters 也能透過 Union.baseType 理解所有 variants 共享的共同結構。

核心架構與運作方式

TypeSpec 大致可拆成四層：

Language / compiler：解析 .tsp，建立 semantic type graph，執行型別與 constraint 檢查。
Libraries：例如 @typespec/http、@typespec/versioning，透過 decorators 與 compiler extension 將 domain semantics 加到 type graph。
Emitters：讀取 compiler program，將相關模型映射成 OpenAPI、JSON Schema、Protobuf 或其他輸出。
Tooling：language server、formatter、linter、自訂 generator 與 SDK emitter。

重要的是 emitter 不需要把 TypeSpec 當純文字處理，而是直接操作 compiler 已理解的 semantic model。這也是 TypeSpec 比單純「從 YAML 產 code」更有擴充性的原因。

主要優勢

高度減少大型 API 的重複定義

Template、model inheritance/composition、decorator 與 reusable libraries 能把常見 pattern 提升成可重用 abstraction。

API contract 與 code generation 更接近 compiler pipeline

API schema 先經 type checking，再交給 emitter。這比直接生成或拼接 YAML 更容易在 build 階段發現結構錯誤。

適合建立組織級 API platform

團隊可以建立自己的 decorators、lint rules、libraries 與 emitters，把命名、pagination、error shape、authentication、versioning 等規範直接變成 toolchain，而不只是寫在文件裡。

多輸出格式是一等能力

官方架構本來就假設同一份 TypeSpec 可能被不同 emitters 消費，而不是只服務 OpenAPI。

相較同類型工具的優點

相較直接維護 OpenAPI

OpenAPI 的優點是通用、成熟、工具多；但 YAML/JSON 在大型模型上容易重複，而且 abstraction 能力有限。

TypeSpec 可以把 OpenAPI 當成 build artifact：開發者維護較高階的 TypeSpec source，再產生 OpenAPI 給既有 gateway、documentation、client generator 或 validation ecosystem 使用。

這代表採用 TypeSpec 不等於放棄 OpenAPI，反而可以把 OpenAPI 降到 interoperability layer。

相較只針對 Protobuf / gRPC 的 schema workflow

Protobuf 非常適合 binary RPC contract，但 TypeSpec 的設計目標更廣，能同時描述 HTTP API、JSON Schema 與 Protobuf-oriented model。對需要 REST + event/schema + RPC 多種輸出的平台更有彈性。

相較一般 code-first API framework

Code-first framework 通常從 runtime implementation 推導 API schema；TypeSpec 把 contract 獨立在 runtime 之外，因此 frontend、backend、SDK、gateway 與文件工具可以在 implementation 尚未完成時就共享同一份 contract。

缺點與限制

多一層語言與 toolchain

團隊除了 TypeScript／Java／Go 等實作語言之外，還需要理解 TypeSpec syntax、decorators、compiler 與 emitter concepts。小型 API 可能得不償失。

生態仍不如 OpenAPI 本身普及

最終 interoperability 通常仍會落到 OpenAPI、JSON Schema 或 Protobuf；TypeSpec 是 upstream authoring layer，而不是取代所有下游標準。

自訂能力越強，治理成本也越高

自訂 decorators、libraries、lint rules 與 emitters 可以建立非常完整的 platform，但如果缺乏規範，也可能形成另一套內部 framework，需要專人維護。

Experimental 功能需要審慎採用

1.16 的 type info provider 與 union extends 仍屬 experimental compiler feature，不適合在無升級策略的核心 contract 中立即重度依賴。

適合的使用者與專案

擁有大量 REST API 的平台型產品。
需要同時維護多語言 SDK 的 API provider。
Azure／cloud service 類型的大型版本化 API。
Monorepo 內有多個服務，希望統一 API conventions。
正在建立 internal developer platform、API governance 或 schema compiler pipeline 的團隊。
想保留 OpenAPI compatibility，但不想直接長期手寫大型 OpenAPI YAML 的團隊。

不適合的使用者與專案

只有數個 endpoint 的小型 CRUD 服務。
完全 code-first，而且不需要 SDK／schema／跨語言 contract 的專案。
不願增加 build tooling 或 DSL 的小型團隊。
只需要一份簡單 OpenAPI 文件、且目前維護成本很低的既有系統。

結論

TypeSpec 真正值得關注的地方，不是「又一種 API 描述語言」，而是它把 API design 拉回 compiler architecture：以 typed semantic model 作為來源，再透過 libraries 與 emitters 投射到不同協定與工具鏈。

1.16 的 type-info provider、共享 linter ruleset 與 union constraint 進一步強化了這個方向。對小型服務而言它可能過重，但對 API 數量多、版本長、SDK 多、需要組織級治理的系統，它很可能比直接維護 OpenAPI 更適合作為長期 source of truth。