觸發場景：實作營運端報表 API、寫了一個 freezed model 疑問來源：abstract class PeriodReportRow with _$PeriodReportRow implements ReportAmountsView 這一行包含太多陌生語法 整理目的：把「為什麼長這樣」與「是否有更好懂做法」的脈絡記錄下來、避免下次又從零開始查 本文邊界：這是一篇 work-log，目標是回溯一次具體實作中的理解成本；它不取代 freezed 官方文件，也不把某個專案的模型分層當成通用規則。

事件起點

今天在某個營運端 Flutter 專案新增週期彙總報表 API，這份報表和既有的單次作業報表共用呈現邏輯、各自有獨立的 DTO。為了讓兩個 DTO 共用 sections builder、抽了一個 ReportAmountsView 介面、讓兩邊的 *Row 都 implements 它。

寫完後盯著這行程式碼看了一下：

1@freezed
2abstract class PeriodReportRow
3    with _$PeriodReportRow
4    implements ReportAmountsView {
5  const factory PeriodReportRow({
6    required String date,
7    // ... 18 個欄位
8  }) = _PeriodReportRow;
9}

短短四行裡塞了好幾個需要分層理解的語法：abstract 為什麼能配 factory、with _$PeriodReportRow 在做什麼、_$ 這個前綴代表什麼、= _PeriodReportRow 如何接到生成類，以及為什麼要分成「我寫的 abstract」+「生成的 mixin」+「生成的具體類」三層。

這篇筆記把那次停下來查證的路徑整理成可重讀的判斷脈絡。

第一層：with 是什麼

with 是 Dart 的 mixin 語法、把另一個型別的成員「混入」當前 class。當前 class 會接上 mixin 提供的成員；如果 mixin 宣告了抽象成員，最後的具體類仍要提供實作。

三個關鍵字的差異

1abstract class PeriodReportRow
2    with _$PeriodReportRow         // ← mixin：接上生成 API surface
3    implements ReportAmountsView  // ← interface：拿到契約

extends 佔據唯一父類別位置，適合真正的 is-a 關係；implements 只拿契約，適合用型別描述能力；with 在中間，適合把一組生成或共用的成員接到 class 上。

在 freezed 中的角色

_$PeriodReportRow 是 build_runner 跑完後在 period_report_dto.freezed.dart 裡產出的 mixin，角色是把 Freezed 生成的 API surface 接到你宣告的 PeriodReportRow 門面上。

• 欄位 getter 的契約或 forwarding surface（date、grossAmount、channelA 等）
• == 和 hashCode 相關生成邏輯
• copyWith
• toString
• JSON 相關的 generated function / method 接線（取決於是否搭配 json_serializable 與 fromJson factory）

所以 abstract class PeriodReportRow with _$PeriodReportRow 在做的事是：

「我這個 class 是抽象門面，Freezed 會把生成 API 放在 _$PeriodReportRow mixin 與 _PeriodReportRow 具體類裡；門面透過 with 接上生成 surface，factory 再回傳真正持有欄位的生成類。」

這裡最容易誤解的是「mixin 等於所有實作」。在 Freezed 的常見生成模式裡，mixin 會宣告或提供部分生成成員，真正持有 final 欄位並滿足 getter 的通常是 factory 指向的 _PeriodReportRow 具體類。with _$PeriodReportRow 的價值是讓門面型別擁有一致的生成 API 形狀，而不是把每個欄位的儲存都塞進 mixin。

為什麼 freezed 用 mixin 而不是 extends

• mixin 不佔「父類別」的獨生子位置：Dart 只允許單一 extends、freezed 如果用 extends 強佔了、你就不能讓 model 繼承自己的 base class。with 可以無限疊加、給你自由度
• mixin 支援多個疊加：class Foo with A, B, C 會把 A、B、C 的方法依序混入。Freezed 利用這個語法位置，把生成 API 接到使用者宣告的門面類
• implements ReportAmountsView 在這裡剛好成立：ReportAmountsView 要求的是一組 getter 契約，而 Freezed 會讓生成的 _PeriodReportRow 具體類依照 factory 參數產生對應欄位。門面類宣告 implements，具體類回傳時提供欄位實作，所以不需要再手寫 18 個 forwarding getter

