l

2024年9月18日 星期三

重構既有系統,邁向整潔架構 (6):第三回合,在使用案例層讀寫分離

September 18 17:52~18:52

▲這一集換Eiffel上場

 

工商服務

想了解本系列文章完整內容,請參考重構既有系統:邁向整潔架構實作班。課程介紹與報名網址在此:https://teddysoft.tw/courses/refactor-to-ca/

***

前言

上一集<重構既有系統,邁向整潔架構 (5):第二回合,套用DDD戰術模式>在基本領域模型中套用領域驅動設計(DDD)的戰術模式(Tactical Design Pattern),找出聚合(Aggregate),達到封裝與決定交易邊界的目的。這一集要處理程式碼最多的TaskList。

***

分而治之

TaskList程式碼如圖1、圖2所示,這時候可以將execute mehtod所呼叫的哪幾個private method升等成Class,以簡化TaskList的長度,並且可以觀察原本這些private method與TaskList之間的耦合關係。

 

▲圖1:TaskList程式碼,1/2

 

▲圖2:TaskList程式碼,2/2

***

Use Cases Layer新住戶

Teddy將這些被升等成類別的private method放到usecase package,如圖3所示。現在Clean Architecture已經慢慢成形,最重要的兩層(entity與usecase)已經都有「住戶」了。

 

▲圖3:將TaskList的private method升等成類別

***

 

區分Command與Query

為了讓use cases layer的成員責任更佳明確,Teddy進一步套用CQRS設計模式。同時,利用use case來「吶喊」系統功能;請參考圖4。

 

▲圖4:在 use cases layer吶喊系統功能,並將讀寫分離。

***

接下來看一個Command的程式範例,圖5為AddTaskUseCase介面,這是一個in port,讓第三層的Rest Controller呼叫。

 

▲圖5:AddTaskUseCase介面

 

Teddy把實作Use Case介面的物件稱為Service,圖6為AddTaskService程式碼。

 

▲圖6:實作AddTaskUseCase的AddTaskService

 

Query程式與Command類似,差別在於兩者實作的介面不同,請參考圖7與圖8。

 

▲圖7:ShowUseCase介面

 

▲圖8:實作ShowUseCase的ShowService

***

剩下的execute

重構至此還沒討論圖1中的execute method,它的用途是用來呼叫use cases layer的那些Command與Query。Teddy一樣幫它座艙升等為類別,請參考圖9。但是這個升等之後的Execute class不像use case,比較像分派工作給不同use case的dispatcher。在架構上現在還妾身不明,Teddy先把它直接丟在use cases layer最外層。

 

請考圖9,Use case layer重構至此已經差不多了。其中有一些細節,像是Repository、Mapper、DTO、Presenter這些設計模式,全部寫出來內容太多。請容許Teddy偷懶一下,在此省略。有興趣又有錢的鄉民,歡迎報名參加重構既有系統:邁向整潔架構實作班,課程中會有詳細說明。

 

▲圖9:重構後的完整usecase package目錄結構

***

下集預告

重構至此Clean Architecture的四層已經完成了兩層,下一集要處理interface adapters layer。

***

友藏內心獨白:人口越來越多,物件村快變成物件「市」了。

2024年9月17日 星期二

重構既有系統,邁向整潔架構 (5):第二回合,套用DDD戰術模式

September 17 16:20~17:57

▲被封裝在聚合內部的咪咪

 

工商服務

想了解本系列文章完整內容,請參考重構既有系統:邁向整潔架構實作班。課程介紹與報名網址在此:https://teddysoft.tw/courses/refactor-to-ca/

***

前言

上一集<重構既有系統,邁向整潔架構 (4):第一回合,分層與移除基本型別依戀>已經形成了基本的領域模型,這一集要在領域模型中進一步套用領域驅動設計(DDD)的戰術模式(Tactical Design Pattern),找出聚合(Aggregate),達到封裝與決定交易邊界的目的。

***

領域模型: 決定Entity, Value Object與Aggregate

圖1是上一集重構後的領域模型,ToDoList, Project, Task是Entity,Project Name是Value Object。為了簡化起見,Teddy將整個領域模型包成一個ToDoList Aggregate。

