同一性是兩者的分界

entity 的同一性由身份定義：欄位可以全部改變、只要身份參照不變就是同一個；兩個欄位完全相同的 entity 仍然是兩個。value object 的同一性由內容定義：內容相等就是同一個，替換一個內容相同的實例對系統沒有任何影響。這條分界推導出兩者相反的設計形狀——entity 有生命週期、狀態沿業務流程演進、變更要有路徑；value object 不可變、要「改」就是造一個新值換上去。

相等性定義本身可以承載業務規則。一個 POS 專案的購物車品項用內容比對判定同一項、而折扣參與比對——手動改過價的品項被視為獨立的訂單行，合併購物車時只有規格、折扣、口味全部相同的品項才累加數量。「什麼算同一個」在這裡是業務決策寫進相等性定義的例子，而這正是 value object 的表達力所在：同一性規則集中在一個定義裡、所有比對點共用。

判準：操作需不需要 identity-based 定位

判準是對這個物件的操作、需不需要精確指到某一個實體——概念重不重要、有沒有 id 欄位可以填，都不參與判斷。上述 POS 專案把這條判準踩出完整的階段軌跡：點餐階段的品項操作是「加一份」「換口味」，內容相等就是同一個、value object 的內容比對足夠；品項被掛單系統接受後獲得後端身份，操作變成「取消那一筆」「改那一筆的量」——同商品同口味的三筆明細內容完全相同，取消其中一筆時內容比對無法指定是哪一筆，此刻模型必須升級成持有身份參照的形態（同一個品項、四個 model）。

操作形態對應三種模型選擇：

• 操作以內容為對象（累加、合併、比對、替換）——value object，內容相等性就是全部所需。
• 操作要指到特定實體（取消那一筆、改那一筆的回寫，或讀取側的關聯、去重、生命週期追蹤）——entity，或至少是持有身份參照的包裝。
• 操作只剩查閱與退貨這類對既成事實的處置——live 內容參照凍結成 snapshot、身份保留作退貨與取消的鍵，見下一節。

判準的常見誤用是拿概念重要性代替操作分析：「訂單很重要所以是 entity」推不出正確結論，訂單行在輸入階段就是純內容比對；反方向「它有 id 欄位所以是 entity」同樣失效，id 可以只是序列化需要的欄位、與同一性判定無關。判準的作用對象是操作清單，操作清單來自業務流程——這也是為什麼身份語意的判定要等操作盤點之後才能做。

判準隨生命週期重問

同一個業務概念的身份語意會在生命週期的轉折點改變，每個轉折點都要重問一次判準。上述品項模型的完整軌跡是四個模型接力：純需求描述（無 id、內容比對）、後端實體（後端 id）、訂單行（把多筆後端明細收攏成一行、持有它們的身份集合）、歷史明細（id 加全欄位 snapshot）。每一次交棒都對應身份狀態的真實變化，四個模型是身份語意在三個轉折點上改變的結果、而不是重複建模。

概念成為歷史事實之後，live 內容參照要凍結、身份繼續承重。歷史訂單明細保存下單當時的商品與價格 snapshot——商品後續改名、下架、調價，訂單仍顯示當時購買的內容；身份參照在這個階段轉而承擔退貨與取消操作的鍵。凍結時機的判準是業務對「過去」的要求：歷史記錄反映事件發生當下的世界，持有 live 參照的歷史會跟著現在的資料漂移。反過來，還在進行中的購物車品項持有 live 參照是正確的——會員身分改變、價格即時跟著變，這是進行中狀態的業務需求。同一個「參照要不要凍結」的問題，答案由生命週期階段決定。

單一模型通吃全生命週期的代價在每個階段各自浮現：改量操作靠內容比對會誤中同內容的其他筆、歷史訂單持 live 參照會跟著商品改名漂移。拆分自己也有帳要付——層間 mapping、交棒處的同步成本、模型數量的認知負擔；轉折點少、各階段操作集合幾乎重合的概念，單一模型加階段旗標反而便宜。四個模型是這個 domain 有三個真實轉折點的結果、而不是通用配方——模型的邊界跟著身份語意的轉折點切，每段模型只服務自己階段的操作。

value object 的價值：語意封閉

value object 的第二個價值獨立於同一性判定（也獨立於容器型別的類別判定——資料袋裡照樣可以放語意封閉的欄位型別）：把一個領域概念的合法運算限縮成封閉集合。判讀訊號是一個領域概念的合法運算集合、明顯小於它底層型別的運算集合——差集裡的每個運算都是一個等著被誤用的 API。金額是標準案例：底層數字型別開放任意四則運算，但「金額乘金額」在領域裡沒有意義、「金額加折扣率」是單位錯誤；同一個 POS 專案把金額換成高精度數字型別之後、這些誤用仍然全部放行，第二次遷移把金額包成 Money 型別、開放的運算限於領域有意義的集合（金額加減、乘數量、乘倍率、退款的負號）——運算列表本身就是領域規則的宣告（金額型別的三段遷移）。

這個案例同時標出兩個常被混淆的獨立問題：精度（浮點誤差）換底層型別就解決、語意（任意運算全放行）要包 domain type 才解決。解掉第一個問題的當下、第二個問題還完整存在，而它要等夠多誤用路徑累積後才顯形。判準操作化：盤點概念的合法運算清單、跟底層型別的運算集合做差集；差集非空、且裸型別跨模組邊界流動（或差集裡的誤用已經實際發生過一次），包一層的價值就成立。這層封閉防的是無心誤用；刻意拆封仍然可行，攔截點是拆封處的 code review，型別層防護的完整邊界見 不變式的強制層次。

枚舉也是 value object 建模

分類值是 value object 的一種、同樣適用建模判準，而枚舉最常見的設計錯誤是粒度：分類系統的粒度是消費者的屬性、不是分類系統自己的屬性。同一個 POS 專案的支付方式有兩類消費者、粒度需求相反：序列化要無損對齊後端的完整列舉（對帳時兩筆記錄一筆支付寶一筆微信、壓成同一類就回不去了）、UI 行為分流只有少數真正的分歧（要不要找零、限不限會員）。單一枚舉選哪個粒度都犧牲一方，解法是分層——保真層無損對齊後端、行為層歸併成行為真正分歧的大類、層間用 exhaustive switch 衍生：「忘記決定新渠道歸哪類」這條違反路徑在編譯期就走不通（16 種支付渠道、4 種行為分類）。

分層的判斷方式是列消費者：消費者一種、單一枚舉足夠；消費者多種且粒度需求不同、每個消費者一層，層的粒度是「這個消費者眼中真正有分歧的數量」。粒度選錯的訊號是例外註解與重複開始增生——粗粒度層長出「有些成員其實……」的例外說明、細粒度層的行為謂詞大半是複製貼上。另一個相鄰但不同的病要區分開：多個正交的分類軸被壓進同一個枚舉（狀態、格式、來源混裝）——那是拆軸問題、分層救不了，訊號同樣是例外增生、但修法是先把軸分開。

判讀訊號

• 改量、取消、退貨這類操作用內容比對定位對象——同內容的其他實體會被誤中，操作清單已經要求 identity-based 回寫、模型該升級。
• 歷史記錄的顯示內容跟著現行資料變動（商品改名、訂單明細跟著變），是參照凍結時機漏掉的訊號：成為事實的資料要 snapshot。
• 一個領域概念以裸的通用型別跨模組流通（金額是 double、識別碼是 string）、而它的合法運算遠少於底層型別——語意封閉的價值已成立，包 domain type。
• 枚舉的行為謂詞大量重複、或某一類長出「有些成員例外」的註解：粒度或軸的選擇跟消費者需求不合，先列消費者清單再決定分層或拆軸。