簡化的等價心智模型

 1// 你寫的：
 2abstract class PeriodReportRow
 3    with _$PeriodReportRow
 4    implements ReportAmountsView { ... }
 5
 6// 大致等於（觀念上）：
 7abstract class PeriodReportRow implements ReportAmountsView {
 8  // 門面接上 generated API surface：
 9  PeriodReportRow copyWith(...);
10}
11
12class _PeriodReportRow implements PeriodReportRow {
13  // 具體生成類持有欄位並滿足 interface getters：
14  @override final String date;
15  @override final Decimal grossAmount;
16  @override final Decimal channelA;
17  // ... 等等所有 factory 參數對應的欄位
18}

這是心智模型：with 接上 generated surface，factory = _PeriodReportRow 接到真正的資料承載類。

第二層：_$ 命名約定

第一次看到 _$PeriodReportRow 容易以為這是某個 framework 的特殊符號。實際上是兩個獨立慣例疊加的結果。

_ 和 $ 各自的角色

組合起來：

• _$PeriodReportRow → 機器產的 + 只給內部用（你不該在外部檔案引用它）
• $PeriodReportRowCopyWith → 機器產的 + 公開介面（呼叫 instance.copyWith(...) 時要看得到型別）

兩個前綴分別代表不同意圖——freezed 透過 _ 的有無、區分「實作細節」跟「公開介面」。

_$Foo 為什麼你的檔案看得到

Dart 的 library-private（_ 前綴）並非「檔案私有」、是「library 私有」。預設一個 .dart 檔就是一個 library、但 part 指令會把多個檔案併成同一個 library。

freezed model 檔案開頭那兩行：

1part 'period_report_dto.freezed.dart';
2part 'period_report_dto.g.dart';

就是在說：「這三個檔屬於同一個 library」。

結果：generated 檔裡的 _$PeriodReportRow 雖然 _ 開頭、但因為 part 連通、你的主檔還是看得見、可以 with 它。其他 import 你檔案的人就看不到、正好符合「只給內部生成檔用」的意圖。

這也是為什麼忘記寫 part 'xxx.freezed.dart'; 會編譯失敗——不是因為「找不到檔案」、是因為「_$Foo 不在同一個 library 內、外部不能引用」。

一個快速辨認方式

下次看 freezed / codegen 產出的名字、可以這樣判斷：

• _$Foo → mixin / 實作類（內部用）
• $Foo → public 介面（給外部呼叫）
• _Foo → 純內部 class（如 _PeriodReportRow 是 freezed 為你的 factory 產的具體類）
• Foo → 你自己寫的 abstract class、是門面（facade）

所以這次寫的：

1abstract class PeriodReportRow with _$PeriodReportRow implements ReportAmountsView
2//             ↑ 門面            ↑ 內部 mixin           ↑ 你定義的介面

三層責任可以被辨認：你自己寫的門面類、機器產的實作、你自己定義的契約。它不是透明抽象，因為使用者仍要看懂 part、with _$Foo 與 factory redirect 這些接線。

第三層：為什麼要這樣拆——是設計不當嗎

with _$Foo 加 part 加 abstract class 加 factory 加 _$ / $ / _ / 無前綴 四種命名……理解到這裡會自然冒出一個問題：這個拆分本身、是不是 freezed 設計不當？

我的看法：這個拆分不是 freezed 設計不當、但它確實暴露了 Dart 語言層的能力缺口。換個角度、「需要這樣拆」是症狀、不是病因——病因在語言本身。

拆分到底解決了什麼問題

把那幾個元素還原成「想做的事 vs 不得不這樣寫」：

前 3 行是真實需求；最後一行是「為了實現前 3 行、Dart 缺工具、所以要組裝」。

對比其他語言處理同樣問題

1// Kotlin —— 語言內建
2data class PeriodReport(val date: String, val grossAmount: BigDecimal)
3// copy、equals、hashCode、toString 全部自動、0 行 codegen

1// Rust —— derive macro 內建在語言
2#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
3struct PeriodReport { date: String, grossAmount: Decimal }

1// TypeScript —— 結構型別 + 解構即拷貝
2type PeriodReport = { date: string; grossAmount: Decimal };
3const next = { ...prev, grossAmount: newAmount };  // copyWith 不用存在