在DDD中,Aggregate與Repository是一對一的關係,一個Aggregate透過一個Repository存入資料庫。決定了Aggregate的邊界,之後如果有儲存領域模型狀態的需求(絕大多數的軟體系統都會有持久化的需求),只需要實作ToDoListRepository即可。

 

▲圖1:領域模型的四個類別

 

***

 

將Entity Id升級成Value Object

DDD的Entity是一個有「唯一識別符號(unique ID)」的物件,原本的ToDoList缺少這個id,因此新增ToDoListId value object作為它的id。Project可以用ProjectName當作它的id,至於Task有一個long id屬性可以當作它的id,但是考慮到以後Task id有可能是使用者自己指定的字串,因此一併幫它新增TaskId value object作為它的id。

增加兩個Value Object之後的領域模型如圖2。

▲圖2:領域模型現在有六個類別

***

 

封裝聚合

DDD的Aggregate是一個交易邊界,同時也是一個封裝單位。操作Aggregate內部物件的動作必須透過AggregateRoot,以避免客戶端破壞Aggregate Invariant。如果Aggregate回傳它內部Entity給客戶端,客戶端不可以直接修改這個Entity,以避免客戶端繞過Aggregate Root修改了Aggregate。

換句話說,Aggregate如果回傳內部Entity參考給外部物件,則這個Entity應該是唯讀物件

舉個例子,圖3是ToDoList(Aggregate Root)的getProjects()方法,回傳其內部的List<Project>。客戶端拿到這個List<Project>物件之後,有兩個途徑可能繞過ToDoList而破壞封裝:

  1. 直接在List中增加一筆Project。
  2. 直接修改某個Project的內容,例如在Project身上新增一個Task。

第一點可以透過回傳一個「不可修改的List」來避免,至於第2點就只能靠ToDoList將Project轉成自己設計的ReadOnlyProject來避免。

 

▲圖3:ToDoList::getProjects() 程式碼

 

ReadOnlyProject的實作很簡單,請參考圖4。它直接繼承Project,然後覆寫所有會改變狀態的methods,直接丟出UnsupportedOperationException。

▲圖4:ReadOnlyProject程式碼(部分)

 

Project與Task都需要一個唯讀版本,重構後的領域模型現在有8個類別,請參考圖5。

▲圖5:領域模型成長到8個類別

***

 

下集預告

經過一番努力,重構至此領域模型終於有物件導向領域模型的樣子。但是一開始看起來很「礙眼」的TaskList程式依然沒變,還是原本那個150行、看起來亂亂的樣子。沒關係,下一集Teddy再來對付它。

***

友藏內心獨白:重構也要價值驅動。

2024年9月16日 星期一

重構既有系統,邁向整潔架構 (4):第一回合,分層與移除基本型別依戀

September 16 17:48~18:40;19:49~20:39

▲從下層爬往上層的咪咪 (by 常玉)

 

工商服務

想了解本系列文章完整內容,請參考重構既有系統:邁向整潔架構實作班。課程介紹與報名網址在此:https://teddysoft.tw/courses/refactor-to-ca/

***

前言

前三集聊了:
  1. 重構既有系統,邁向整潔架構 (1):為什麼透過重構改善軟體架構很困難
  2. 重構既有系統,邁向整潔架構 (2):逆轉重構流程
  3. 重構既有系統,邁向整潔架構 (3):Task List Kata簡介
這一集終於要動手重構。
***

分層原則

Teddy在第二集提到要採用由上而下的方式來重構,首先套用Clean Architecture,確定架構分為四層,如圖1所示。
 
▲圖1:套用Clean Architecture的分層原則
 
其中Task這支只有不到30行的程式很明顯地屬於Entities Layer,將它移到entity package。150行的TaskList目前還不清楚屬於哪一層,先不移動它。
 
***
 
物件村沒人怎麼辦?
Teddy的重構目標是在架構上採用Clean Architecture,在Entities Layer與Use Cases Layer則是套用DDD(領域驅動設計)的戰略模式語言(Entity, Value Object, Service, Aggregate, Repository等)。現在「物件村(domain model)」只有一個Task,顯得有點孤單,要想辦法增加物件村的人口。
 