函數式生態（Haskell、Elixir、F#）的對應形態不同但判準相同：entity 的同一性用 opaque type handle + 函數操作替代 mutable state + method，value object 用 newtype / smart constructor 確保合法值只能從受控管道建出。載體從 class 換成 module visibility 和 type wrapper，「操作需不需要 identity-based 定位」這條判準不變。

下一步

• 身份與規則就位之後，規則的落點：不變式的強制層次
• 變更路徑收斂與稽核凍結：狀態轉換與稽核軌跡
• 型別類別的入口判準：資料袋與領域模型
• Dart 的實作層整合（三種載體的選型判準、遷移安全網、取值出口設計）：值物件的 Dart 實作路徑；個別 case 細節：金額型別的三段遷移、16 種支付渠道、4 種行為分類

「這個領域值該不該升級成值物件」的判定屬於理論層，判準是同一性語意與語意封閉、與語言無關，見 entity 與 value object 的判準 與 value object 卡。本章接手判定之後的問題：在 Dart 裡，同一個「值物件」有三種實作載體，成本結構與適用情境各異——選哪條由這個值的欄位數、要不要 runtime 身份、以及專案對產生器的容忍度決定。

判斷：什麼領域值值得升級

值得升級的訊號是一個領域概念以裸的通用型別跨模組流通、而它的合法運算明顯少於底層型別。金額用 double 或 Decimal、識別碼用 String、數量用 int——這些型別在模組之間傳遞時，型別系統對「金額乘金額」「識別碼相加」這類無意義運算全部放行，因為它們在底層型別的世界裡都合法。合法運算集合小於底層集合、且裸型別已經跨越模組邊界，包一層的價值就成立。

這裡有兩個常被壓成一個的獨立問題。精度是底層表示的問題——浮點數累加金額會把誤差堆到分位，換一個高精度數字型別就解決。語意是運算邊界的問題——換完精度型別後，「任何人都能對這個值做任意運算」原封不動。解掉第一個問題的當下第二個問題完整存在，而它要等夠多「拿金額亂算」的路徑累積後才顯形。把兩者混為一談的後果是換完 Decimal 就宣告收工、語意缺口留在原地。

反過來，不是每個領域值都值得升級。合法運算集合幾乎等於底層型別的集合時（一個真的就是任意整數的計數器），封閉沒有差集可關、專用型別只是多一層轉換。裸型別從不跨越模組邊界、只在單一函式內部短暫存在時，誤用的窗口太小、升級的維護成本收不回。判準操作化成一句話：盤點這個概念的合法運算清單、跟底層型別的運算集合做差集，差集非空且裸型別在模組間流動，才動手。

實作路徑的成本結構

三種載體對應兩條軸：這個值是單一底層值還是多欄位複合值、以及需不需要 runtime 的型別身份。單一底層值（金額包一個數字、識別碼包一個字串）走 extension type 最省；多欄位複合值（地址、日期範圍、含幣別的金額）需要一個真正的物件裝多個欄位，走 class 路徑，class 又分手寫與 freezed 產生兩種。runtime 身份的需求橫切這兩軸——需要 is Money 在執行期為真、或需要反射看得到型別時，只有 class 路徑滿足。

Dart 3 的 record 是多欄位載體、還自帶結構相等，看起來像多欄位複合值的第四條路徑，但它不入選值物件的載體、原因在型別語意。record 是結構型別而非名目型別：兩個欄位形狀相同的概念（(String, String) 的地址與姓名）在型別系統裡是同一個 record 型別、拿不到 DateRange 這種領域名字，也就換不到「傳錯型別編譯期就擋」的保護。record 沒有建構子、無處掛不變式檢查，也無法限縮 API——任何拿到它的程式碼都能讀所有欄位、組任意新值。值物件要的名目身份、建構期不變式、封閉介面，record 結構上三個都不給。它適合的是函式的匿名多回傳與臨時分組，不是需要領域約束的值物件。

手寫 immutable class 與 copyWith

手寫 immutable class 是最直接的載體：所有欄位 final、建構子帶不變式檢查、要「改」就造一個新實例。多欄位複合值在這條路徑上用 copyWith 做逐欄位覆寫——傳要改的欄位、其餘保留原值、回傳新實例，這對欄位組合全部合法的值語意清晰。成本在 boilerplate：== 與 hashCode 要手寫且要涵蓋所有參與相等性的欄位、copyWith 每加一個欄位就要同步一行，漏一個欄位的相等性比對是安靜的 bug。

這條路徑的邊界在 copyWith 的適用範圍。對欄位組合全部合法的資料袋與純值物件，copyWith 是正確工具；對有領域方法、欄位之間有不變式約束的型別，全欄位 public 的 copyWith 是繞過領域方法的逃生口——領域方法從「唯一變更路徑」降級成「建議路徑」。判準是型別有沒有「不允許任意組合的欄位」，有的話那些欄位就不該讓 copyWith public 可寫。完整機制見 copyWith 是逃生口，不是設計。

freezed 產生器

freezed 是把手寫 class 的 boilerplate 壓到接近零的產生器：標記 @freezed 後自動產生 copyWith、== / hashCode、toString()、以及 sealed union。多欄位複合值需要完整相等性與序列化、又不想手工維護每個欄位的同步時，freezed 是這條路徑的主流選擇；它的 sealed union 在枚舉分層上另有價值——exhaustive switch 讓「忘記決定新成員歸哪類」在編譯期就走不通。

成本結構有兩面。一面是工具依賴：freezed 走 build_runner 產生程式碼，專案要接受產生器的建置步驟與產物管理。另一面是預設路徑的一視同仁——freezed 不區分資料袋和有領域方法的 entity，每個被標記的 class 都得到全欄位 public copyWith，包含狀態欄位與稽核欄位。規範說「請走領域方法」、工具預設給全欄位 copyWith，兩者衝突時預設會贏。在 entity 上使用 freezed 需要額外收窄：把 copyWith 改 private、或從參數列移除受約束的欄位。結構細節見 Freezed 三層結構解剖。

extension type 零成本包裝

extension type 是 Dart 3.3 起提供的載體，把單一底層值包成一個新名字、限縮可用的 API、而 runtime 不存在額外物件——編譯後就是底層型別本身，所有約束活在編譯期。單一底層值的語意封閉、又在高頻路徑上流通（金額在每筆訂單明細累加、識別碼在每次查詢傳遞）時，這條路徑用零 runtime 開銷換到型別安全。它跟 class 路徑是互斥的實作選擇：class 走 runtime、有型別身份也有 overhead；extension type 走編譯期、零 overhead 但 runtime 透明，is 與 as 看到的是底層型別。

用 extension type 時要在設計期定 subtype 決策——它是底層型別的 subtype（寬鬆：可隱式 upcast 回底層、封裝邊界弱）還是獨立型別（嚴格：只能顯式拆封、每個銜接點都要拆）。金額的做法是 implements Object 而只有 Object：既有的格式化入口 formatAmount(Object) 能直接吃它、不必改簽名；同時它不是數字型別的 subtype，於是不能被傳進任何收數字型別的參數，裸運算沒有回來的路。這條路徑不搭 copyWith——extension type 沒有 runtime 物件可以逐欄位覆寫，逐欄位覆寫語意只在 class 路徑上成立。

三條路徑的選型錨點收在下表，每一列的成本結構與適用情境在上面各自的段落展開：

從原始型別遷移過去