1// Swift —— struct 是值類型
2struct PeriodReport: Codable, Equatable {
3    let date: String; let grossAmount: Decimal
4}

 1// Dart 2 —— 你只能這樣寫（沒 freezed 的話）
 2class PeriodReport {
 3  final String date;
 4  final Decimal grossAmount;
 5  const PeriodReport({required this.date, required this.grossAmount});
 6  PeriodReport copyWith({String? date, Decimal? grossAmount}) =>
 7      PeriodReport(date: date ?? this.date, grossAmount: grossAmount ?? this.grossAmount);
 8  @override bool operator ==(...) => ...;
 9  @override int get hashCode => ...;
10  @override String toString() => ...;
11  factory PeriodReport.fromJson(Map<String, dynamic> json) => ...;
12  Map<String, dynamic> toJson() => ...;
13}
14// 18 個欄位 × 6 個樣板 ≈ 150 行手寫、每加一個欄位要改 5 個地方

Freezed 是在這個現實下做的工程權衡：用一個外部工具、把這上百行壓回十幾行宣告。代價就是看到的「分三層」。

Freezed 自己有沒有設計可議的地方

Freezed 的設計可議之處集中在抽象洩漏，而不是功能是否成立：

• part directive 是漏出的實作細節：使用者必須知道 library / part 的概念才能寫對。Freezed 依賴 part，是因為生成檔需要和主檔落在同一個 library，讓 _ 開頭的 generated member 可以被主檔看到
• with _$Foo 暴露了 codegen 接線：理想上 @freezed 只描述資料形狀，使用者不用知道生成 mixin 的名字。現行 codegen surface 需要使用者把生成 mixin 接上去，這就是學習成本來源
• abstract class + factory 需要語言模型支撐：abstract class 不能直接 new，但 factory 可以回傳具體子類。Freezed 產生 _PeriodReportRow，因此這個寫法在語言上成立；直覺成本來自「門面類」和「具體生成類」分離

那「設計得不當」的真正主體是誰

這個問題要拆成三層看：

1. 你的 model 設計：宣告一個 immutable DTO 並實作金額視圖契約，這個方向成立
2. Freezed 的設計：它用 codegen 換掉大量樣板，代價是 part、with _$Foo、factory redirect 這些接線露在使用者面前
3. Dart 的語言能力：Dart 長期缺少穩定的 data class / static metaprogramming 能力，讓資料模型的重複樣板需要靠 build_runner 與外部 codegen 補齊

未來改善方向不是 macros 這條直線

Dart 官方在 2025-01-29 宣布停止 macros 工作，因此「等 Dart macros 穩定後，這層拆分自然消失」已經不是可靠判斷。更務實的觀察是：Dart 仍會改善資料建模與 codegen 體驗，但方向可能是更專門的 data language features、build_runner 改善或 augmentations，而不是通用 macros。

理想中的資料模型語法可能長得像這樣：

1@Data()
2class PeriodReportRow implements ReportAmountsView {
3  final String date;
4  final Decimal grossAmount;
5  // ... 18 個欄位
6}
7// 目標是讓資料形狀、序列化、value equality、copyWith 更接近語言級宣告

這段只能當作「期待中的語言表達能力」，不能當作 Dart 已承諾的 roadmap。對今天的專案來說，Freezed 仍然是把資料模型樣板壓低的成熟工具；它的成本是 build_runner、生成檔、以及本文拆解的三層心智模型。

第四層：沒有 freezed 怎麼做

如果規劃時就決定不裝 freezed、Dart 怎麼處理「immutable + JSON + copyWith + equality」這組需求？

路線一：純手寫