物件導向設計,顧名思義就是要透過物件(領域模型)來表達問題領域的業務邏輯。這個Task List Kata重構範例只有兩個物件,這種現象有一個可能性,就是設計者對於「基本型別依戀」,捨不得使用物件,只用了String, Int這些基本型別。因此,接下來Teddy要採用「只管移除基本型別依戀」的方式,來增加物件村的人口。
 
***
 
無腦移除基本型別依戀
請參考圖2,第17行Map<String, List<Task>> tasks,將它「座艙升等」成Tasks物件,如圖3所示。
 
▲圖2:TaskList程式碼片段
 
 
 
▲圖3:移除基本型別依戀,新增Tasks物件
 
***
套用Value Object
圖3中的Map<String, List<Task>> tasks,其中Map的key代表project name,因此將其座艙升等成Value Object,請參考圖4。
 
▲圖4:ProjectName value object,用Java record代表
 
***
 
引入共通語言(Ubiquitous Language)
請參考圖5,此時Tasks類別的第6行變成Map<ProjectName, List<Task>> tasks,這還是一個基本型別依戀。請問一個擁有一組Project Name對應到List<Task>的「概念」要怎麼稱呼它?在此Teddy將其稱為Project。因此我們進一步將Map<ProjectName, List<Task>> tasks重構成List<Project> projects,參考圖6。
 
▲圖5:Tasks類別
 
 
▲圖6:Project類別
 
 
最後,Teddy把Tasks類別改名成ToDoList,現在物件村已經有四個物件,請參考圖7。
 
▲圖7:物件村從1個住戶增加為四個住戶
 
***
 
下集預告
有了物件村的住戶(領域模型),下一集要在領域模型中套用DDD戰術模式(tactical design patterns),好好了解一下什麼叫做Aggregate, Entity, Value Object。

***

友藏內心獨白:只有一個物件變成全村的希望,這樣壓力太大。

 

2024年9月13日 星期五

重構既有系統,邁向整潔架構 (3):Task List Kata簡介

September 13 20:30~22:07

 

前言

上一集<重構既有系統,邁向整潔架構 (2):逆轉重構流程>Teddy提到只要「大膽假設」不管你是開發什麼系統,就是要套用Clean Architecture就對了。如此一來,便可將重構從「由下而上」的設計方法轉變成「由上而下」的設計過程。

接下來這幾集,Teddy將以Task List Kata為例,說明如何將既有系統的架構重構成Clean Architecture。

***

Task List Kata介紹

Task List Kata是一個公開的重構練習,程式碼可參考:https://kata-log.rocks/task-list-kata。如圖1所示,它有8種不同的語言版本,Teddy使用Java版本。

 

▲圖1:Task List Kata支援的語言

 

如圖2所示,Teddy將Task List Kata複製到自己的repository,並將package name改成tw.teddysoft.tasks。

 

▲圖2:Task List Kata專案目錄

 

Task List Kata原本只有三支程:

  • Task:參考圖3,這是一支只有不到30行的程式,很簡單,好像沒什麼需要重構。
  • TaskList:參考圖4、圖5,這是一支約150行的程式,看起來很亂,感覺是重構的重點。
  • ApplicationTest︰整合測試,當重構進行時可以執行這個測試案例確定沒有感變舊有的程式行為。

 

▲圖3:Task.java程式碼

 

▲圖4:TaskList.java程式碼, 1/2

 

▲圖5:TaskList.java程式碼, 2/2

***

鄉民們怎麼重構

首先,了解需求。Task List Taka的介紹網頁提到 (用ChatGPT翻譯成中文):

 

***

任務清單

這是一個對基元(primitives)過度依賴的程式範例。

基元是任何具有技術性質且與您的業務領域無關的概念。這包括整數、字符、字串和集合(列表、集合、映射等),還有執行緒、讀取器、寫入器、解析器、異常處理等任何純粹專注於技術問題的事物。相比之下,這個專案中的業務概念,如「任務」、「專案」等,應被視為您領域模型的一部分。領域模型是您所運營的業務的語言,將其應用於代碼庫有助於避免使用不同的語言,從而幫助避免誤解。根據我們的經驗,誤解是造成漏洞的最大原因。

練習

