軟體架構設計：API 設計準則（二）、API Design-First 原則、策略與開發流程

軟體架構設計：API 設計準則（二）、API Design-First 原則、策略與開發流程

API Design-First 原則、策略與開發流程 Logo

圖片來源：https://coolshell.cn/articles/18024.html

前言

本篇文章是上一篇『軟體架構設計：API 設計準則（一）、API 的設計開發與挑戰』的接續。前一篇文章中，我們探討了 API 的開發與挑戰，這還沒結束，這篇我們來聊聊什麼是 API Design-First 優先設計？這與傳統的軟體開發有些不同，這與我們已經熟悉的 RESTful API 的以 Resource-Based 為設計的設計概念也有些不同，下面，我們就來探討吧！


為什麼需要 API 設計原則？

在說明為什麼需要 API 設計原則時，我得先回到一開始的主題 API Design-First 優先設計，為什麼需要 API Design-First 呢？因為 API 設計有別於傳統軟體開發，差異等等下方解釋，在設計 API 時講求有效的產出，首先是別企業體的或企業組織為維持市場競爭力與獲利所擁有的能力與模型稱為：【商業能力】，而在開發 API 時將將用戶與開發者視為第一考量，講求的是盡可能讓用戶在不牽涉過多技術細節便可調用這個 API。

在早期，許多企業未遵循 API Design-First 流程開發方法，而使用傳統方式設計 API，會後得到的結果可能就是『多次的砍掉重練及更冗長的開發週期』或最終 API 不為其他客戶所使用，甚至退出市場。


從 RESTful 到 API Design-First 優先設計

傳統 Resource-Based 的 RESTful API 

圖（一）、傳統 Resource-Based 的 RESTful API


原本我們熟知的 RESTful API 是將數位世界中的圖像、物件、後端的人員，都可稱為資源，這又稱作 Resource-Based API 的設計，因為 RESTful 將網路上的一切都視為資源。

但是在API Design-First 的概念裡面：

1. 資源 ≠ 資料模型

好的 API 設計提供的是該企業的數位能力，而不是後端的資料結構，因為 API 涉及的是跨企業之間的資料交換，這裡的 API 設計並不是傳統 SPA 應用程式裡面的 Front-end Framework 去呼叫的那個後端 API，這是兩個完全不同的開發情境，這必須先說明清楚。

另外優秀的 API 交付的是正確的結果，好的用戶端使用體驗，以及最好是避免被特定平台綁住、且 API 彼此交換地為標準 + 公開協定、跨平台的資料格式為基礎最佳。

因為 API 一旦公開，企業彼此之間其時就被這個 API 套牢，所以、正所謂，好的 API 帶你上天堂、不好的 API 帶你住套房。

2. 資源 ≠ 物件或是領域模型 (Domain Modeling)

另外，在 API Design-First 的概念裡，API 所操作的資源也不應該完全等於程式碼中的物件，應該額外的定義彼此交換的模型，因為直接使用描述商業邏輯的程式碼有可能因為變動性高而導致 API 因為直接耦合商業邏輯而導致需要修改。因此考量到可維護性，API Design-First 的結果性都不應該讓 API 用戶端看見後端的程式與資料模型。

所以，好的 API 也承襲了軟體開發中，最基礎的一些基本概念，像是 S.L.O.I.D.、模組、封裝、低耦合、高內聚等等。


究竟 API Design-First 與傳統軟體開發方法有何不同？

一般來說，就設計的順序而言，API Design-First 優先考慮撰在寫程式碼與設計使用者 UI 之前，就先設計 API，而傳統的軟體開發方法通常在核心應用程式邏輯和使用者介面設計完成之後，接著才開始設計對外之 API。

這與傳統的軟體開發方法形成鮮明對比對吧？在程式碼優先開發中，開發人員首先專注於建立服務及其所有資源，先建立 API Spec 而後先撰寫 API 程式碼，因為 API Design-First 強調協作關係，也就是前端和後端團隊以及利害關係人之間的早期團隊進行合作，不像傳統的軟體開發方法有很多孤立進行的工作，像是 SA/SD.. 等，然後系統整合又發生在後期，說到這裡會發現，這其實就是敏捷開發。