把 freezed 產的東西自己寫一遍：

 1class PeriodReportRow implements ReportAmountsView {
 2  final String date;
 3  final int primaryOrderCount;
 4  final Decimal grossAmount;
 5  // ... 其他 16 個欄位
 6
 7  const PeriodReportRow({
 8    required this.date,
 9    required this.primaryOrderCount,
10    required this.grossAmount,
11    // ...
12  });
13
14  factory PeriodReportRow.fromJson(Map<String, dynamic> json) {
15    return PeriodReportRow(
16      date: json['date'] as String,
17      primaryOrderCount: json['primary_order_count'] as int,
18      grossAmount: jsonToDecimal(json['gross_amount']),
19      // ... 重複 18 次
20    );
21  }
22
23  Map<String, dynamic> toJson() => {
24        'date': date,
25        'primary_order_count': primaryOrderCount,
26        'gross_amount': grossAmount.toString(),
27        // ... 重複 18 次
28      };
29
30  PeriodReportRow copyWith({
31    String? date,
32    int? primaryOrderCount,
33    Decimal? grossAmount,
34  }) =>
35      PeriodReportRow(
36        date: date ?? this.date,
37        primaryOrderCount: primaryOrderCount ?? this.primaryOrderCount,
38        grossAmount: grossAmount ?? this.grossAmount,
39        // ... 重複 18 次
40      );
41
42  @override
43  bool operator ==(Object other) =>
44      identical(this, other) ||
45      other is PeriodReportRow &&
46          other.date == date &&
47          other.primaryOrderCount == primaryOrderCount &&
48          other.grossAmount == grossAmount;
49          // ... 重複 18 次
50
51  @override
52  int get hashCode => Object.hash(date, primaryOrderCount, grossAmount /* 18 個 */);
53
54  @override
55  String toString() => 'PeriodReportRow(date: $date, ...)';
56}

18 個欄位 × 6 個樣板 ≈ 150 行、每加一個欄位要改 5 處（constructor、fromJson、toJson、copyWith、==、hashCode）。漏改一處 → 隱性 bug。

路線二：只 codegen 序列化、其他手寫

只用 json_serializable（比 freezed 輕量很多）：

 1@JsonSerializable()
 2class PeriodReportRow {
 3  final String date;
 4  @JsonKey(name: 'primary_order_count') final int primaryOrderCount;
 5  @DecimalConverter() final Decimal grossAmount;
 6  // ...
 7
 8  const PeriodReportRow({required this.date, ...});
 9
10  factory PeriodReportRow.fromJson(Map<String, dynamic> json) =>
11      _$PeriodReportRowFromJson(json);
12  Map<String, dynamic> toJson() => _$PeriodReportRowToJson(this);
13
14  // 不寫 ==、hashCode、copyWith
15}

省掉 fromJson / toJson 的樣板（最容易出錯的部分）、但仍要自己寫 == 和 copyWith（如果需要）。

路線三：Dart 3 Records

 1typedef PeriodReportRow = ({
 2  String date,
 3  int primaryOrderCount,
 4  Decimal grossAmount,
 5  // ...
 6});
 7
 8// 建立
 9final row = (
10  date: '2026-05-11',
11  primaryOrderCount: 0,
12  grossAmount: Decimal.zero,
13  // ...
14);
15
16// 「copyWith」就是用解構重組
17final next = (
18  date: row.date,
19  grossAmount: newAmount,
20  primaryOrderCount: row.primaryOrderCount,
21  // ...
22);

Record 是 Dart 3 內建的不可變值型別，適合短距離攜帶一組值：

• 支援：自動 == / hashCode / toString
• 支援：不可變
• 限制：無名 → 不能 implements ReportAmountsView、不能加方法、不能 extends
• 限制：JSON 還是要手寫
• 限制：沒有 named constructor → 無法做「from raw API JSON」的轉換邏輯

對「跨模組共享、需要實作介面、需要 fromJson」的 DTO，record 的語意承載力不足。對「函式內部短暫的多回傳值」，record 很合適。

真正該問的問題：你需要的是哪幾項

回頭把「freezed 給你的功能」拆開看、對 DTO 真正用得到的有：

這個 DTO 情境的核心需求是 JSON 轉換與 immutable；其他能力是 Freezed 順手提供的附加價值，是否有用取決於後續資料流。

過剩功能不是壞事、但會誤導

用了 freezed 後會傾向「reach for copyWith」，因為它就在那。如果一開始只用 json_serializable，可能根本不會在 DTO 上做修改。較穩定的 DTO 用法是把 DTO 視為 API 邊界的快照；需要變更行為時，轉成 domain model 再承載狀態變化。

這次 DTO 只吃到 Freezed 的部分價值