值物件多半在裸型別的誤用累積之後才補上去，於是實作值物件常常等於一次型別遷移。一個金額欄位的遷移軌跡把兩個獨立問題各解一段：最初是浮點數、累加誤差堆到分位；第一段換成高精度數字型別、精度問題解決；金額仍然是裸的通用數字、任何拿到它的程式碼都能做任意運算，於是第二段把它包進 extension type，開放的運算限於領域有意義的集合。運算列表本身就是領域規則的宣告：金額加減可以、乘數量可以、乘倍率可以（刻意跟數量分開簽名），金額乘金額不存在、因為介面沒開放。想對它做底層型別的任意運算，得先顯式呼叫拆封方法，那一行拆封程式碼就是 code review 的攔截點。這條軌跡的完整素材見 金額型別的三段遷移。

遷移動的是全專案的欄位，安全網是 characterization test——遷移前對著舊實作寫、鎖住當前輸出（包含當前的邊界行為，例如找零算出負數時歸零），遷移後全綠就證明型別替換沒有帶入行為變化。它跟一般測試的差別在斷言的性質：它驗證「行為不變」、不驗證「行為正確」。正確性是另一批測試的事——把兩個問題混在同一批測試裡，遷移期間的紅燈就分不清是「換壞了」還是「本來就錯」。做法展開見 測「不變」、不測「正確」：characterization test。

取值出口：封裝的對象是運算、不是取值

值物件封住的是「任意運算」、不是「取原始值」本身。基礎設施邊界對原始值有正當需求——快取需要 key、資料庫需要 column 值、序列化需要原始表示、格式化銜接層需要底層型別。正確做法是給原始值一個語意明確的官方出口，而不是禁止取值逼下游硬撬。金額的拆封方法 toDecimal() 就是這種出口，註解直接寫明供哪種場合使用；序列化給 toDbValue() 這類名字說明用途的方法；UI 顯示給 displayValue。有官方出口的世界裡「誰在拆封」是可 grep 的（搜出口方法名就是完整清單），封裝邊界是明示的。

把取值本身當違規會來回撞牆。一個 App 的識別碼型別的封裝政策擺盪過兩輪：先追「零個外部取值」把公開介面只留 toString()，撞上基礎設施層的正當需求後又把取值 getter 加回來、改名叫「相容性介面」。兩個極端各自的撞牆點是同一個病的兩面——完全封裝逼正當消費把 toString() 當取值 API 用（語意寄生，toString() 哪天為除錯改格式、快取 key 就靜默換一批），零封裝則讓 ISBN 校驗、ID 格式這些不變式失去強制點。穩態在中間：原始值有官方出口、出口有語意、邊界寫進決策記錄。擺盪的完整軌跡見 Value Object 的封裝擺盪，出口設計的理論層展開見 建構路徑設計。

邊界

本章處理值物件在 Dart 的實作載體選擇，是實作層知識。三個上游判定不在本章：一個型別該不該模型化成領域模型（入口判準見 資料袋與領域模型）、模型化之後該用 entity 還是 value object（同一性判準見 entity 與 value object 的判準）、以及約束該落在文件層、型別層還是執行層（見 不變式的強制層次）。值物件把封閉做在型別層，防的是無心誤用——刻意用反射或 dynamic 拆封仍然繞得過，威脅模型是「防止意外」而不是「防止刻意」。

型別層防護的另一半責任落在 entity 而非 value object：entity 的同一性由身份定義、有生命週期、變更要走領域方法，那條路徑的收窄（copyWith 逃生口、稽核軌跡凍結）跟本章的值物件封閉是相鄰但不同的問題，路由到 狀態轉換與稽核軌跡。

下一步

三條實作路徑各有 case 可深讀：copyWith 的適用邊界在 copyWith 是逃生口，不是設計、freezed 的結構在 Freezed 三層結構解剖、extension type 的 subtype 決策與遷移在 金額型別的三段遷移。取值出口的封裝邊界在 Value Object 的封裝擺盪、遷移安全網在 characterization test。理論地基從 DDD 指南的模型設計主梯 進，值物件在其中的位置是 entity 與 value object 的判準 的語意封閉段。

概念位置

Value object 有兩個獨立的價值。第一個跟 entity 的判準有關——操作以內容為對象（累加、合併、比對、替換）就用 value object。第二個是語意封閉：把一個領域概念的合法運算限縮成封閉集合——差集裡的每個運算都是等著被誤用的 API。語意封閉的價值獨立於同一性判定、也獨立於容器型別的類別——資料袋裡照樣可以放語意封閉的 value object。

可觀察訊號

一個領域概念以裸的通用型別跨模組流通（金額是 double、識別碼是 string）、而它的合法運算遠少於底層型別——語意封閉的價值已成立。封裝後要給原始值一個語意明確的官方出口（見 建構路徑設計）。

設計責任

Value object 需要決定相等性定義（哪些欄位參與比對、參與本身就是業務規則）、不可變策略、以及封裝出口。枚舉是 value object 的一種——粒度判準看消費者需求、不看分類系統本身。判準的完整展開見 entity 與 value object 的判準。

工廠的表達力與消費者需求

工廠（建構子、命名工廠、builder）是合法物件的唯一入口。它的職責有兩個：保證出生即合法（不變式檢查）、同時覆蓋消費者的正當需求（給得出消費者想要的合法組合）。兩個職責有張力——保證越嚴、接受的參數越窄；解法是讓工廠的表達力跟上需求、而不是放棄保證。

一個書籍管理 App 的 createForTest 工廠只接受 id / title / author / isbn 四個參數。測試想表達「預設 tags 再追加三個自訂 tag」——這是合法的需求、工廠的表達力沒覆蓋到。需求進不了工廠，就會從別的出口出去——在這個專案，出口是全欄位 copyWith（copyWith 是逃生口，不是設計）。

工廠參數列的設計判準：收的是「有語意的需求」（預設 tags 加自訂、指定初始狀態、帶入驗證過的關聯物件），不是「所有欄位的任意值」。後者退化成另一個全欄位建構器，保證也跟著消失——分寸在「覆蓋高頻的合法組合、不開放任意拼裝」——「高頻」的門檻見下一節：同一組合出現第二次就收進工廠。

逃生口吸收建構路徑的缺陷

逃生口吸收是建構路徑缺陷長期不被修好的核心機制：表達力缺口碰上萬能拼裝工具、上游缺陷被下游繞道消化、工廠永遠不會被迫改進。機制分三步。第一步、工廠表達不了需求：上述 createForTest 不接受 bookTags。第二步、逃生口接住需求：copyWith 總是能拼、它成為唯一出路。第三步、拼裝現場的最短路徑埋下語意錯誤：在用 copyWith 拼的當下、順手建個臨時物件撈預設值（Book.createForTest(id: 'tmp').bookTags）是阻力最小的寫法——而 'tmp' 不滿足 BookId 的長度約束。同型寫法幾天前才在另一個檔案修過一次。

關鍵在第二步的因果方向：逃生口不只讓錯誤寫法變可能、它讓正確的修法變不必要。沒有逃生口時、工廠表達力不足會立刻擋住需求、逼出「幫工廠加參數」的修法；有逃生口時、每個被擋的需求都繞出去了、工廠的缺陷永遠不會痛。同族語意錯誤第二次出現就是結構在選擇行為的證據：兩個作者（或同作者在不同時刻）在同一個表達力缺口前面各自獨立走出同一條最短路徑（copyWith 是逃生口，不是設計）。