而底下的 ADDR 其實也從 DDD 發展而來，ADDR 的創作者 James Higginbotham 這麼表示。

傳統軟體開發 vs. API Design-First (ADDR) 

圖（二）、傳統軟體開發 vs. API Design-First (ADDR)


什麼是企業組織的『數位能力』？

在商業領域、企業組織為維持市場競爭力與獲利所擁有的能力與模型稱為『商業能力』，這是該企業得以謀生的企業命脈，或 Domain Knows-how，這種商業能力也可看作 Enterprise Business 或者數位化的 Application Business，但是所謂了（數位能力 ≠ APIs），能將此商業能力自動化、舉凡批次處裡、甚至電子檔案，各種企業組織提供之自動化機制的能力模型都算一種數位能力。

我舉個例子：

KKTIX 提供的售票網站服務提供支線上售票、提供顧客自行客製化活動的內容、金流等等.. 就是 KKTIX 提供之數位能力。

跨平台 API Framework 框架設計 V2 課程報名持續中

跨平台 API Framework 框架設計 V2 課程報名持續中

睽違 5 年的【跨平台 API Framework 框架設計 V2 課程】報名持續中，目前只要 $3300，報名只到 2024/11/07 要買要快！！ XDD

因為疫情因素，距離上次的實體課程已事隔五年，.NET Core 也從 2.1/3.0 進展到 .NET 8 了，而本框架也從 .NET 451 一路推進到 .NET 6、現在也全面更新到 .NET 8 的版本，藉由 .NET Core 的支援，功能也越來越強。

由於，小弟在許多企業端設計不少這樣的 API 框架，因此催生這個課程的出現，本課程一部份延續上一次的『跨平台的 Web API Framework 框架開發』 ，但是內容全部重新設計，畢竟早已事過境遷，隨然與上一堂類似，都是 API 框架設計，只不過本次會以更廣的以軟體架構設計的視角，來探討 API 框架設計😎。

在上一堂課程中，我們講述了一個從無到有建立 ApiHostBase 的基礎類別，來提供一種共用 API Controller來『動態』重複使用 Reuse 商業物件Business Object的一種方式，這次我們把架構眼界再往上提升一個層次，從六角架構的角度出發、並以框架設計為出發點、並基於一種使用者需求（線上租車需求為例）來設計一組服務此 Core Domain 的框架🧐。

課程大綱（Agenda）：

● 究竟什麼是 (Design)？什麼是 (Architecture)？

  • API 設計的挑戰、從 API 來重新檢視基本軟體設計原則
  • 從 S.O.L.I.D. 角度來規劃你的 API 框架
  • 什麼是軟體架構？設計模式？
  • 又要模組化、封裝、低耦合、高內聚？拿捏得當比較重要！
  • 你需要什麼？或你想要什麼？
  • 實作：一個簡單的租車需求 
    • 從整潔架構談自定義 NuGet 套件規劃與使用
  • 套件的定義？哪一類的程式碼應該歸類為套件？
  • 從 Clean Architecture 的角度來談框架內的 NuGet Packages 的規劃與使用
    • EasyArchitecture Framework 的現有架構規劃
  • EasyArchitecture 要達成的目標 
    • 一切從可重複使用 Re Use 開始
  • 如何設計你的範本：從你的範本開始 
    • 設計你自己的 Web API Framework 框架 
    • Q & A 

目前有開放早鳥喲!!! ?? 只要 $2900 ~只開放5張~ 先搶先贏!! 賣完就沒啦!! 😎

原價：$3300

報名傳送門： https://mystudyway.kktix.cc/events/apiframeworkv2

留言

張貼留言

這個網誌中的熱門文章

什麼是 gRPC ？