Freezed 在 DTO 上仍有價值，尤其是 immutable、JSON 轉換接線、欄位同步與 toString 除錯。這次報表 DTO 的資料流比較單純，主要吃到的是 JSON 轉換與 immutable；copyWith、sealed union、複雜狀態轉移這些能力比較像附加值。

Domain 物件（如 ShoppingCart、Order）常有「在現有狀態上做小修改」或「多種狀態擇一」的場景，這時 copyWith 與 sealed union 更容易回收那層拆分成本。比較精確的判斷不是「Freezed 不適合 DTO」，而是「不同 model 層吃到的 Freezed 價值不同」。

第五層：更好懂的路徑是中間投影物件

重新用 WARP 看這個設計時，決策錨點不是「怎樣讓 builder 少寫一次」，而是「下一個維護者能不能快速看懂資料怎麼從後端 row 變成報表 sections」。如果這個錨點成立，讓 DTO 直接 implements ReportAmountsView 的寫法就不一定是最佳答案。

目前的做法把共用點放在 DTO 型別上。兩種報表 row 都是後端 API row，卻為了共用 _buildGeneralSections / _buildAccountSections，一起實作一個 18 個 getter 的 ReportAmountsView。這在型別上可行，但讀者要同時理解 Freezed 生成類、mixin、interface、DTO 與報表 builder，才能知道為什麼這行能編譯。

共用 builder 的三個局部方案

方案 1 是目前寫法。它的優點是 _buildGeneralSections / _buildAccountSections 可以直接共用，而且沒有額外 mapping；缺點是共用介面綁在 API DTO 上，讓「後端資料形狀」和「報表需要的共同金額視圖」混在同一層。這種寫法對熟悉 Freezed 的人不難，但對第一次接手的人，理解成本集中在一行 class 宣告上。

方案 2 是最直白的寫法。每種報表 row 用自己的 builder，讀者不用理解跨 DTO 介面；缺點是兩份 builder 很容易長得幾乎一樣。當報表欄位增加或文字調整時，維護者要記得同步兩邊，重複會變成一致性風險。

方案 3 把共用點移到更貼近需求的中間層。DTO 仍然只描述 API 回傳形狀，報表 builder 只吃 ReportAmounts，兩個 row 各自用 extension 或 mapper 明確轉成報表需要的共同資料。

 1class ReportAmounts {
 2  const ReportAmounts({
 3    required this.primaryOrderCount,
 4    required this.primaryTurnover,
 5    required this.grossAmount,
 6    // ...其餘報表需要的金額欄位
 7  });
 8
 9  final int primaryOrderCount;
10  final Decimal primaryTurnover;
11  final Decimal grossAmount;
12}
13
14extension SingleRunReportRowAmounts on SingleRunReportRow {
15  ReportAmounts toAmounts() => ReportAmounts(
16        primaryOrderCount: primaryOrderCount,
17        primaryTurnover: primaryTurnover,
18        grossAmount: grossAmount,
19      );
20}
21
22extension PeriodReportRowAmounts on PeriodReportRow {
23  ReportAmounts toAmounts() => ReportAmounts(
24        primaryOrderCount: primaryOrderCount,
25        primaryTurnover: primaryTurnover,
26        grossAmount: grossAmount,
27      );
28}

這個 mapping 看起來重複，但它是有價值的重複：它明確標出「哪些 API 欄位被投影成報表金額」。後端欄位名稱或語意改變時，維護者會在 mapper 裡看到轉換邊界，而不是在一個 18-getter interface 裡推理兩個 DTO 為什麼剛好長得一樣。

重新判斷

以好懂與好維護為核心，方案 3 比方案 1 更穩。它多寫一個 ReportAmounts 和兩份 mapping，但把複雜度放在比較合理的位置：DTO 層接 API，projection 層接報表語意，builder 層只處理畫面 / 呈現 sections。

方案 1 可以短期保留，因為它型別安全、改動小、和既有 Freezed 寫法一致。但若這段程式會長期被不同人維護，或未來還會增加其他 report row，應把 ReportAmountsView 換成明確的 ReportAmounts 投影模型。

