軟體架構設計：有『題』（二）- 為X宏網路售票系統加入 API First 網站

軟體架構設計：有『題』（二）- 為X宏網路售票系統加入 API First 網站

前言

在上一篇文章〔軟體架構設計：有『題』- API 設計原則以『線上售票系統為例〕裡面，我們幾乎在 LINQPad 上完成了一個線上購票的雛形，而這一次，一個部分是我們會再持續的建模的過程中補足一些上一次的缺失部分、第二部分則是加入網站設計部分，而這個網站會使用先前我在某客戶端所開發的 API Framework 框架為基底來設計，除了完全支援 >NET 6 外，這個框架封裝的許多在 Clean Architecture 裡屬於 Infrastructure 的部分，包括 【Role Security Access Controll Layer】與【Notification】以及【Log】等功能，更細部的部份我們下面再來談。

持續的建模

針對上一次，我們在X宏網路售票系統中用 UML 所呈現的 DDD 的 Domain Modeling 與 對照 Scenario 可以發現幾個小缺失。

(1). 加入 ShowTime 的 ValueObject (2). 建立 SeatReservation 實體的 Create 方法 (3). 調整 ConcertVenue 音樂會場地物件實作

另外，也針對 Application Services 的 購票作業 Reservation 方法調整程式碼邏輯，因應票卷 Ticket 由 Ticket.Create 方法來產生，並需要傳入（訂位代號：ReserveID; 場次：ShowTime）

程式碼中使用的術語，完全參照 Domain Modeling 與 事件風暴 中所精練出的通用語言 (Ubiquotius Language)，以確保程式碼完全可以對照領域模型，建模的過程也完全可以撰寫程式碼，並確保在最短的週期裡完成程式碼的設計與修改。

程式碼調整如下：

Domain Layer 的程式碼

public interface IAggregateRoot
{
}

public class Entity
{	
}

public abstract class ValueObject
{
    
}
// 票卷實體
public class Ticket: Entity, IAggregateRoot
{
    private SeatReservation _seatReservation;
    public SeatReservation SeatReservationInfo => _seatReservation;
    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(), _seatReservation = reserve };
    }
}
// 預定位 Entity
public class SeatReservation: Entity
{
    public Guid Id { get; protected set; }
    public string ReserveName { get; protected set; }
    public ConcertVenue ReserveConcertVenue { get; protected set; }
    public ShowTime ShowTime { get; set; }
    // 確認與預訂票卷
    public Ticket SetReservat(Ticket ticket)
    {
        return ticket;
    }
    public string[] GetReserveByDate(TimeSpan reserveRange)
    {
        return new string[] {};
    }
    public static SeatReservation Create(string ReserveName, ShowTime ReserveShowTime)
    {
        return new SeatReservation() { Id = Guid.NewGuid(), ShowTime = ReserveShowTime };
    }
    // 檢核購票時間、並檢核選擇票種是否還有位子？（如預定是空位，則傳回：true; 否則傳回：false）
    public bool CheckVenueIsExist()
    {
        return true;
    }
}

public class Membership: Entity
{
}

public class Account: Entity, IAggregateRoot
{
}
// 演唱會場次
public class ConcertVenue: ValueObject
{
    public int ShowTimeNum { get; set; }
    public string ShowTimeName {get;set;}

}
// 演出時間
public class ShowTime: ValueObject
{
    public ShowTime(DateTime? startShowTime, DateTime? endShowTime) 
    {
        if(!startShowTime.HasValue || !endShowTime.HasValue)
        {
            throw new ShowTimeNotDefinedException(@"票種的開始時間 startShowTime 與 結束時間 endShowTime 不可為空白！");
        }
        _startShowTime = startShowTime;
        _endShowTime = endShowTime;
    }
    private DateTime? _startShowTime;
    public DateTime? GetStartShowTime()
    {
        return _startShowTime;
    }
    private DateTime? _endShowTime;
    public DateTime? GetEndShowTime()
    {
        return _endShowTime;
    }
}
// 票種場次未定義的自訂錯誤 Exception
public class ShowTimeNotDefinedException: Exception
{
    public ShowTimeNotDefinedException(string message) : base(message) {}
}
// 無效的訂位紀錄（可能該座位已經被預訂；或者是資料輸入有誤）
public class InvalidSeatReservationException: Exception
{
    public InvalidSeatReservationException(string message) : base(message) {}
}

Application Services

在應用層部分，調整（建立/產生）票卷 Ticket 實體的流程，先完成預定票卷的實作。

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)
        {
            // 建立票種、若選擇時間有票種，進行購票作業
            SeatReservation seat = SeatReservation.Create(ticketDto.ReserveID, ticketDto.ShowTime);
            
            // 產生新的票卷（此預定保留 10 分鐘）
            Ticket ticket = Ticket.Create(seat);
            
            // 檢核購票時間、並檢核選擇票種是否還有位子？
            if(!ticket.SeatReservationInfo.CheckVenueIsExist())
            {
                throw new InvalidSeatReservationException("可能該座位已經被預訂, 或者是資料輸入有誤!");
            }
            
            // 預訂票卷（此預定預設保留 10 分鐘、即便執行了 SeatReservat() 但若未付款，10分鐘取消資格，將釋放此預訂票種給其他訂票作業的 Transaction）
            ticket = seat.SetReservat(ticket);
            
            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 ShowTime ShowTime {get;set;}
    }
}