修法對準上游：讓工廠能表達需求（createForTest 接受 bookTags），拼裝的動機就消失了。修每一個拼裝點——把 'tmp' 改成合法長度、把臨時物件改成取自己的欄位——只消掉當次症狀，下一個測試還是會在同一個表達力缺口前面選擇拼裝。門檻是兩次：第一次拼裝可以當個案修掉——只出現一次的特殊組合用拼裝是合理的、工廠也有參數列膨脹的反向代價。第二次出現就該停止修拼裝點、轉頭找共同面對的表達力缺口。工廠產物的 copyWith 呼叫在覆寫哪些欄位、就是一份「工廠該收而沒收的參數」的實證清單——繞道流量本身是免費的需求調查（#223 逃生口吸收建構路徑的缺陷）。

原始值的官方出口

建構路徑的另一面是出口：value object 封裝了原始值之後、基礎設施層（快取 key、資料庫 column、序列化）要怎麼拿到它需要的表示。穩態是封裝任意操作、而非封裝取值本身——基礎設施邊界的需求是正當的、該給語意明確的出口。這個穩態從擺盪中浮出。

同一個書籍管理 App 的 value object 封裝在三個版本間擺盪。v0.7.6 全移除（裸字串），不變式失去強制點、任何字串冒充任何 ID。隨後 v0.8.10 推向另一極——完全封裝、目標零個 .value 外部存取——基礎設施層的 176 個編譯錯誤暴露這些消費是正當需求，把它們全逼到 toString() 上是語意寄生、格式一改快取 key 靜默換一批。最終 v0.8.13 加回 .value getter、被重新命名成「相容性介面」，實質是理想在依賴現實前退讓（VO 的封裝擺盪）。