嘗試實現以下功能,同時逐步重構以去除基元。在完全重構代碼以移除基元之前,儘量不要實現任何新行為,也就是說,只有在您即將更改的代碼已被重構後,才進行變更。不要重構無關的代碼。

一組判斷基元是否已移除的標準是,只允許基元出現在構造函數的參數列表、本地變量和私有字段中。基元不應該被傳遞給方法或從方法中返回。唯一的例外是基礎設施代碼——與終端、網絡、資料庫等進行通信的代碼。基礎設施需要將數據序列化為基元,但應視為特殊情況處理。您甚至可以將基礎設施視為一個獨立的領域,具有技術性質,其中基元是該領域的核心概念。

您應該嘗試將測試包圍在您正在重構的行為周圍。一開始,這些測試大多是高級系統測試,但隨著進展,您應該會撰寫更多的單元測試。

***

上述說明已經提示了重構方向:「優先考慮去除primitives」,也就是去除重構中提到Primitive Obsession(基本型別依戀)壞味道。但是一般人看到這個練習,直覺的想法是:「把大的拆成小的」。很多人會先把TaskList的private methods像是showaddsetDonehelperror等「座艙升等」,各自變成一個class,並套用Command設計模式,讓execute可以執行不同的命令。

接著,為了產生這些不同的命令,又套了Simple Factory。然後呢…….嗯,就沒有然後了。此時TaskList程式長度剩下原本的1/3,抽離出來的Command也符合單一責任原則,程式碼也很短,感覺好像沒什麼明顯地方需要重構了。

***

 

換你想

在正式談Teddy如何重構Task List Kata之前,請鄉民們也想想看,如果是你,你會如何重構?

***

工商服務

想了解本系列文章完整內容,請參考重構既有系統:邁向整潔架構實作班。課程介紹與報名網址在此:https://teddysoft.tw/courses/refactor-to-ca/

***

友藏內心獨白:搞錯順序只會徒然浪費時間。

2024年9月10日 星期二

重構既有系統,邁向整潔架構 (2):逆轉重構流程

September 10 07:38~08:08;11:30~11:49

      

▲圖1:Ada逆練九陰真經

 

前言

上一集<重構既有系統,邁向整潔架構 (1):為什麼透過重構改善軟體架構很困難>Teddy提到重構是一種「由下而上」的設計,而設計本身應該採用「由上而下」的過程,這也是為什麼透過重構改善軟體架構會如此困難的原因。

為了簡化重構軟體架構的難度,要想辦法將重構流程改成「由上而下」。

 

***

怎麼做?

要「逆轉重構流程」,其實很簡單,就是先確定架構目標就可以了。例如,假設鄉民是Uncle Bob的粉絲,不管手邊有什麼軟體,就是要想辦法無條件套用Clean Architecture就對了。如此一來,你就有了軟體架構重構的目標:Clean Architecture。

現在Teddy把架構重構的問題轉換成如何套用Clean Architecture,Teddy用Pattern Language的方式來解釋這個套用的過程,請參考圖1。有五個模式支撐Clean Architecture:

 

▲圖1:Clean Architecture底下有五個模式

 

上述五個模式的套用順序,先從Four Layers開始,將系統分成以下四層(四個不同的packages):

  • entity
  • usecase
  • adapter
  • io
      

有了大方向之後,接下來就是把你的既有系統想辦法塞入Clean Architecture這四層之中,如圖2。

 

      

▲圖2:Clean Architecture的四個階層

***

下一集Teddy將會以Task List Kata為例,說明如何將既有系統的架構重構成Clean Architecture。

***

 

工商服務

想了解本系列文章完整內容,請參考重構既有系統:邁向整潔架構實作班。課程介紹與報名網址在此:https://teddysoft.tw/courses/refactor-to-ca/

***

友藏內心獨白:道理很簡單,要做到卻不簡單。

2024年9月5日 星期四

重構既有系統,邁向整潔架構 (1):為什麼透過重構改善軟體架構很困難

September 5 21:02~22:06

▲Ada:我不會逆轉重構但我可以逆轉自己!

 

前言

