軟體架構設計：有『題』- API 設計原則以『線上售票系統為例』

軟體架構設計：有『題』- API 設計原則以『線上售票系統為例』



前言

先前，我有篇文章是以讀過【Get Your Hands Dirty on Clean Archiecture】後的心得感想，這本書的中文名稱是：【Clean Architecture 實作篇：在整潔架構上弄髒你的手】，讀完這本書大約是去年 2022/10 月左右，也是我當時在開發 API 新版框架大爆發的時候，書中給我不少的啟發，在配合實際的專案開發的實作經驗 + 框架設計所需要的框架設計便引入六角架構的設計方式，藉以改良原有的舊版的框架，而這篇『軟體架構設計：無題 (http://gelis-dotnet.blogspot.com/2022/08/blog-post.html)』中便是以完整的〔六角架構 (Hexagonal Architecture)〕並加以解釋如何在六角架構中落實單元測試 Unit Test，這些都是我讀完書後，實際落實在專案上的實際做法 + 分享。

當時的六角架構 + Unit Test 的範例程式在這：https://github.com/wugelis/AdapterInOutLayerSapmle

上次是無題，今天，我以一個X宏線上售票系統為例子，我們從頭到尾地的，Step By Step 的來介紹，這個 API 售票系統的建置過程，而這裡，我也會搭配 『API 設計原則』一書裡的一些做法，也就是說，這裡開發的 API 會使用 API First 的設計樣式，因為這裡的 API 設計的出發點為該企業、在這個商業模式上所能夠提供之『商業能力』回出發點考量，而不是過往傳統的單一客戶(UI)思維的客製化模式考量，所謂的 API First 是轉向為產品化思惟的導向模式，如此也才能發揮 API 在市場上的價值，這也才是 API First 的思維模式。

需求來源

圖（一）、線上售票系統需求 線上售票系統需求

今天的需求來源，是一個線上售票系統，先前我曾在專案中製作過一個售票系統的雛形，這裡我就拿這個範例來以 DDD 來進行戰略建模，並搭配使用我在新竹顧問時所開發的新版 API Framework 來實作並支撐這個售票系統 API 的 Infrastructure Layer，沒錯，所以言下之意，我們以 DDD 來驅動這個售票系統 API 的開發，所以這裡的 Core Domain 就是這個 API 主要的商業能力。

從事件風暴到領域模型

圖（二）、DDD 的戰略建模 - Bounded Context DDD 的戰略建模 - Bounded Context

從圖（一）需求得知在購票流程裡，除了可以線上購票外，購票成功後會發送簡訊通知，這裡我們找到 3 個 Contexts 並確定其系統邊界，這 3 個 Contexts 分別是：購票、管理票卷、簡訊發送。整個購票作業還需要 Generic Subdomain 來支撐，像是我前面提到的 API 的 Framework 會提供 OAuth2 與 JWT Token 的 Infrastructure 的底層能力。

一次只看一種業務問題即是 Problem Space 的主要目標，透過這個方式來看我們的這個（產品/專案）的商業目標，我可以將這些商業目標拆分如下的 Subdomain：

  • 購票：Core Domain
  • 登入購票網站：Generic Subdomain
  • 簡訊通知：Generic Subdomain
  • 管理票卷：Supporting Domain

讓領域模型關連到程式碼

圖（三）、透過事件風暴(Event Storming) - 進行建模 透過事件風暴(Event Storming) - 進行建模

這邊管理票卷劉在下次，我先針對 Core Domain 來進行 API First 的建模，這也是售票系統主要提供的商業能力。

圖（四）、DDD 戰術建模 - Domain Modeling DDD 戰術建模 - Domain Modeling

到這裡，我們已經可以進行戰術建模 + 繪製領域模型 Domain Modeling 了，因為經由事件風暴可以得知 UI 應該提供『選擇座位』、『選擇演唱會場次』、『選擇票種』的 Command，這些即可以直接繪製 Domain Modeling 並清楚的表達出劃位 (Seat Reservation) 動作、產生 Ticket 的購票作業，以及相關的 Value Object

程式碼實作

這裡以整潔架構為基底，先刻劃出 Domain Layer：

public interface IAggregateRoot
{
}

public class Entity
{	
}

public abstract class ValueObject
{
    
}

public class Ticket: Entity, IAggregateRoot
{
    public Guid Id { get; set; }
    public string ReservatName { get; protected set;}
    // 確認購票
    public int SaveTicket()
    {
        return 0;
    }
    // 建立票卷
    public static Ticket Create(SeatReservation reserve)
    {
        return new Ticket() { Id = Guid.NewGuid() };
    }
}
// 預定位 Entity
public class SeatReservation: Entity
{
    public Guid Id { get; protected set; }
    public string ReserveName { get; protected set; }
    public ConcertVenue ReserveConcertVenue { get; protected set; }
    public DateTime? ShowTime { get; set; }
    // 確認與預訂票卷
    public Ticket SetReservat(string name)
    {
        return new Ticket();
    }
    public string[] GetReserveByDate(TimeSpan reserveRange)
    {
        return new string[] {};
    }
    public static SeatReservation Create(string ReserveName)
    {
        return new SeatReservation() { Id = Guid.NewGuid() };
    }
}

public class Membership: Entity
{
}

public class Account: Entity, IAggregateRoot
{
}

public class ConcertVenue: ValueObject
{
    
}

接著是 Application Services 的實作，這對應到 UX 也可以是一個 Use Case ，我們先以購票這個 Domain Event 來進入，這裡的 Command 有些是 Query，不過因為有購票人就要有 Account 會員身分，最後要建立 Ticket 演唱會票卷，這些就有很多事情要做了。在上方 Domain Layer 我們先建好 Account, Ticket, SeatReservation, ConcertVenue 等 Entity 與 ValueObject 物件，接著，下面的 Application Services 便會參照到這些物件。

Application Services 設計的程式碼如下：

namespace Application.ConcertTickets
{
    public interface IReserveRepository
    {
        int SaveConcertReservation(Ticket ticket);
    }
    
    public class ConcertTicketAppService
    {
        private IReserveRepository _reserveRepository;
        public ConcertTicketAppService(IReserveRepository ticketRepository)
        {
            _reserveRepository = ticketRepository;
        }
        // 購票作業
        public int Reservation(ReserveDTO ticketDto)
        {
            // 檢核購票時間
            
            // 檢核選擇票種是否還有位子？
            
            // 若選擇時間有票種，進行購票作業（此預定保留 10 分鐘、若未付款，10分鐘取消資格，將釋放此預訂票種給其他訂票作業的 Transaction）
            SeatReservation seat = SeatReservation.Create(ticketDto.ReserveID);
            
            // 預訂票卷（此預定預設保留 10 分鐘）
            Ticket ticket = seat.SetReservat(ticketDto.ReserveID);
            
            return 0;
        }
        // 確認定位
        public int SaveReservation(Ticket ticket)
        {
            return _reserveRepository.SaveConcertReservation(ticket);
        }
    }
}
// DTO 組件
namespace Application.DTO
{
    public class ReserveDTO
    {
        public string ReserveID { get; set; }
        public DateTime? ReserveTime { get; set; }
        public int? ShowTime {get;set;}
    }
}

這裡即為一個透過事件風暴 (Event Stroming) 進行建模、到如何對應到實際程式碼設計的一個過程，這之中包括了整潔架構的軟體架構設計。

因為內容太多了，待續...

範例程式

https://github.com/wugelis/CleanArchitectXConcertLINQv2

留言

張貼留言

這個網誌中的熱門文章

軟體工程師 - 成長的 10 個階段

圖片
軟體工程師 - 成長的 10 個階段 前言 先前，我在 Study4 小聚 #6 分享的一場關於軟體工程師 & 架構設計的養成之路，在該議程中，我分享了軟體工程師的 10 個階段（你的階段如有雷同、應該是...純屬巧合。XDDD） 哪 10 個階段？ 我將軟體工程師的成長依序分為 10 個成長階段，因為隨著技能的提升，你該擴充的 不會只是只有軟體開發技術，溝通與協作能力尤其重要 ，也像是『康威定律』中所提到的， 你的軟件的設計 & 或系統設計本質上反映了企業的組織機構。系統各個模塊間的介面的設計，也反映了企業各個部門之間的信息流動和合作方式，這些技能再進行軟體架構設計時也息息相關 ，團隊在進行模組設計時需要頻繁的溝通，這些、都是是否能將軟體做好的關鍵因素。 如 Logo 圖片，我依序說明每個階段的成長歷程。 1). 初始開發階段、熟悉 Programming/Developer 階段（PM/PO/SD 給規格後加以實作出來），並能夠藉由 模仿 來學習。這是剛進入軟體產業的學習階段。 2). 此階段代表已懂得透過重構來讓程式碼有基本的可維護性 、已能熟用 DRY (Don't Repeat Yourself)，進入這個階段代表已經有基本的程式語言的基礎， 應付 Programming/Developer 日常 工作 上的需求基本上沒什麼太大的問題。 3). 這裡的專案收尾代表對於專案開發已經有某些程度的認知、掌握度。我所提的掌握度在於了解『技術債』的產生緣由 與 危害，在 Programming/Devloper 層面懂得透過 S.O.L.I.D./Design Patterns 解決問題 並 開始能夠 自我學習 + 自我成長 。 4). 我這裡用『紀錄』 代表能運用所學 + 將使用者需求運用 〔邏輯思考〕 與 〔抽象化〕 轉化為程式碼 + 並能 自我成長 將經驗保存下來。我認為這是跨越只是（寫程式／實作）進入另一個門檻的重要經驗與歷練。 這個階段花費的時間會較長一點，時間長短取決於個人歷練、經歷、學習的環境與工作內容。 5). 此階段含括上面所有技能，並能夠與〔團隊〕和〔客戶〕 溝通 與 協作 、並產生出〔產品〕。而所謂的協作代表，不只自身技術所長能應付本身開發工作工作所需，亦能帶領團隊解決軟體專案的大小事務、也能夠替...
閱讀完整內容

常見的程式碼壞味道（Code Smell or Bad Smell）

圖片
常見的程式碼壞味道（Code Smell or Bad Smell） 圖片取自：https://www.slideshare.net/ElMahdiBenzekri/art-of-refactoring-code-smells-and-microservices-antipatterns 前言 究竟重複的程式碼要不要共用它？傳統的軟體開發上，重複的程式碼幾乎被視為罪惡的來源，但是它真的有多可怕？ 常見的 Code Smells The Dispensable （一些可有可無的） Lazy Class (冗員類別） 如果一個類很少使用它會增加代碼庫的複雜性，從而阻礙開發。這樣的類可能是不必要的，它的功能可以成為另一個類的一部分。 Data Class (只有資料的類別） 一個類別只有包含『資料』未包含Methods，也就是說並未包含行為，不具行為模式的類別代表該『實例』容易被【其他類別所操控】。 Duplicate Code (重複的程式碼) 如描述，這也是上次有分享在我的 FB 社團 軟體開發之路［德國資深架構師給新手的建議］ 中有產生非常熱烈討論，這在社團朋友提醒下想起 Refactor 重構一書裡曾提過 rule of three 法則， 這個法則的定義是這樣的，有時部分程式碼重複其實是允許的（不是說重複一定是是被允許的）而是在某些 Context 情境下，該程式碼有一段時間不會衍伸別的功能 或 需求一段時間不會異動、且如要將它 DRY 會產生的『複雜度』或『花費時間』遠高於預估的時間 或 不值得在目前這個專案的節骨眼上花費這個時間來做這件事，加上它 DRY 產生的複雜度偶後產生的維護成本【遠高於】不 DRY 的情況下的維護本，那麼，在這個時候，這個異動頻率【極低】的程式碼就不需要花費這個時間來 DRY 了！！ 因為重點在於，重構是需要『成本』的。(迷之音：DRY 是種抽象化阿~😎) 這讓我想起之前，大約在 2016 年左右，在 101 的樓上某金融業客戶，曾經做過一個專案，這個專案就是因為客戶 DMZ 環境的因素，我讓內網的 Webside 與 DMZ 的網站保留了部分重複的程式碼，因為這段程式碼終年不需要異動，我也懶得花這個時間，而我居然也忘了這記件事情了.. 哈哈 Orz 不過原歸正傳，我個人還是認為，其實適當...
閱讀完整內容

什麼是 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 也完全的跨平台。要在 ....
閱讀完整內容