圖片
圖片取自： https://grpc.io/docs/guides/ gRPC 是什麼？能吃嗎？ 在安裝了 .NET Core 3.0 之後，眼尖的朋友應該會發現，在新增 ASP.NET Core 網頁類型專案裡，會看見一個 gRPC Service 類型的專案，其實它也不是什麼很新的東西，早在十多年前 Google 就使用這樣的 RPC 協定進行一些大量的可靠性微服務的存取，聽到這，難道現有的 Web API 不可靠嗎？其實不是的，它主要用在移動設備等提供高效簡單且跨平台的通訊與熱插拔的驗證機制。 gRPC 的運作原理 gRPC 顧名思義，是種基於 RPC 的通訊協定，不同於 Web API 走的傳統 HTTP 基礎協定，它有點像是 Socket ，但應該說是基於 Socket， 或精確地來說它是基於 HTTP/2 的協定 ，gRPC 是種協議緩衝協定，它必須事先定義 IDL (Interface Definition Language) 描述檔，看到 IDL 對於一些熟悉 COM／DCOM 的朋友一定非常的熟悉，對！沒錯！就是類似的東西！但，這邊的 IDL 是用一種副檔名為 .proto 檔案來是先定義在分散式環境中，要傳輸的序列化結構資訊，當然它也可以跟 JSON 一起使用。 也就是說，要使用 gRPC 您必須先定義 .proto 協議，然後透過 Compile 的支援，編譯成特定語言框架。而很高興的是，C# 也支援了，然而其實根據官方的資料顯示，C# 應該在 .NET Core 2.1 開始就支援了，只是到了 .NET Core 3.0 才有樣版的支援。 而使用 gRPC 的協議緩衝區的服務可以做到 Stub 的機制，也就是說，它就像是許多 RPC 一樣，Client 在呼叫 Server 端時，其實是對 Stub 進行叫用，Stub 在這就像個緩衝區一般，但更細部的說，應該是一個遠程服務的替身，這應該又讓許多熟悉 COM／RPC 通訊的朋友覺得熟悉了起來，是的！沒有錯。 在 .NET Core 3.0 裡使用 gRPC 目前支援 .proto 擴展為 gRPC 協議緩衝區的編譯器只有 .NET Core 了 ， 根據 Github 上的說明 .NET Framework 4.5+ 以上或 Mono 4+ 以上也可支援，而 gRPC 也完全的跨平台。要在 .
閱讀完整內容

什麼是 gRPC（二）- 來撰寫第一個 Hello World 吧！

圖片
前言 上一篇 什麼是 gRPC ，筆者大致介紹了 gRPC Service 的基本概念，這一次，我們就來小試一下身手，撰寫一個 Hello World （迷之音：嘗試新技術時，總是得先來一個 Hello World ～我不想違背這良好傳統阿阿阿阿） 使用環境 Visual Studio 2019 .NET Core 3.0.100-preview3-010431 開始進行 撰寫 gRPC 除了先準備好基礎環境、選定一種 作業系統／ 程式語言 Language 外、（Framework／SDK／Runtime）等環境備妥後，就可以開始撰寫， (1). 開始撰寫 gRPC 第一步就是先定義 .proto 協議了 上一篇筆者提到，gRPC 的 Server 與 Client 必須使用相同的協議才可進行溝通，一般來說，你應該使用 protoc.exe 編譯器先行編譯過 greet.proto 協議檔，並產出 C# 程式碼檔案後才可繼續，而在 Visual Studio 2019 裡，拜 MSBuild 之賜，已經有人預先寫好 .Target 檔案了 （什麼是 MSBuild ？什麼是附檔名 .Target 檔案可參考： MSBuild .targets 檔案 ） 筆者先撰寫一個 SayHelloWorld 方法如下： 在協議裡，除了在 service Class 撰寫要公開存取的方法外， 必須在提供『傳入訊息型態』、『回傳訊息型態』 ，這邊我先定義兩個 message，一個是『 HelloMyFirstgRPC 』、另一個是『 HelloMyReply 』 在撰寫 proto 協議檔時，建議先決定 message 回傳型態與傳入的型態，那麼 Visual Studio 2019 會有 InteillSense 的完整支援。不得不說 Visual Studio 2019 在 .proto 協議編輯上的支援已經算不錯了。 注意： 一般來說，Visual Studio 2019 會在背景裡自動編譯 .proto 協議檔案，但始有可能不會有任何提示，所以您也可以自行使用命令列工具進行手動編譯，如下圖，若編譯失敗會出現錯誤訊息，如下圖顯示 return 關鍵字錯誤： protoc.exe 編譯器 & 相關 MSBuild Tools 會隨著 NuGet 套件在 Vis
閱讀完整內容