今年四月Teddy開了一門新課程:【重構既有系統:邁向整潔架構實作班】。以往的開課流程Teddy總是先寫部落格文章,再設計課程,但這門課Teddy卻是直接設計課程而沒寫部落格文章。這系列文章算是「補寫」原本應該出現的文章,第一集先談為什麼軟體架構層級的重構很困難?

***

重構是一種設計

大部分鄉民應該都知道重構是在不改變程式碼外在行為的前提之下,藉由改變它的結構達到增進設計品質的一種方法。既然重構可以「改善設計」,因此可以將重構視為一種設計方法

Teddy將設計方法區分為兩種:

  • 由上而下:先決定設計目標,然後由上而下展開子目標,最後展開到一個可以施工的工作單元。例如,傳統的物件導向分析與設計就是一種由上而下的方法。先確定專案願景,然後展開需求、設計領域模型、軟體架構。
  • 由下而上:不確定最終目標是什麼,先從手邊可接觸到的「東西」著手設計,再慢慢將這些「東西」兜成更大的「東西」,透過這種方法完成設計工作。重構本質上就屬於這種設計方法。

***

 

設計應該是由上而下的過程

根據建築師Christopher Alexander的看法,設計是一種由上而下個過程。這就好比敏捷社群常說「以終為始」是一樣的道理,你希望達到什麼目標,就以這個目標當作設計的出發點。這樣講鄉民們可能還是覺得有點抽象,Teddy舉領域驅動設計中的戰術設計模式(tactical design patterns)為例,請參考圖1,Model-Driven Design模式是這個模式語言的「起點」,也是這整個設計最「頂」的模式,也等於這個模式語言的「目標」。

翻成白話文就是:領域驅動設計的戰術設計就是Model-Driven Design。如果看到這模式鄉民們就懂了,就開悟了,底下的其他模式也就無需再看。

 

▲圖1:領域驅動設計的戰術設計模式語言

 

***

再舉一個日常生活的日子,假設你晚上要請朋友吃飯,你要先決定「去那裡吃飯」?例如吃路邊攤、快炒、日式料理、韓式料理或是西餐等。如果是吃快炒,接下來才是決定要點什麼菜、什麼湯和飲料。這就是由上而下的設計思維。

***

由上而下那又怎樣?

重構作為一種由下而上的設計方法,用來達成區域改善是很有效的方法。例如,用Rename重構幫變數、method、class、package取個可以代表它們意圖的好名子。有沒有改善設計,當然有。改善後的設計對軟體架構的影響是什麼?不知道(不明顯)!

同理,用Extract Method把Long Method變短同時又用有意義的method name來代表程式碼的意圖。有沒有改善設計,當然有。改善後的設計對軟體架構的影響是什麼?不知道(不明顯)!

這就是透過重構要達到改善軟體架構很困難的原因。要採用由下而上的方式改善軟體架構並非不可行,但這類似演化的作法,需要一段很長、很長、很長的時間,以至於在一般專案中變得不切實際。因為鄉民們沒有那麼長的時間可以透過演化的方式「長出」一個好架構出來。

***

怎麼辦?

答案就在前文中。其實很簡單,就是要想辦法將重構改成由上而下的設計方法。只要做到這點,透過重構改善軟體架構就變得不再那麼遙不可及。

今天先聊到這個,下一集Teddy再來談如何「逆轉重構」,把它改成由上而下的設計方法。

***

工商服務

重構既有系統:邁向整潔架構實作班課程介紹與報名網址:https://teddysoft.tw/courses/refactor-to-ca/,有興趣的鄉民歡迎參考。

***

友藏內心獨白:好久沒出來亮相了。

2024年3月10日 星期日

2024 新課程:【重構既有系統:邁向整潔架構實作班】

March 10 21:59~23:14

▲實作Clean Architecture需要了解的「設計模式」

 

前言

2023年七月Teddy開始每天錄製一則YouTube影片之後就荒廢了部落格寫作,這兩天有鄉民提醒Teddy:「blog也重要,文字也是好東西」。鄉民說得有道理啊,還是要分配點時間給blog才對。

2024年第一篇blog,就先打個廣告,介紹泰迪軟體的最新課程:【重構既有系統:邁向整潔架構實作班】。

***

課程介紹