實作落地時還有一個命名細節：如果已經從「共用介面」改成「中間投影模型」，檔名也應從 report_amounts_view.dart 改成 report_amounts.dart。否則程式碼雖然改成 projection，讀者仍會被舊的 View 命名帶回「DTO 實作介面」的心智模型。

實作後驗證

這輪實作已經把 ReportAmountsView 移除，改成 ReportAmounts 投影模型與兩個 toAmounts() extension。局部 flutter analyze 對修改檔案通過，並補了 report_amounts_test.dart 驗證兩種報表 row 的共同金額欄位投影正確。

這個驗證證明 projection 邊界在型別與欄位對應上可行，但它還沒有驗證呈現版面或實際 API response 的完整結果。後續若報表內容有差異，應回到 sections builder 或 API 欄位語意，而不是回頭讓 DTO 重新實作共用介面。

規劃有沒有瑕疵

整體判斷：使用 Freezed 本身不是瑕疵，但共用 builder 的抽象位置值得調整。

1. 工具選擇是「一致性 vs 適配度」的取捨

這類專案統一使用 freezed 的收益：

• 一致性：所有 model 一樣寫，接手者不用學兩套
• 未雨綢繆：今天 DTO 不需要 copyWith、明天可能要（例如做 optimistic update 時要短暫修改 DTO）
• 降低決策成本：不用每個 model 問「這個需要 copyWith 嗎？」

成本：

• DTO 上「邊際過剩」：用不到的功能也產出來、多花 build_runner 時間
• 抽象洩漏：使用者必須懂 _$ / part / mixin

這個取捨沒標準答案、看團隊規模和維護週期。若系統長期維護、多人接手、既有專案已經採用 Freezed、而 build_runner 成本可接受，一致性的價值通常會高於 DTO 上的邊際過剩。

2. DTO 與 domain model 兩層分離仍然合理

不在「用了 freezed」、而在於——是否需要 DTO 與 domain model 兩層分離？

這類專案結構：

1SingleRunReportRow（DTO、貼著 API）
2       ↓ service 轉換
3ReportSummary（domain、貼著 UI / 呈現）

兩層是分開的。這個分層有成本：

• 多寫一個 model
• 多寫一份轉換邏輯
• 多一份要維護

但價值：

• 後端改 API 欄位名 → 只動 DTO 層、domain 不受影響
• UI 要新增顯示邏輯 → 只動 domain 層、DTO 不受影響
• 呈現報表的格式可以脫離 API 變化

對長期維護、資料語意敏感的營運系統，這層分離通常值得；對短期 prototype，這層分離的維護成本可能高於收益。

3. 共用 builder 的抽象位置可能放太早

ReportAmountsView 把報表需要的共同欄位直接壓到 API DTO 上，這是目前寫法最需要檢討的地方。更清楚的分層是：DTO 先完整接住後端 row，再由 mapper 投影成 ReportAmounts，最後由 sections builder 使用這個報表模型。

這個調整不會否定 Freezed，也不會否定 DTO / domain 分層。它只是把「共同報表金額」從 API DTO interface 移到報表投影層，讓型別關係更接近讀者真正要理解的資料流。

一個反向思考

如果沒有 freezed、會怎麼做？

我猜會：

1. DTO 只用 json_serializable（最輕量）
2. domain model 手寫（反正欄位通常比 DTO 少）
3. 用 immutable 慣例但不強制（final 欄位 + 沒有 setter）

這樣寫出來會比現在少一層拆分但多一些手寫樣板。誰好誰壞、看 trade-off 什麼：

結論

1. 「拆」是 Freezed 在 Dart 現有 codegen surface 下的工程妥協：它用三層結構換掉大量手寫樣板
2. with _$Foo 和 part 是漏出的實作細節：使用者需要理解 library、mixin、factory redirect，才能讀懂 Freezed 生成模型
3. 不同 model 層吃到的 Freezed 價值不同：DTO 常吃到 immutable / JSON / 欄位同步，domain model 更容易吃到 copyWith / union / 狀態轉移能力；統一用法換來的一致性，在長期維護的專案上可能值得
4. Dart macros 不是可期待的解法路線：官方已停止 macros 工作，後續改善更可能來自 data features、build_runner 或 augmentations
5. 真正要檢討的是分層邊界：DTO 與 domain model 分離是否值得，比 with _$Foo 本身更接近架構決策
6. 目前 implements ReportAmountsView 可行但不一定最好懂：若核心目標是長期維護，ReportAmounts 投影模型通常比讓 API DTO 直接實作共用介面更清楚；落地時連檔名也要改成 projection 命名，避免舊抽象殘留