加入 API First 網站設計部分

這邊的場景，我們切換到 Visual Studio 裡，使用我預先撰寫好的 API Framework Template 進行套入，原先在 LINQPad 裡的程式碼我們就直接貼為各 Assembly 並切開耦合性，完全符合在 ［API 設計原則-API與微服務傳遞價值之道］一書裡，先切分 (Package) 再 切分 (Layer) 設計技巧。

(1). 安裝 EasyArchitectVSIXProject 並新增一個 EasyArchitectV2CoreWebHost

圖（一）、安裝 EastArchitectVSIXProject 套件 安裝 EastArchitectVSIXProject 套件

這裡，圖示為齒輪的為支援 .NET 6 版本的 API Framework、未來也會支援 .NET 7/8

(2). 如果熟悉 TDD 的開發者，這裡就可以針對 Domain Layer 寫紅燈測試

(3). 撰寫 XConcertTicketsController 的 SeatReservation 的 API 方法

這裡，Infrastructure 全由 API Framework 框架所提供，所以開發人員能夠『專注』在訂票的商業邏輯上的設計，這裡我直接引用我 API Framework 裡的 API First 範本：EasyArchitectV2ApiHostController

這裡 EasyArchitectV2ApiHostController 更名為 XConcertTicketsController

所有的 API Controller 程式碼均由 Templates 自動產生，這裡我只撰寫 SeatReservation 的 API 方法，完整 API Controller 程式碼如下：

using Application.ConcertTickets;
using Domain.ConcertTickets;
using EasyArchitect.OutsideApiControllerBase;
using EasyArchitect.OutsideManaged.AuthExtensions.Attributes;
using EasyArchitect.OutsideManaged.AuthExtensions.Filters;
using EasyArchitect.OutsideManaged.AuthExtensions.Services;
using Infrastructure.ConcertTickets;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Mxic.FrameworkCore.Core;
using System;

namespace Web.XConcertTickets.Controllers
{
    /// <summary>
    /// X宏網路購票系統
    /// </summary>
    public class XConcertTicketsController : OutsideBaseApiController
    {
        private readonly IUserService _userService;
        private readonly IUriExtensions _uriExtensions;

        /// <summary>
        /// X宏網路購票系統範例
        /// </summary>
        /// <param name="logger"></param>
        /// <param name="userService"></param>
        /// <param name="httpContextAccessor"></param>
        public XConcertTicketsController(
            ILogger<OutsideBaseApiController> logger, 
            IUserService userService, 
            IUriExtensions uriExtensions,
            IHttpContextAccessor httpContextAccessor) 
            : base(logger, userService, httpContextAccessor)
        {
            _userService = userService;
            _uriExtensions = uriExtensions;
        }

        /// <summary>
        /// 訂票作業
        /// </summary>
        /// <param name="ReserveName"></param>
        /// <param name="startShowTime"></param>
        /// <param name="endShowTime"></param>
        /// <returns></returns>
        [NeedAuthorize]
        [HttpGet]
        [APIName("SeatReservation")]
        [ApiLogException]
        [ApiLogonInfo]
        public async Task<ReserveResponseDTO> SeatReservation(string ReserveName, DateTime? startShowTime, DateTime? endShowTime)
        {
            Application.ConcertTickets.ConcertTicketAppService app = new ConcertTicketAppService(new ReserveRepository());
            ReserveResponseDTO result = app.Reservation(
                new ReserveDTO()
                {
                    ReserveID = "XXXXX10001",   //訂位代號（流水號）
                    ReserveName = ReserveName,  //定位大名
                    ReserveTime = DateTime.Now, // 訂位時間、不等於票種時間 或 演唱會場時間 (the showtime for Concert Venue)
                    ShowTime = new ShowTime(startShowTime, endShowTime)
                }
            );

            return await Task.FromResult(result);
        }
    }
}

以上，我們大致完成網路的訂票作業系統的初步設計，這已經算是比較完整的設計了，也完全遵循 API First 的設計方法，下次，我們再來探討搭配 TDD 的實作技巧。

待續...

文章範例程式：

https://github.com/wugelis/CleanArchitectXConcert


# 關於我：

Gelis 吳俊毅 - 資深 .NET 技術顧問

FB 社團 (軟體開發之路)：

https://www.facebook.com/groups/361804473860062/

FB 粉絲團 (Gelis 的程式設計訓練營)：

https://www.facebook.com/gelis.dev.learning/

我講授過的課程 SlideShare：

https://www.slideshare.net/GelisWu

GitHub：

https://github.com/wugelis

留言

張貼留言

這個網誌中的熱門文章

什麼是 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
閱讀完整內容

常見的程式碼壞味道（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 不過原歸正傳，我個人還是認為，其實適當
閱讀完整內容