TypeSpec 是設計 API 的強大彈性語言。 它可讓開發人員以可延伸且易於理解的語言定義 API。 該編譯會使用發出器來產生 API 規格、用戶端程式代碼和伺服器端 API 程式代碼。 TypeSpec 是由Microsoft所開發的 開放原始碼專案 ，並由社群支援。
TypeSpec 可讓您建立模組化、可重複使用的元件，其簡潔且符合 API 指導方針。 標準 TypeSpec 連結庫包含 OpenAPI 發出器，可確保與現有工具和工作流程的相容性。
作為開放原始碼語言，TypeSpec 可以描述任何 API，而不只是 Azure 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 撰寫新的 API 規格，或從現有的 OpenAPI 規格移轉。 |
| TypeSpec 定義 | 使用 TypeSpec 定義 API。 可重複使用的元件可讓 API 簡潔，並確保符合指導方針。 |
| TypeSpec 編譯程式 | 編譯程式會處理 TypeSpec 定義，以準備它們以產生程式代碼。 |
| 世代 | 專用發出器會自動產生 API 規格、用戶端程式代碼和伺服器端存根程式代碼。 |
| 整合 | 產生的輸出會順暢地整合到現有的 API 工具鏈中。 |
TypeSpec 編譯器的路徑 ：
TypeSpec 編譯程式可以視需要同時產生 OpenAPI 規格、用戶端程式代碼和伺服器端存根程式代碼的輸出，同時允許您根據專案需求獨立觸發每個輸出。
產生 OpenAPI 規格
OpenAPI 發出器會產生標準化的 API 描述格式。產生程式代碼 Client-Side 代碼
用戶端程式代碼發出器會建立取用 API 的程式代碼。產生 Server-Side Stub 程式碼
服務端發出器會產生伺服器存根程式代碼來啟動 API 實作。
使用 TypeSpec 產生完整的程式代碼
用戶端程式代碼產生
TypeSpec 藉由直接從 TypeSpec 定義中自動建立程式碼來取用 API，從而精簡化用戶端代碼生成。 此程式會利用標準運行時間介面等重要功能，以確保無縫整合、自定義程式代碼擴充性，以針對特定用戶端需求量身打造輸出，以及跨越整個開發堆疊的完整產生。 因此，開發人員可以維護應用程式之間的一致性、減少手動編碼工作，以及快速整合 API 與現有的工具鏈，同時享有更有效率且可調整的開發工作流程。
支援的語言：
- 。NET
- 爪哇島
- JavaScript
- 蟒
伺服器程式代碼產生
TypeSpec 支援直接從 TypeSpec 定義產生伺服器端存根程式代碼。 這樣可簡化開發程式，並確保客戶端和伺服器實作之間的一致性。
支援的語言：
- 。NET
- JavaScript
主要功能：
- 標準執行階段介面：標準發射器最初專注於產生執行階段介面，以確保具有彈性並能輕鬆地與各種執行階段堆疊整合。
- 自定義程式代碼擴充性：TypeSpec 發出器提供自定義程式代碼擴充性，可讓開發人員根據特定需求量身打造產生的程序代碼，使其可適應不同的環境。
- 完整程式代碼產生：TypeSpec 支援跨整個開發堆疊產生程式代碼，從客戶端到伺服器，包括不同的通訊協定和資產類型，確保統一的開發方法。
藉由使用 TypeSpec 的服務端程式代碼產生功能，開發人員可以減少手動編碼、改善一致性，以及提升整體生產力。
與產業工具鏈的互作性
TypeSpec 與現有的產業工具鏈緊密整合，確保互作性，並提升生產力。 藉由從 TypeSpec 定義產生 OpenAPI 規格，開發人員可以使用專為 OpenAPI 設計的龐大工具生態系統，例如適用於 API 的 Swagger 檔、適用於 API 測試的 Postman，以及用於部署 API 的 Azure API 管理。 這包括設定 API 閘道、產生客戶端和伺服器程式代碼，以及驗證 API 資料。 此相容性可讓小組維護其目前的工作流程，同時受益於 TypeSpec 所提供的結構化且一致的 API 設計。
絕佳的開發人員體驗
開發者整合包括 Visual Studio Code 延伸模組 和 Visual Studio。 這些整合提供有效率且無錯誤編碼的功能，例如自動完成、語法醒目提示、建置時間錯誤識別、符號重新命名，以及檔格式設定。 例如，在 Visual Studio Code 中撰寫 TypeSpec 定義時，延伸模組會提供即時自動完成和語法醒目提示，讓您更輕鬆地撰寫正確且一致的 API 定義。
此外，TypeSpec 遊樂場 提供互動式環境，開發人員可以在即時 中對 TypeSpec 語法和功能進行實驗。 此 Web 型工具提供立即的意見反應和驗證，讓您更容易學習並採用 TypeSpec。 TypeSpec 遊樂場所提供的互動式實際作體驗會加深開發人員的瞭解和熟練程度，最終導致更一致、更高品質的 API 設計。 這些工具藉由簡化開發程式、降低錯誤的可能性，以及加速新小組成員的學習曲線，共同改善開發人員體驗。
為了進一步支援從現有 API 轉換的開發人員，OpenApiMigration 工具 提供將 OpenAPI 規格轉換成 TypeSpec 定義的有效率方式。 此移轉工具可簡化並加速採用 TypeSpec，同時保留現有 API 檔的完整性。 三個移轉範例包括：
真實世界的用法
TypeSpec 已成功用於各種產業，以簡化 API 設計和開發。 以下是一些範例：
- 電子商務：在線零售平臺使用 TypeSpec 來設計和記錄其 API，讓第三方服務順暢地整合，並改善整體開發人員體驗。
- Finance：金融服務公司採用 TypeSpec 以確保其 API 之間的一致性和合規性，減少 API 治理所需的時間和精力。
- 醫療保健：醫療保健提供者使用 TypeSpec 來設計適用於患者數據管理的 API，確保其系統的數據一致性和安全性。
開始吧
開放原始碼支援
- 我們重視並鼓勵您的想法、意見反應和貢獻，以協助改善專案。
- 如需如何參與的詳細資訊，請參閱 參與者指南。
- 如果您有問題或需要協助，請隨意 詢問社群 ，或在 GitHub 上提交問題。
瞭解更多資訊
請享受這些 YouTube 影片，以深入瞭解 TypeSpec：
- 大規模運用 TypeSpec API
- 使用 TypeSpec 進行架構優先 API 設計
- TypeSpec 101
- 使用 TypeSpec 制定開放金融標準