換個角度說：當你寫 with _$PeriodReportRow 時，你是在接受一個 codegen 工具的心智模型，用它補上資料類型在手寫 Dart 裡會產生的大量樣板。

附錄：今日實作中相關的設計決策

這次新增週期彙總報表 API 時，面對的關鍵設計選擇是「沿用既有 row、還是新增一個獨立 row」。

當下選擇了新增，然後抽 ReportAmountsView 介面共用 sections builder。這個決策當時在 A/B/C 三個選項裡合理，但重新用「好懂、好維護」作為錨點審查後，應該補上第四個選項：

選項 A 的主要問題是型別會說謊。既有 row 有單次作業、操作者、時間等語意，新的 row 是跨作業週期彙總；把兩種欄位塞進同一個 row，會讓 optional 欄位承擔太多語意分支。

選項 B 的主要問題是同步成本。它最容易讀，但如果兩種報表的 sections 幾乎一致，後續調整顯示項目時就要維護兩份相似邏輯。

選項 C 是當下採用的路徑。ReportAmountsView 只覆蓋「金額部分」、操作者 / 作業週期 / 日期等識別欄位刻意留給各自的 row 自管，避免介面變成 god interface；但它也讓 API DTO 直接承擔報表共用介面，讀者必須理解 Freezed 的門面類、generated mixin 與具體生成類。

選項 D 是重新審查後更好的候選。它保留兩種報表 row 各自獨立，也保留 sections builder 共用，但把共用點移到 ReportAmounts 這個報表投影模型。這樣多寫的 mapping 是刻意暴露資料轉換邊界，而不是無效樣板。

因此，本文更新後的判斷是：當下選 C 可以理解，但若要讓程式碼更好懂、更好維護，實作上應改成 D。

參考資料

• freezed 套件
• Dart language tour - Mixins
• Dart language tour - Libraries and imports
• Dart Blog - An update on Dart macros & data serialization
• Dart Records
• 既有的 freezed 選型評估筆記

關聯 Ticket：0.2.0-W5-007 決策結論：移除 freezed，採用 json_serializable + Equatable

我設定了一個新的需求開了一個專案，我沒有專門指定開發的框架或者細節，我只有很簡單的先建立我需求的 spec 文件，這個文件當然並不完整，我是希望先讓AI做一個 原形，我會在 prototype 符合我的需求動起來之後再介入去調整設計。

我的初始技術規範就只有我要用 flutter 去寫，所以AI就動了，但是在中間我發現 AI使用了 Freezed ，我並不喜歡在我 build 之外還要做一次 code generation 的動作，所以我就跟AI討論一次關於 Freezed 這種做法的必要性，至少在原形階段我覺得單純一點的 model 檔案沒有什麼不好，也不大會出錯，整體討論下來我選擇 捨棄 已有的 Freezed 程式碼，重構成更簡易的 版本，但是我覺得這個評估還是很有價值，所以讓AI重新整理了一次討論的內容作為備查。

1. Freezed 是什麼

Freezed 是 Dart 的自動程式碼產生（code generation）套件，專門用來幫你自動生成資料類別（data class）裡那些重複的樣板程式碼（boilerplate），包括：

• copyWith：複製一份物件，但可以只改其中幾個欄位，常用在狀態管理時產生新狀態
• == / hashCode：值相等比較（value equality），讓兩個內容相同的物件被判定為「相等」
• toString：把物件轉成易讀的字串，方便除錯
• fromJson / toJson：JSON 序列化與反序列化，搭配 json_serializable 使用，處理前後端資料交換
• 聯合型別（Union types）/ 密封類別（sealed class）：用 @freezed 的多建構子語法，實現型別安全的多態模式