穩態的操作化：出口的名字說明用途：toJsonString()（序列化）、toDbValue()（持久化）、displayValue（UI）。「誰在拆封」就變成可 grep 的——一個 POS 專案的 Money 型別用 toDecimal() 作為官方拆封口、搜尋 toDecimal( 就是拆封清單。沒有官方出口的世界裡、下游用 toString() 硬接或把 .value getter 加回來、拆封處完全不可追蹤。

擺盪的根治不在選對某一極、在於把邊界寫成決策記錄：哪些出口存在、各自給誰用、為什麼不多不少。出口增長到大多數消費者都有專屬方法時、封裝的值已不成立——此時直接暴露一個語意明確的拆封方法，比維護多個用途近似的出口便宜。沒有這份記錄、每一任重構者都會從自己撞到的那一面出發、再推向另一個極端。判讀徵兆：重構記錄出現「相容性介面」——檢查它是不是理想撤退的重新命名；決策記錄只記贏面——反方向的代價沒被記、下次擺回去的推力還在；封裝重構在基礎設施層爆量——訊號是「這些消費是正當的」、該給出口不是硬改。

判讀訊號

• 測試 Arrange 段出現「工廠 + copyWith 拼裝」——盤點拼裝在補什麼欄位、高頻欄位收進工廠參數列。工廠參數列長期不變、而它的產物被 copyWith 環繞——表達力已落後需求，原則見 #223。
• 建一個立刻丟棄的物件、只為了拿它的一個欄位？這是語意錯誤的標記，先找它真正想表達的需求。
• 同族語意錯誤第二次出現——停止修個案、找兩個案共同面對的建構路徑缺口。
• toString() 被當成取值 API 用在快取 key / DB 值——語意寄生、格式一改靜默事故。出口要有語意明確的名字，語意封閉判準見 entity 與 value object 的判準。
• VO 封裝重構的編譯錯誤在基礎設施層爆量——基礎設施是正當消費者、該給出口。

下一步

• 物件組好之後、整個系統怎麼被組起來：組裝層的可達性
• 出生合法的機制：不變式的強制層次
• 變更路徑收斂：狀態轉換與稽核軌跡
• 型別類別的入口判準：資料袋與領域模型
• value object 的語意封閉判準：entity 與 value object 的判準
• Dart 的語言細節（copyWith 三態缺口、工廠表達力擴充、extension type 的拆封口）：copyWith 是逃生口，不是設計、VO 的封裝擺盪
• 原則層：#223 逃生口吸收建構路徑的缺陷

觸發場景：Flutter 書籍管理 App 的查詢輸入層——BookQueryInput value object 加 BookInputValidator 驗證器。實作過程撞了兩個問題：測試想建一個全空的輸入來測 validator、被 VO 的建構驗證擋住建不出來；ISBN 填 978ABC 被拒、錯誤訊息卻說「長度必須是 10 或 13 位」 疑問來源：驗證邏輯到底該放建構子還是 validator？以及那個張冠李戴的錯誤訊息是怎麼來的？ 整理目的：記下驗證的兩層分工判準、以及「先標準化再檢查」的證據銷毀陷阱 本文邊界：素材是該專案 v0.11.3 的實作記錄（41 個單元測試的 TDD 過程、含三個實作期問題的解法）

兩層分工：存在條件 vs 輸入品質

這一層的設計把驗證拆在兩個位置，各守一種性質的規則：

BookQueryInput 的建構期不變式：至少一個查詢參數非空。這是存在條件——四個欄位全空的「查詢輸入」在語意上不是一個查詢，這種物件不該存在於系統的任何角落。違反它的處置是拒絕建構：拿到 BookQueryInput 實例的任何下游、都可以信任它至少有一個參數。

BookInputValidator 的格式驗證：ISBN 格式（10 或 13 位、允許連字符與空格）、標題與作者長度（1-255 字元）、附帶標準化（去連字符、收斂空白）。這是輸入品質——使用者打錯很正常，處置不是拒絕存在、是回一個 ValidationResult：錯誤碼清單、本地化訊息、以及標準化後的值。

判準收成一句：違反時「這個物件不該存在」的規則進建構子、違反時「要好好告訴使用者」的規則進 validator。前者失敗是程式錯誤（哪段程式碼試圖建一個不合法的物件？）、後者失敗是日常輸入流程的一個分支。混放的代價在兩個方向都會現形：格式驗證塞進建構子，UI 層要 try-catch 例外再翻譯成欄位錯誤、錯誤碼與訊息的結構化全部丟失；存在條件放進 validator，全空的物件能在系統裡流通、每個消費者都要自己防。

有趣的是這個分工是被測試撞出來的：測試想建全空實例去測 validator 的「至少一個參數」規則、被建構不變式擋住。這個衝突不是誰錯——它暴露了「至少一個參數」同時被兩層宣告。釐清後規則歸建構期（存在條件）、validator 的對應測試改測空白字串等輸入品質情境。測試建不出 fixture、經常就是層次劃分待釐清的訊號。

順序陷阱：先標準化、等於先銷毀證據

第二個問題是條精緻的小 bug。ISBN 驗證的原始順序是「先標準化、再檢查」：標準化移除所有非數字字元、然後檢查位數。輸入 978ABC 走完這條管線：字母被移除、剩 978、三位數、被拒——錯誤訊息是「長度必須是 10 或 13 位」。

拒絕是對的、理由是錯的。使用者的實際問題是「ISBN 含字母」，訊息卻叫他去檢查長度——他數了數自己輸入的六個字元、更困惑了。機制上這是證據銷毀：標準化是有損操作，把「含字母」這個診斷所需的證據刪掉了，後面的檢查只能對殘骸做判斷、自然歸錯類。修法是把順序反過來：

1// 先對原始輸入檢查格式——證據還在
2if (!RegExp(r'^[\d\-\s]+$').hasMatch(isbn)) {
3  return 'invalid_isbn_format';   // 正確的病名
4}
5// 通過格式檢查的才標準化、再驗位數
6final normalized = normalizeIsbn(isbn);

一般化的規則：診斷在證據被破壞之前做。管線裡任何有損轉換（去除字元、截斷、大小寫合併、去重）之後的檢查，都只能回報轉換後世界的錯誤——想給使用者他輸入層面的錯誤訊息、檢查就得在轉換前。這條規則在錯誤處理鏈上反覆適用：wrap 例外時保留原始例外、log 時保留原始輸入，同一個「別讓下游只看到殘骸」。

另一個小設計也值得帶走：ValidationResult 直接攜帶 normalizedIsbn / normalizedTitle——驗證跟標準化一次完成、下游拿標準化值繼續用，不會出現「驗證器驗一個版本、查詢用另一個版本」的分裂。

判讀徵兆

• 測試建不出想要的 fixture、被建構驗證擋住——存在條件與輸入品質可能混在同一層、先釐清歸屬
• 錯誤訊息與使用者的實際輸入對不上（說長度、其實是字元；說格式、其實是空值）——檢查點在有損轉換之後、往管線上游搬
• UI 層用 try-catch 接建構例外再翻譯成表單錯誤——格式驗證放錯層了、它該回結構化結果不該拋
• 驗證器回布林——錯誤碼、訊息、標準化值都沒有位置放，遲早長出第二套平行邏輯

相關閱讀

• 不變式住哪一層的全景：#222 約束要讓違反路徑走不通——本文的建構期不變式是「執行層強制」的標準形態
• 同族的分類學：Exception 型別綁 ErrorCategory 的建構不變式——那篇是錯誤的分類不變式、本文是輸入的存在不變式
• 概念地基：建構路徑設計——建構子與 validator 的分工是建構路徑設計的入口決策；存在條件與輸入品質的分層邊界見 不變式的強制層次

觸發場景：Flutter 書籍管理 App 的資料庫整合測試全面失敗，錯誤訊息：Invalid argument 整合測試作者 with type BookAuthor. Only num, String and Uint8List are supported——所有涉及 SQLite 的 CRUD 操作都掛 疑問來源：同一個 map 裡 id 跟 title 都存得進去，為什麼 author 炸了？ 整理目的：記下 value object 跨持久化邊界的轉換責任、以及 toString/fromString 這條隱性契約的風險 本文邊界：素材是該專案 v0.10.6 的修復規劃記錄；sqflite 的型別限制是 SQLite 本身的特性、不是套件的設計選擇

錯誤現場：三個欄位、兩種寫法

炸點在 repository 把 entity 轉成資料庫 map 的方法：

1Map<String, dynamic> _bookToMap(Book book) {
2  return {
3    'id': book.id.toString(),        // BookId → String，存得進去
4    'title': book.title.toString(),  // BookTitle → String，存得進去
5    'author': book.author,           // BookAuthor 物件直接塞 → 炸
6    ...
7  };
8}

sqflite 底下的 SQLite 只接受 num、String、Uint8List 三種型別。BookAuthor 是帶內部狀態的 value object（作者清單、譯者），直接放進 map 就是把一個 Dart 物件遞給不認識它的儲存引擎。錯誤訊息其實說得很清楚——難的不是修，是這個錯誤揭露的責任問題：誰負責把領域型別拆成儲存型別？

責任歸位：轉換發生在 repository 邊界

修法本身一行：'author': book.author.toString()；讀回的方向 _mapToBook 已經在用 BookAuthor.fromString(map['author']) 重建。架構上這是 adapter 的職責放在 repository 層——domain 的 value object 不知道 SQLite 存在、SQLite 不知道 value object 存在，兩個世界的轉換集中在 I/O 邊界的 _bookToMap / _mapToBook 一對方法裡。

這個歸位讓錯誤的形態變得可預測：每個新的 VO 欄位都要在這對方法裡出現一次，漏掉序列化端會炸 Invalid argument（吵、好抓）、漏掉反序列化端會在讀取時炸型別轉換（也吵）。真正安靜的坑在第三種情況——兩端都寫了、但不對稱。

隱性契約：toString 與 fromString 的對稱性沒人強制

用 toString() / fromString() 當序列化通道，工作的前提是 fromString(x.toString()) == x——而這條契約沒有任何機制在守。修復記錄自己就把風險寫進了已知限制：複雜物件轉字串可能遺失部分內部狀態、未來需要更精細的序列化機制。

具體的斷裂點兩種。其一，toString() 的本業是除錯表示，哪天有人為了 log 可讀性把格式改成 BookAuthor(name: ...)，資料庫裡從此存進去的是新格式、舊資料用新 fromString 讀不回來——兩個消費者（除錯與持久化）寄生在同一個方法上、變更理由不同步。其二，格式本身有損：這個專案的 BookAuthor 把多作者序列化成「作者1, 作者2」、譯者成「作者 (譯者 譯)」——作者名字裡出現逗號或括號時，roundtrip 就不再對稱。

正解方向修復記錄也留了：語意明確的序列化介面（toDbValue() / 專用 Serializable、或 JSON 結構化），讓「持久化格式」成為一個有自己名字、自己測試、自己變更理由的東西。過渡期至少要補上對稱性測試——對每個 VO 斷言 fromString(v.toString()) == v、含邊界值（空作者、多作者、含譯者），把隱性契約變成會紅的測試。

判讀徵兆

• Invalid argument ... with type X. Only num, String and Uint8List are supported——X 就是漏轉換的 VO、去 _toMap 系方法找它
• repository 的 map 轉換裡混用「物件直接放」跟「.toString()」兩種寫法——前者是還沒炸的候選
• toString() 同時服務除錯輸出跟持久化 / 快取 key——語意寄生，兩個消費者遲早有一個要改格式
• VO 有 fromString 但測試裡沒有任何 roundtrip 斷言——對稱契約處於未驗證狀態

相關閱讀

• 出口語意的原則版：VO 封裝擺盪——那篇論證「原始值要有語意明確的官方出口」，本文是 toString() 被當出口用的實際風險清單
• 持久化邊界的另一面：功能完成卻從未持久化——那篇是欄位沒進出邊界、本文是進了邊界但轉換錯誤，roundtrip 測試同時守住兩者
• 概念地基：DDD 領域驅動設計指南 的 entity 持久化邊界章節

觸發場景：Flutter 書籍管理 App 的 work-log 裡，Value Object 的封裝政策在短時間內擺盪了兩輪：先把整套 VO 系統移除改直接字串、之後 VO 重新出現並推「完全封裝」（目標 0 個 .value 外部存取）、撞牆後又把 .value getter 加回來 疑問來源：每一次轉向的理由單獨看都成立，為什麼會來回擺？穩態在哪裡？ 整理目的：記下擺盪的機制、兩個極端各自的撞牆點、以及 VO 封裝邊界的可操作判準 本文邊界：素材是該專案 v0.7.6 / v0.8.10 / v0.8.13 三份重構記錄——同一條決策線的三個時間點、不是三個獨立事件

三個時間點、兩次反轉

第一步（v0.7.6）：全移除。 當時的狀態是 API 不一致——Book entity 已簡化成純字串、Library entity 還在用 book.id.value 的 VO API，測試因此跑不起來。決策是把 VO 系統整個移除：book.id.value 改 book.id（裸字串）、比較邏輯改字串相等、記錄下來的效益是 API 直觀、記憶體降低。

第二步（v0.8.10）：完全封裝。 VO 重新回到 codebase 後（BookId、BookTitle、BookISBN），新的重構往反方向推到底：目標「0 個 .value 外部存取」、公開介面只留 toString()（快取 key、資料庫）跟 displayValue（UI 顯示）。理由同樣成立：.value 暴露內部實作、同一個值有三種取法、測試綁死內部結構。代價是 176 個編譯錯誤起步，而且執行到 43% 就記錄了「工作量預估偏低」——cache 跟 database 這些基礎設施層對 .value 的依賴遠比預期廣。

第三步（v0.8.13）：加回 getter。 當天深夜的緊急分析裡，BookId 跟 BookTitle「新增 .value getter」被列為合理且必要的修改、定位是「提供必要的相容性介面」——而且被描述成「符合 v0.8.10 封裝性重構原則」。完全封裝的理想在依賴現實前退讓，退讓被重新命名成相容性。

兩個極端各自的撞牆點

擺盪的機制是：兩極的論述都對、但都只對一半。

純字串的撞牆點：移除 VO 的記錄只記了贏面（-50% 程式碼、效能），但執行過程被迫新建「內嵌佔位符類別」（LibraryId、LibraryStatistics）——這個動作本身就是反證：有些概念即使在「去 VO」的世界裡仍然需要一個型別的形狀。裸字串的世界裡，ISBN 校驗、ID 格式這些不變式失去了強制點，任何字串都能冒充任何 ID。

完全封裝的撞牆點：基礎設施層是真實存在的消費者——快取需要 key、資料庫需要 column 值、序列化需要原始表示。「0 個 .value」把這些正當需求全部逼到 toString() 上，而 toString() 承擔不動：它的語意是「這個物件的字串表示」，跟「這個 VO 封裝的原始值」只是碰巧相等——哪天 toString() 為了除錯改成 BookId(abc-123) 格式，所有快取 key 就靜默換了一批。執行面還有一個 Dart 特有的陷阱被記錄下來：批次替換 .value 時得逐處區分 VO 的 .value 跟 Map 的 .values。

穩態：原始值要有官方出口、出口要有語意

把兩次撞牆合起來看，VO 封裝的可操作邊界浮出來：封裝的對象是「任意操作」、不是「取值」本身。 基礎設施邊界對原始值的需求是正當的，正確做法是給它一個語意明確的官方出口，而不是禁止取值逼下游硬撬：

• 給序列化 / 持久化：toJsonString()、toDbValue() 這類名字說明用途的方法
• 給 UI：displayValue
• 給確實需要原始型別的銜接層：一個顯式的拆封方法——同類專案裡 Money extension type 的 toDecimal() 是乾淨的例子，註解直接寫明「供確實需要 Decimal 的場合（如格式化銜接層）」

有官方出口的世界裡，「誰在拆封」是可 grep 的（搜尋 toDecimal( 就是完整清單）；沒有出口的世界裡，下游會用 toString() 硬接、或者像這個 case 一樣把 getter 加回來——而且加回來的 .value 沒有任何語意標記，跟重構前一模一樣。

判讀徵兆

• 重構記錄裡出現「相容性介面」——檢查它是不是理想撤退的重新命名；撤退本身可能是對的、但要記下「原目標為什麼不可行」，否則下一輪重構會再朝原目標衝一次
• 決策記錄只記贏面——反向的代價（本 case：移除 VO 失去不變式強制點）沒被記錄時，下次擺回去的推力就還在
• 封裝重構的錯誤數在基礎設施層爆量——訊號是「這些消費是正當的」、該給出口而不是硬改
• toString() 被當成取值 API 用在快取 key / DB 值上——語意寄生，格式一改就是靜默事故

擺盪的根治不在選對某一極，在於把邊界寫成決策記錄：哪些出口存在、各自給誰用、為什麼不多不少。沒有這份記錄，每一任重構者都會從自己撞到的那一面出發、再推向另一個極端。

相關閱讀

• 概念地基：entity 與 value object 的判準——語意封閉與拆封口的判準層；建構路徑設計——原始值出口穩態的教學層展開
• 出口設計的正面案例：金額型別的三段遷移——Money 的 toDecimal() 就是「官方拆封口」的形態
• 原則層：#223 逃生口吸收建構路徑的缺陷——「沒有官方出口、下游硬撬」跟「工廠表達力不足、測試用 copyWith 拼」是同一個機制的兩個面

觸發場景：整理 POS 專案的購物車模型時，發現「一個商品品項」這個概念在 codebase 裡有四個 model：CartItem、ShoppingCartDetail、OrderedCartItem、OrderItem。乍看是重複建模 疑問來源：四個 model 是過度設計、還是各有不可合併的職責？如果是後者，拆分的判準是什麼？ 整理目的：把「同一個業務概念何時該拆 model、value object 何時升級成 entity」的判斷邊界記下來 本文邊界：素材是一個 Flutter POS App 的現行實作；「四個」是這個 domain 的結果、不是通用配方——判準才是可遷移的部分

四個 model 各在哪個生命週期

一個商品從「使用者點選」到「進了歷史訂單」，這個專案用四個 model 接力表達：

每一次交棒都對應一個身份狀態的變化，這是四個 model 不可合併的原因。

階段一：CartItem 是純需求描述、沒有 id

CartItem 表達「使用者想要什麼」：商品、規格、數量、折扣、口味。它沒有任何 id 欄位——兩個 CartItem 是不是同一項，靠 isSameItem() 做內容比對：

1bool isSameItem(CartItem other) {
2  if (specification.id != other.specification.id) return false;
3  if (discount != other.discount) return false;   // 手動改價過的品項視為獨立行
4  // 口味集合比對（不考慮順序）
5  ...
6}

這是 value object 的語意：內容相等就是同一個。合併購物車（mergeItems）靠這個判定把相同品項的數量累加。值得留意折扣也參與同一性判定——改過價的品項是不同的訂單行，這是業務規則直接寫進相等性定義的例子。

階段二：掛單接受的那一刻、identity 誕生

需求被掛單系統接受、寫進 ShoppingCart.details 之後，每筆明細獲得了後端身份 detail.id。model 的原始註解把這個轉折講得很清楚：

一旦這個需求被掛單系統接受、寫進 details，它就獲得了後端身份（detail.id），從這刻起在前端應以 OrderedCartItem 表達——客人加點同一項三次，邏輯上是一筆訂單行（一個 OrderedCartItem），實體上是三筆 detail。

OrderedCartItem 的結構只有兩個欄位：cartItem（內容）加 sourceDetailIds（身份）。它存在的理由是操作需要精確回寫：改數量、單品取消、單品改價，都必須映射回後端要修改的那幾筆 detail。內容比對在這裡不夠用——同商品同口味的三筆 detail 內容完全相同，取消其中一筆時內容比對無法指定是哪一筆。

購物車 model 上有一段對應的契約註解：UI 顯示的列表經過合併與過濾，「UI 列表的 index 跟 details 的 index 不是同一個東西」，任何 UI 到後端 detail 的操作都要透過 sourceDetailIds 做 id-based 比對。用 index 對應兩個列表是這個結構下最容易踩的錯誤路徑，契約直接把它寫死在文件裡。

階段三：結完帳、參照凍結成 snapshot

OrderItem 是結帳完成後的歷史事實。它跟 CartItem 的關鍵差異是參照的凍結：

• CartItem 持有 live 的 Product 參照，價格即時查當前規格（會員身分變了、價格跟著變）
• OrderItem 保存 OrderDetailProduct / OrderDetailProductSpecification 的 snapshot，註解明說「即使後續商品改名/下架，訂單仍顯示當時購買的內容」；unitPrice 也在 fromResponse 時依當時的會員身分擇一凍結

detailId 在這個階段承擔新職責：退貨與取消 API 的鍵、以及同訂單中區分「同商品不同口味」的唯一鍵。

判準：操作需不需要 identity-based 回寫

把三次交棒放在一起看，「value object 什麼時候該升級成 entity」的答案就浮出來了。判準是對這個物件的操作，需不需要精確指到某一個實體——概念重不重要、有沒有 id 欄位可以填，都不參與這個判斷。

• 需求描述階段：操作是「加一份」「換口味」，內容相等就是同一個，value object 的內容比對足夠
• 進入外部系統之後：操作是「取消那一筆」「改那一筆的量」，必須 identity-based 回寫，此時需要 entity（或至少像 OrderedCartItem 這樣持有身份參照的包裝）
• 成為歷史事實之後：操作只剩查閱與退貨，連 live 參照都要凍結成 snapshot——歷史不隨現在的資料變動

反過來看單一 model 通吃的代價：改量操作靠內容比對會誤中同內容的其他筆；歷史訂單持 live 參照會跟著商品改名漂移。四個 model 不是重複，是身份語意在三個轉折點上真的變了。

相關閱讀

• 概念地基：entity 與 value object 的判準（本文是該判準的實機案例）、狀態轉換與稽核軌跡（凍結作為稽核端點的教學層展開）
• 同專案的 snapshot 對照組：entity 稽核軌跡的洞（copyWith 是逃生口，不是設計）——那篇談變更路徑的完整性，本文談身份與參照的凍結時機，兩者合起來是「歷史事實怎麼被保護」的兩個面

觸發場景：Flutter 書籍管理 App 的 import domain 介面盤點，發現兩個同名類別並存：value_objects/import_result.dart 跟 models/import_result.dart——都叫 ImportResult、欄位完全不同、引用時全憑 import 路徑分辨 疑問來源：兩個類別各自看都命名合理，撞名是怎麼發生的？重命名之後的 Phase 4 稽核又抓到什麼？ 整理目的：記下傘狀名的碰撞機制、依職責命名的修法、以及「重命名是原子操作組」的教訓 本文邊界：素材是該專案 v0.12.1 的介面盤點與 Phase 4 重構稽核報告

碰撞：兩個「匯入結果」、各自誕生都合理

攤開兩個類別的內容，撞名的成因就清楚了：

寫驗證邏輯的人需要一個型別裝驗證結果——「這是匯入流程的結果」、叫 ImportResult，合理；寫匯入執行的人需要一個型別裝執行結果——同樣的推理、同樣的名字。「Result」是傘狀詞：它只說「某個東西的結果」、不說是哪個環節的，同一個 domain 裡任何階段的產出都有資格用它，於是第二個使用者出現時必然碰撞。碰撞的代價由所有讀者付：每次看到 ImportResult 都要先看 import 路徑才知道在讀哪一個，而 IDE 自動匯入選錯路徑的錯誤、型別又剛好對不上時的錯誤訊息（「ImportResult 不是 ImportResult」）尤其折磨。

修法：名字要能回答「什麼操作的結果」

決策保留 models 版當主要的 ImportResult（它代表整個 use case 的產出、消費者最多），value object 版重命名為 ImportValidationResult——名字補上了它缺的那一節：驗證的結果。判準可以一般化：result / info / data / manager 這類傘狀名，掛上去之前先問「它是哪個操作的 result」——答案就是名字該有的樣子。兩個同名類別並存時的診斷同理：先問哪一個的名字說謊了（通常是語意較窄的那個佔了寬名字）、改窄的那個。

這跟分層 enum 的粒度判準是同一族：名字的顆粒度要配得上它指涉範圍的顆粒度，佔著寬名字的窄概念是碰撞的定時炸彈。

稽核抓到的：做一半的重命名、以及宣稱的漂移

Phase 4 重構稽核在「已完成」的重命名上抓到殘局：類別名確實改成了 ImportValidationResult——但檔名還是 import_result.dart。而且工作日誌宣稱檔案已重命名為 import_validation_result.dart、與現實不符。

三層漂移疊在一起：類別名（改了）、檔名（沒改）、文件宣稱（說改了）。做一半的重命名比不做更迷惑——現在檔名對讀者說「這裡是 ImportResult」、打開來是另一個名字，Dart 的「檔名對應主類別名」慣例反過來變成誤導。教訓收成兩條：

• 重命名是一組原子操作：類別名、檔名、所有 import 路徑、測試引用、文件宣稱——清單上每一項都做完才算完成，IDE 的 rename 重構通常只保證前三項、檔名跟文件是人的責任
• 宣稱完成與實際完成是兩個 fact：工作日誌寫「已重命名」的當下可能是計畫、可能是部分完成——下游讀者無從分辨。這正是 Phase 4 稽核這類「驗收與執行分離」流程存在的理由，同構於 read-path 分析的獨立重驗紀律

判讀徵兆

• 同一個 domain 裡 grep 到兩個同名類別——先判哪個名字說謊（語意窄的佔寬名）、改窄者
• 類別名含 Result / Info / Data / Manager 而前綴不含操作名——傘狀名候選，下一個同 domain 的產出型別就會撞上來
• 檔名與主類別名不一致——半完成重命名的化石，補完或回退、別放著
• 工作記錄宣稱的檔案狀態與 codebase 不符——把「宣稱」降級為線索、以 grep 結果為準

相關閱讀

• 命名顆粒度的同族：16 種支付渠道、4 種行為分類——名字與指涉範圍的顆粒度要相配
• 原則層：#157 語意錨用單一字串——同語意雙字串與同字串雙語意是一體兩面的引用災難；#84 Naming 是 iterated artifact——第一版命名幾乎不對、cross-call-site 檢驗才收斂
• 宣稱與實際的分離：遷移計畫有寫入、有消費、缺讀出——獨立重驗的紀律

觸發場景：Flutter 書籍管理 App 引入 value object 之後，估計 100+ 個測試失敗——expect(book.title, '測試書籍') 這類斷言全數過期，因為 book.title 現在是 BookTitle、它的 toString() 回傳 BookTitle:<測試書籍> 疑問來源：改斷言就好？改成什麼——.value、.displayValue、還是 toString()？追下去發現這個問題本身就是病灶 整理目的：記下 VO 取值 accessor 不一致的兩層傷害、以及「集中取值知識」的止血法 本文邊界：素材是該專案 v0.11.15 的測試修復計畫與執行記錄；accessor 混亂的成因（.value 的存廢擺盪）在另一篇有完整弧線

第一層傷害：toString 洩漏讓裸字串斷言靜默過期

欄位從 String 升級成 value object 之後，型別變了、但舊斷言不會編譯失敗——expect(actual, expected) 的參數是 dynamic，BookTitle 跟 '測試書籍' 的比較合法地在 runtime 回 false。於是 VO 引入前累積的所有裸字串斷言，以「測試失敗」而不是「編譯錯誤」的形式集體過期，一次 100+ 個。

自定義 toString()（BookTitle:<測試書籍> 這種帶型別前綴的除錯格式）讓失敗訊息更迷惑：期望值跟實際值看起來「幾乎一樣」，差一層包裝。這是 toString 語意寄生的又一個現場——它的本業是除錯表示，被斷言、被序列化、被快取 key 借用時，每個借用者都對它的格式有隱性依賴。

第二層傷害：四種取法、連修復者都寫錯

修復計畫的第一版推薦「改用 .value 屬性」：

1expect(book.title.value, '測試書籍');   // 修復計畫推薦的寫法

執行階段發現這個推薦本身是錯的——實際的 accessor 分佈是：BookTitle 跟 BookAuthor 用 .displayValue、BookId 只能 toString()、isbn 根本是裸 String? 不用取值。「取原始值」在四個相鄰型別上是四種寫法，連專門來修這個問題的人都先踩了一次。

這是介面不一致的可測量代價：API 的使用知識無法從一個型別遷移到下一個，每次使用都是一次查閱或一次賭注。而這個混亂不是誰設計出來的——它是 .value 存廢擺盪的沉積物：封裝重構移除了 .value、留下 toString() 跟 displayValue 兩個出口、緊急修復又給部分型別加回 .value，幾輪下來每個 VO 停在擺盪的不同相位上。

止血：helper 函數庫集中取值知識

逐個改 100+ 斷言的過程中，策略從「批次改寫」轉向「建輔助函數庫」：

1// test/helpers/value_object_test_helpers.dart
2expectBookTitleEquals(book.title, '測試書籍');
3expectBookAuthorEquals(book.author, '作者名');

helper 把「每個 VO 怎麼取原始值」的知識集中在一個檔案：斷言的呼叫端不再需要知道 BookTitle 用 displayValue 而 BookId 用 toString()——它們長得一樣、內部各自處理差異。附帶的複利是未來 accessor 再變動（例如統一成單一名字）時，要改的位置從 100+ 個斷言縮成一個 helper 檔。

要分清楚的是：helper 是止血、不是根治。它讓不一致的 API 可以被一致地使用，但不一致本身還在——lib/ 端的每個新消費者仍會面對四種取法。根治是家族統一 accessor（同名、同語意、同回傳型別），而那要先解決擺盪篇談的「出口語意」問題：先決定每個出口給誰用，名字才定得下來。

判讀徵兆

• 型別升級（String → VO）後測試大量失敗、失敗訊息的期望與實際「差一層包裝」——裸值斷言過期，別逐個修、先決定統一的比較方式
• 同一家族的型別、取原始值的寫法超過一種——API 知識不可遷移，每個消費者都在重新學
• 修復計畫裡寫的 accessor 跟實作對不上——不一致已經騙到文件層了，這是「先盤點再動手」的訊號
• 測試 helper 裡出現 per-type 的比較函數——止血有效，但把「統一 accessor」記進債務清單，別讓 helper 的存在掩蓋根治的必要

相關閱讀

• 成因的完整弧線：VO 封裝擺盪——四種取法是全移除、完全封裝、加回 getter 幾輪擺盪的沉積物
• toString 語意寄生的另一個現場：SQLite 只吃三種型別——除錯表示被借去當持久化通道
• 概念地基：DDD 領域驅動設計指南——value object 的介面也是模組的公開契約、家族一致性是契約的一部分

觸發場景：整理 POS 專案的金額處理時，發現 git 歷史上金額型別換過兩次——double 到 Decimal、再從 Decimal 到自訂的 Money。第二次遷移乍看多餘：精度問題 Decimal 已經解掉了 疑問來源：Decimal 哪裡不夠？第二次遷移買到的是什麼？ 整理目的：記下「精度」跟「語意」是金額型別的兩個獨立問題、以及 Dart extension type 在第二個問題上的實作手法 本文邊界：以該專案的實際遷移軌跡為素材；extension type 是 Dart 3 的機制、其他語言的對應手法（newtype / value class）思路相同但細節不同

第一段：double 的精度問題

最初所有金額欄位是 double，JSON 轉換器把後端的 number 或 string 統一存成 double。浮點數處理金額的問題是經典的：0.1 + 0.2 != 0.3，累加訂單明細時誤差會累積到分位。

第一次遷移（單一 PR 內兩個 commit）把所有 model 的金額欄位換成 Decimal，API 接入層用 jsonToDecimal 統一處理後端可能回 number 或 string 的格式差異。精度問題到此解決。

第二段：Decimal 解決了精度、沒解決語意

換完 Decimal 之後，金額仍然是一個裸的通用數字型別。任何拿到 Decimal 的程式碼都能對它做任意運算：兩個金額相乘（語意上不存在的運算）、金額跟折扣率直接相加、拿金額當數量用。型別系統對這些錯誤全部放行，因為它們在 Decimal 的世界都是合法運算。

這是 primitive obsession 的標準形態：值的表示對了、值的語意邊界還是沒有。三個月後的第二次遷移把金額包進 Money：

1extension type const Money._(Decimal _raw) implements Object {
2  Money operator +(Money other) => Money._(_raw + other._raw);
3  Money operator -(Money other) => Money._(_raw - other._raw);
4  Money operator -() => Money._(-_raw);              // 退款 / 折讓
5  Money operator *(int quantity) => ...;             // 金額 × 數量
6  Money multiplyByRate(Decimal rate) => ...;         // 會員價率、服務費率
7  Money clamp(Money min, Money max) => ...;
8  ...
9}

運算列表本身就是領域規則的宣告：金額加金額可以、金額乘整數（數量）可以、金額乘倍率（Decimal，刻意跟數量分開簽名）可以——金額乘金額不存在，因為介面沒開放。想對 Money 做 Decimal 的任意運算，得先顯式呼叫 toDecimal() 拆封，那一行拆封程式碼就是 code review 的攔截點。

implements Object 的取捨：要當 Object、不當 Decimal

extension type 宣告 implements Object 而只有這個，是一個精確的 subtype 決策：

• 是 Object 的 subtype：既有的格式化入口 formatAmount(Object) 可以直接吃 Money、不用改簽名
• 不是 Decimal 的 subtype：如果宣告 implements Decimal，Money 就能被傳進任何收 Decimal 的參數、所有裸運算又回來了——包裝等於白做

extension type 在 runtime 是零開銷的（編譯後就是底層的 Decimal），所有約束都活在編譯期。這也意味著它的保護是編譯期的：反射或 dynamic 繞得過去，威脅模型是「防止無心的誤用」而不是「防止刻意拆封」。

遷移安全網：characterization test 先鎖行為

第二次遷移動的是全專案的金額欄位，怎麼確認換型別沒改行為？這個專案在遷移前先寫了一批 characterization test，測試檔開頭直接註明用途：

Characterization test —— 鎖住 CheckoutContext 結帳金額計算的現有行為。在 Money value object 遷移（階段 5）前建立。涵蓋應付金額 fold、現金找零（含負數歸零分支）、金額足夠判斷。

characterization test 跟一般測試的差別在斷言的性質：它不驗證「行為正確」、驗證「行為不變」。遷移前對著舊實作寫、鎖住當前輸出（包含當前的邊界行為，例如找零算出負數時歸零），遷移後全綠就證明型別替換沒有帶入行為變化。正確性是另一個問題、留給另一批測試——把兩個問題混在同一批測試裡，遷移期間的紅燈就分不清是「換壞了」還是「本來就錯」。

收束：兩個問題、兩次遷移

金額型別有兩個獨立的問題，這個專案的軌跡恰好一段解一個：

第一段遷移完成時「金額用 Decimal」看起來已經是終點，語意問題要等到夠多「拿金額亂算」的路徑存在後才顯形。判讀訊號是：一個領域概念的合法運算集合、明顯小於它底層型別的運算集合時，包一層 domain type 的價值就成立——差集裡的每個運算都是一個等著被誤用的 API。

相關閱讀

• 概念地基：entity 與 value object 的判準 的語意封閉段（本文是 primitive obsession 到 domain type 的實機案例）
• 同族判準：copyWith 是逃生口，不是設計——那篇的判準「有沒有不允許任意組合的欄位」在型別層的對應是「有沒有不允許的運算」，兩篇都是把約束從慣例層上移到型別層