Teddy在幾年前開過軟體重構的課,當初的想法是完整介紹Refactoring這本書,從Bad Smells出發,然後舉很多小例子說明不同的重構方法如何移除這些壞味道。這種重構方式固然有用,但Teddy總是覺得有點「小打小鬧」的感覺,對於整個系統的架構改善有限。就好像「你花了時間把家裡整理乾淨,但對於整個市容其實沒什麼影響,還是一樣中華民國美學:斑駁的外牆、陽台外推,以及到處都是鐵皮屋加蓋的違建。」

軟體架構層面的「大規模重構」,一直是很困難的一件事。去年Teddy與ezKanban團隊著手開發ezDoc:一個Living Documentation(活文件)系統,功能性需求開發完成之後,這幾個月花了很多時間在重構系統。一開始團隊也是採用傳統「由下而上」的重構方式,重構完成之後,可能是受到這幾年深入研究整潔架構(Clean Architecture)與領域驅動設計(Domain-Driven Design)的影響,Teddy突然有一個想法:「設計應是由上而下的過程,如果反過來先確定就是要把軟體系統重構成Clean Architecture,接著再依據Clean Architecture的架構指導原則並套用DDD戰術設計模式來重構系統,會有怎樣的結果?」

Teddy與ezKanban團隊把ezDoc的兩個主要功能:Living Readme(活自我說明檔)與Living Glossary(活字彙表)依據這個想法重構,期間Teddy另外找了Task List Kata這個很經典的重構範例來驗證這個做法,發現的確比傳統由下而上的重構方式要好很多。

Teddy整理了一套「整潔架構驅動重構方法(Clean Architecture-Driven Refactoring)」,就誕生了這個課程(還是要想辦法賺錢XD)。在這個課程中,Teddy以Task List Kata作為範例,逐步說明Teddy所發明的「整潔架構驅動重構方法」。這門課不使用紙本講義,Teddy會先引導學員思考一個核心的設計問題:「為什麼軟體架構重構很難?」,接著Teddy用實作的方式,藉由重構Task List Kata,把逐步將「整潔架構驅動重構方法」介紹給學員。在這個過程中,主要由Teddy在課堂上引導設計思考與重構程式碼給學員看,學員則採用mob programming的方式,以組為單位撰寫Teddy所安排的練習範例。

課程涉及Clean Architecture與領域驅動設計的以下內容:

  • 分層原則:將軟體架構分為四層。
  • 建立Entities Layer:透過移除基本型別依戀壞味道尋找物件,建立通用語言。並使用DDD戰術設計模式,遵守Aggregate Root設計原則。
  • 建立Use Cases Layer物件、區分Command Use Case與Query Use Case(在使用案例層讀寫分離)、依賴反轉、依賴注入、套用Repository、Controller、Presenter、DTO(Data Transfer Object)、Mapper等設計模式。。
  • 在Interface Adapters Layer形成Controllers、依賴注入、Presenter設計模式的使用方法討論。
  • Main Component,使用Spring Boot作為依賴注入框架。
  • 在Interface Adapters Layer增加Web Controllers (使用Spring Boot)。
  • 使用Persistent Object 以滿足跨層原則,重新設計Repository介面與Mapper。
  • 使用關連式資料庫,透過 JPA (Java Persistence API) 使用Spring Boot連結H2資料庫。

課程練習範例Task List Kata有C#, Go, Java, Kotlin, Python, Ruby, Scala, Typescript這幾種語言,上課練習Teddy用Java語言示範,團隊mobbing也是使用Java。使用不同語言的學員在了解「整潔架構驅動重構方法」並看過一次Java重構範例後,在課後可選擇自己熟悉的語言重新練習一次,將你所常用的語言範例版本重構成整潔架構。

▲Teddy套用Clean Architecture重構後的Task List Kata,包含測試案例由3個Java程式變成106個。

***

報名網址

本課程今年上半年兩個班次已經確定開課:

  • 2024年4月22、23日(一、二)
  • 2024年5月25、26日(六、日)


課程介紹與報名網址:https://teddysoft.tw/courses/refactor-to-ca/,有興趣的鄉民歡迎參考。

***

友藏內心獨白:一個課程四種享受—Refactoring、Clean Architecture、DDD與Teddy。