解決的核心問題：Dart 的類別預設是可變的（mutable），而且比較兩個物件時只看記憶體位址是否相同（identity equality），不會比較欄位內容。如果要手刻一個有 10 個欄位的不可變資料物件（immutable value object），大約需要 80-120 行程式碼，而且每次修改欄位都要同步更動 6 個地方（欄位宣告、建構子、copyWith、==、hashCode、toJson），非常容易漏改出錯。

2. 優缺點分析

優點

缺點

3. 適用場景判斷表

4. 替代方案比較

方案 B 詳細說明（本專案推薦）

• JSON 序列化：保留 json_serializable（10 個模型仍需 fromJson / toJson），build_runner 僅用於 JSON
• Value equality：使用 Equatable 套件，繼承 Equatable 並宣告 props 即可，零 code generation
• copyWith：僅 2 個 State 類別（SessionListState、ConversationState）需要，手寫工作量極小
• Immutability：使用 final 欄位 + 命名建構子，Dart 語言層級保證

方案 D 補充說明（Dart 3 原生特性）

Dart 3.0+ 引入的原生特性可部分替代 freezed：

5. 與狀態管理框架的關係

Riverpod 的 Value Equality 機制

常見誤解：「Riverpod 需要 freezed 才能正確判斷狀態變更」。

事實釐清：

1. Dart 預設是 identity equality（比較記憶體位址）。兩個欄位完全相同的新物件，== 仍為 false
2. Riverpod 在 state = newValue 時使用 == 判斷是否通知 listener rebuild。相同則不通知
3. Riverpod 本身不做任何額外 equality 優化，完全依賴物件自身的 == 運算子

此專案的實際影響

在本專案中，不使用 value equality 的影響極小：

結論：Equatable 零 code generation 即可解決 value equality 需求。在本專案場景下，甚至完全不處理也感受不到效能差異。

6. 決策流程

 1是否需要 freezed?
 2    |
 3    v
 4模型數量 > 50?
 5    +-- 是 --> 強烈建議使用 freezed
 6    +-- 否 ↓
 7    |
 8使用 union types / sealed class?
 9    +-- 大量使用 --> 建議使用 freezed（或 Dart 3 sealed class）
10    +-- 未使用 ↓
11    |
12欄位頻繁變動?
13    +-- 是 --> 建議使用 freezed（減少同步維護）
14    +-- 否 ↓
15    |
16需要深層巢狀 copyWith?
17    +-- 是 --> 建議使用 freezed
18    +-- 否 ↓
19    |
20需要 JSON 序列化?
21    +-- 是 --> json_serializable 即可
22    +-- 否 ↓
23    |
24需要 value equality?
25    +-- 是 --> Equatable 或手寫 ==
26    +-- 否 --> 完全不需要 freezed

7. 本專案評估結論

現況盤點

評估對照

決策

移除 freezed，採用方案 B：保留 json_serializable 處理 JSON 序列化，使用 Equatable 處理 value equality，手寫 copyWith（僅 2 個 State 類別）。

理由：freezed 在本專案中只用到最基礎功能（copyWith、==、JSON），全部可被更輕量的方案替代。移除後減少 build_runner 依賴範圍、消除生成檔案膨脹、降低版本耦合風險。

8. 遷移檢查清單

準備階段

• 確認所有 @freezed 類別清單（12 個）
• 備份現有生成檔案
• 確認 json_serializable 獨立使用的配置方式

資料模型遷移（10 個）

• 移除 @freezed 註解，改為 @JsonSerializable + final class
• 保留 part '*.g.dart'（json_serializable 仍需要）
• 移除 part '*.freezed.dart'
• 繼承 Equatable，宣告 props
• 手寫建構子（const 建構子 + final 欄位）
• 確認 fromJson / toJson 正常運作

UI State 遷移（2 個）

• 同上資料模型遷移步驟
• 手寫 copyWith 方法
• 確認 Riverpod 狀態更新行為正確

清理階段

• 刪除所有 .freezed.dart 生成檔案
• 從 pubspec.yaml 移除 freezed 和 freezed_annotation 依賴
• 執行 dart run build_runner build 確認 json_serializable 正常
• 執行全量測試確認無回歸
• dart analyze 0 issues

參考資源

• freezed 套件
• json_serializable 套件
• equatable 套件
• Dart 3 Patterns and Sealed Classes

Last Updated: 2026-03-26 Version: 1.0.0