TL;DR

當軟體開發還是一門工程學

1970 年代，當軟體開發還是一門新興學科時，人們自然地從傳統工程領域借鑒經驗。

蓋房子需要藍圖、造橋需要設計圖，那麼開發軟體當然也需要完整的規格文件——這個看似合理的類比，開啟了長達數十年的瀑布式開發時代。

有趣的是，瀑布式開發 - Waterfall 這個名詞首次出現在1970年 Winston Royce 的論文中

但 Royce 其實只是點名在當時的主流方法，並且給這種方法一些批評與建議。

只是產業界選擇性地抓住了 Buzz Word ”Waterfall” 並將其奉為圭臬，而忽略了他的警告。

當然這也不是第一次業界扭曲軟體工程理論的原意。

瀑布模式的黃金年代

流程的確立

瀑布式建立起一套看似完美的流程：

需求分析 → 系統設計 → 實作 → 測試 → 部署 → 維護

就像接力賽跑，一棒接一棒，每個階段都有明確的交付物和把關者。

需求分析階段產出厚達數百頁的需求規格書（SRS, Software Requirements Specification），

系統設計階段則有高階設計（HLD, High-Level Design）和低階設計（LLD, Low-Level Design）文件。

這些文件不只是參考，而是具有合約效力的承諾。

當時的人相信，只要文件夠詳細，開發就是照著做而已。

甚至 UML 也在那個時代應運而生。

角色分工的確立

這個時期也確立了軟體開發的專業分工：

• PM（專案經理）負責管理時程與資源，通常不懂技術
• SA（系統分析師）負責理解業務需求，把業務語言翻譯成技術語言
• SD（系統設計師）負責技術架構，畫一堆UML圖
• PG（程式設計師）負責編碼實作，被視為「碼農」
• QA（品質保證工程師）負責測試驗證，專門找碴

這種分工暗示著「思考」和「執行」是可以分離的。

會思考的人負責設計，會打字的人負責coding。

這種階級觀念到今天都還沒完全消失。

為什麼瀑布式曾經如此成功？

無法失敗的時代背景

在1980年代，一套企業系統可能要價數百萬美元，開發週期動輒2-3年。

IBM的System/360開發耗資50億美元（相當於今天的400億），這種規模的投資容不得失敗。

瀑布式提供了管理層最需要的東西：控制力(或許只是幻覺)。

每個階段都有文件、有簽核、有人負責。出事了可以調出文件來看是誰的錯。

這種「可究責性」讓高層睡得安心。

適合當時的技術限制

當時的開發環境是什麼樣子？

• 沒有 Git，版本控制用 CVS/RCS 等集中式系統，或原始的複製資料夾
• 早期沒有 IDE，主要用 vi 或 Emacs，90年代才有原始的 IDE
• 編譯大型專案可能要等數小時
• 測試主要靠人工，自動化測試工具原始且昂貴
• 部署要半夜停機，通過實體媒介發布

在這種環境下，改一行code的成本可能是現在的100倍。

「想清楚再動手」不只是最佳實踐，而是唯一選擇。

[個人經驗補充區]

瀑布式的內在矛盾

文件與現實的落差

最大的問題在於：軟體是看不見、摸不著的。

建築師可以做模型，讓客戶看到未來的大樓長什麼樣子。

但軟體呢？畫了100張UML圖，客戶還是不知道系統用起來是什麼感覺。

更慘的是，需求文件寫著「系統應支援多使用者同時操作」，但什麼叫「多」？

10個？1000個？每個人心中都有不同的數字，直到系統上線當機才發現認知落差。

溝通的斷層

瀑布式假設資訊可以無損地傳遞，但現實是每一次傳遞都會失真，每一層次轉換都是風險：

客戶說：「我要一個簡單的購物網站」

PM聽成：「要有會員系統、商品管理、訂單處理、金流串接…」

SA寫成：「系統應提供使用者友善的介面以利商品選購」

SD設計成：「採用三層式架構搭配MVC模式」

PG實作成：「if-else地獄加上全域變數」

最後客戶看到成品：「這不是我要的！」

變更的成本

瀑布式最致命的假設是：需求是可以預先確定且不會改變的。

但現實是，客戶看到系統之前，根本不知道自己要什麼。

網路時代的衝擊

指 dot com 泡沫到 web 2.0 的時代。

產品生命週期從年變成月

競爭對手不是隔壁公司，而是地球另一端的車庫創業

當你的競爭對手每週更新，而你還在等三個月後的UAT（使用者驗收測試），市場早就不見了。

搶佔市場的思維，改變了軟體工程，敏捷成為主流，我們之後再說。

但某些領域仍然需要瀑布式：

• 醫療設備軟體：FDA要求完整的文件追蹤，一個bug可能害死人
• 航太系統：NASA的軟體開發依然遵循嚴格的階段審查
• 金融核心系統：當你處理的是別人的錢，「快速失敗」不是選項

這些領域的共同點是：錯誤的成本遠大於延遲的成本。

更深層的影響是，瀑布式留下的不只是流程，更是一種思維模式。

即使號稱敏捷的團隊，實際上仍在執行小瀑布

下一篇，我們將探討敏捷如何試圖解決這些問題，以及為什麼「敏捷」為什麼也失敗。

參考

• 以前的程序员，除了敲代码，还得会画画【让编程再次伟大#42】
• RUP 統一軟體開發過程
• 序列圖，UML 給軟體開發帶來的唯一好處
• 我们都只是在假装着做Agile【让编程再次伟大#43】

(fin)

TL;DR

簡介 SDD

What is Spec-Driven Development?
Spec-Driven Development flips the script on traditional software development.
For decades, code has been king — specifications were just scaffolding we built and discarded once the “real work” of coding began
Spec-Driven Development changes this: specifications become executable, directly generating working implementations rather than jus
guiding them. – spec-kit

什麼是規格驅動開發 ???
跟過往的開放方式什麼不同???
什麼原因讓它興起 ???

傳統開發流程(1990之前)

回顧軟體開發的歷史，個人電腦時代到網路時代(1975~1990)

大部份是傳統的瀑布式開發（Waterfall）流程是這樣的：

像是接力賽跑一樣一棒接一棒。

需求分析 → 系統設計 → 實作 → 測試 → 部署 → 維護

每個階段都有明確的交付物：

需求分析:產出需求規格書（SRS），對應的角色會有 PM(產品或專案經理)

系統設計:產出設計文件（HLD/LLD），對應的角色會有 SA/SD(系統架構師/系統設計師)

實作階段:產出程式碼，對應的角色會有 RD(工程師)

測試階段:產出測試報告，對應的角色會有 QA(測試工程師)

這個流程有幾個特點：

線性且不可逆 - 每個階段必須完成才能進入下一階段，很難回頭修改

文件導向 - 大量的文件作為階段間的交接依據

後期才見成果 - 要等到實作階段完成，才能看到實際的軟體

變更成本高 - 越晚發現問題，修改成本越高

在這個模式下，規格文件的角色是契約和藍圖。團隊花費大量時間撰寫詳細的規格，試圖在開始編碼前就想清楚所有細節。

但實務上，這些文件往往：

• 寫完就過時，因為需求會變
• 與實作脫節，因為開發時會發現新問題
• 成為負擔，因為要花時間維護卻沒人看

敏捷開發流程(1990~至今)

敏捷開發（Agile）的出現，是對瀑布式開發的反思。它強調：

• 個人與互動 > 流程與工具
• 可用的軟體 > 詳盡的文件
• 客戶合作 > 合約協商
• 回應變化 > 遵循計劃

敏捷的典型流程（以 Scrum 為例）：

Product Backlog → Sprint Planning → Daily Standup → Sprint Review → Sprint Retrospective

這是一個迭代循環，每個 Sprint（通常 2-4 週）都會產出可用的軟體增量。

• Product Backlog: 對齊高層期望，主要角色 Stackholder/Product Owner
• Sprint Planning: 對齊實作時程與方式，主要角色 Product Owner/Team
• Daily Standup: 對齊每日進度，全角色參與
• Sprint Review: 對齊結果，全角色參與
• Sprint Retrospective: 對齊改善，全角色參與

雖然實施部分的Scrum 是可能的，但結果就不是Scrum 了

敏捷的特點：

• 迭代且增量 - 小步快跑，頻繁交付
• 溝通導向 - 強調面對面溝通勝過文件
• 早期且持續交付 - 每個 Sprint 都有可展示的成果
• 擁抱變化 - 將變更視為常態而非例外

在敏捷模式下，規格文件的角色變成了溝通工具和備忘錄。

User Story、Acceptance Criteria 這些輕量級的規格，主要是為了確保團隊理解一致。

程式碼本身成為了真相的來源 - “Code is the truth”。

在迭代過後，這些文件不再有意義。

這解決了瀑布式的一些問題，但也帶來新的挑戰：

• 知識容易流失（口頭溝通沒有記錄，使用團隊記憶）
• 技術債累積（快速迭代可能犧牲品質）
• 規格與實作的差距依然存在
• 實際上團隊/文化等因素，在跑的只是 Scurm-but/小瀑布/隕石
• 商業化的行為已經扭曲原意，甚至作為 KOL 老王賣瓜的神主牌 (看看”敏捷社群”)
• 在大型產品/專案仍然不足夠，因而衍生 SAFe/LeSS 等方法論
• 淪為表面功夫

隕石開發流程(Alpha~Omega)

典型流程

老闆一句話 → 隨便硬幹出來 → 夠奴就加班 → 交付疊加態 → 塊逃啊

• 老闆一句話：靈感一來就開幹，需求模糊。
• 隨便硬幹出來：原型被誤當產品，直接上線。
• 夠奴就加班：團隊燃燒工時與理智，一次衝到底。
• 交付疊加態：交付內容沒人知，時程沒人知，測沒測沒人知。
• 塊逃啊：事後檢討變成批鬥大會，成功不在你，但失敗一定有份。

特點與本質

高壓短命、方向即興、溝通崩壞、文件失效、驗收模糊。
看似混亂，其實是一種生存策略(實用主義)：

• PM 可保命：有 Demo、有交付，能交差。
• 行銷能吹噓：原型當 MVP，上媒體先贏聲量。
• 市場能行（騙）銷：先開賣、後補齊。
• 老闆能交代：有成果、有故事，股東就安心。
• RD 隨便作，洗個經驗跳糟加薪比較快

隕石開發不是技術問題，而是組織文化的選擇。

這些流程的異同、優劣與困境

瀑布、敏捷與隕石開發的差別，反映的是組織文化與生存策略。

瀑布式重規劃與控制，適合穩定需求與高風險專案，但變更成本高、回饋慢。

敏捷式重回饋與溝通，能快速交付並擁抱變化。

隕石式則靠爆發力求生存，短期有成效，不考慮長期品質與維運。

我的看法是新創成長到高原期時，就會從隕石走而敏捷，再大規模就會考慮瀑布/LeSS/SAFe，

而市場大部份都是中小企業，真的能成長成巨人者(amazon/spotify/netfilx)，

一定有它的原因，開發流程應該隨著公司業務成長，形成自已的文化，沒有一定的好壞，也不是可以輕易模仿的。

工程師的自我要求

我個人是傾向 XP 的開發模式，但是它的缺點是學習門檻高，

對面試沒幫助，更多的公司寧願你寫白板題或刷 LeetCode。

團隊不願意投入，相關的 TDD/ATDD/BDD 或是測試左移更難導入小團隊之中。

高層如果沒有技術能力，無法識別好壞，就容易被唬弄，導致需求與實作有落差

AI SDD 流程(2024~未來?)

AI Agent 或 SDD 出現後能不能帶來改變?

或是可以帶來什麼幫助呢?

對工程師而言

• 內建 TDD，但是工程師仍要學習其觀念
• 降低學習門檻，可以用更 Clean 的方式實作代碼
• 全權委託，但是工程師要對架構負責(變得更像 SA ?)
• 淘汰劣質工程師，ex 轉職班、就業班、刷題仔，但是有的很會行銷自已，會被唬弄過去

對產品而言

• 可以縮短想法到實作的距離
• 保持一定的品質，特別是你的工程師都是來自x成、x匠時…
• 自已開發，更高的回饋

問題，認知的差距，人只能賺到自已認知能力內的錢

之前有一個網紅行銷使用 Agent 開發賣課，犯了最低級的錯誤

這是因為他缺乏資安的認知; 所以原本不是開發的人員會需要快速的學習相關的知識(但是 AI 可以將門檻降低)

另外一些反思，那種工程師看不上眼的程式(普遍社群上的工程師都在嘲諷)，

人家已經拿來行銷賣錢，或許工程師應該反向思考怎麼朝行銷/產品靠攏

也或許這個低級錯誤也是行銷手段的一環?

接下來， 我將會用一系列的文章來試作 SDD 並分享我的看法

參考

• 隕石開發流程
• 隕石開發流程-中文版
• Martin Fowler 澳洲演講筆記-變質的敏捷，回歸初衷。
• 軟體工匠的悲歌 The Tragedy of Craftsmanship.

(fin)

前言

最近有位小朋友在進行中文轉換規則的開發時，遇到了一些典型的程式碼異味。

這些異味提示著我們需要重構，你可以先挑戰看一下有沒有辦法識別。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// 重構前的程式碼
apply(text: string): string {
  const protectedChars = ['台']
  
  // 1. 標記階段
  let protectedText = text
  protectedChars.forEach((char) => {
    protectedText = protectedText.replaceAll(char, `<<<${char}>>>`)
  })

  // 2. 轉換階段
  let result = this.baseConverter(protectedText)

  // 3. 還原階段
  protectedChars.forEach((char) => {
    const convertedChar = this.baseConverter(char)
    result = result.replaceAll(`<<<${convertedChar}>>>`, char)
  })

  // 4. 自訂轉換
  result = this.customConverter(result)
  
  return result
}

這篇文章記錄重構的過程，讓程式碼變得更加簡潔和易讀。

當然，這只是其中一種可能的重構方式，可能有別的解法，或是單純的接受它。

壞味道

原始的 ChineseConversionRule 中的 apply 方法存在以下問題：

1. 過多中間變數：text → protectedText → result
2. 命令式寫法：透過變數重新賦值來處理資料流
3. 邏輯分散：標記保護字符和還原的邏輯內嵌在主方法中

過多的中間變數和命令式的寫法讓程式碼顯得冗長且不夠優雅。

protectedText、result、text　都是。

這裡的挑戰是要對原始的字串加工

在不破壞原本邏輯的情況下，保留擴充的彈性，並保持程式結構清晰、可維護。

可能有很多模式可以解決(Decorator / Template Method / Pipeline)

小朋友寫得也不差了，我們來試著讓它更好

重構過程

階段一：消除中間變數

第一步是消除不必要的中間變數，直接在同一個變數上操作：

可以看到修改後，只有 text 一個變數，還是傳入了的

越少變數，越不用花心思思考命名，減少認知負擔，而本質上這些冗餘的變數的確是同質可以刪除的

這是一種隱性的重複壞味道。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

apply(text: string): string {
  const protectedChars = ['台']
  
  // 直接操作 text 變數，消除 protectedText 和 result
  protectedChars.forEach((char) => {
    text = text.replaceAll(char, `<<<${char}>>>`)
  })

  text = this.baseConverter(text)

  protectedChars.forEach((char) => {
    const convertedChar = this.baseConverter(char)
    text = text.replaceAll(`<<<${convertedChar}>>>`, char)
  })

  return this.customConverter(text)
}

階段二：引入 Functional Programming

接下來導入函數式程式設計的概念，使用 pipe 模式來處理資料流：

這裡要先看懂 pipe，簡單理解它把一個初始值依序丟進多個函數，前一個輸出就是下一個的輸入。

可以看到一些明顯的壞味道，重複的 protectedChars，1 跟 3 本身是匿名函數，讀起來也沒那麼好理解，

這是重構必經之路，我們再往下走

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

apply(text: string): string {
  const protectedChars = ['台']
  
  return this.pipe(
    text,
    // 1. 標記階段：將需要保護的字符標記為不轉換
    (input) => protectedChars.reduce((acc, char) =>
      acc.replaceAll(char, `<<<${char}>>>`), input),
    
    // 2. 轉換階段：使用 OpenCC 進行轉換
    this.baseConverter,
    
    // 3. 還原階段：將標記的字符還原為原始字符
    (input) => protectedChars.reduce((acc, char) => {
      const convertedChar = this.baseConverter(char)
      return acc.replaceAll(`<<<${convertedChar}>>>`, char)
    }, input),
    
    // 4. 使用自訂轉換器進行模糊字詞的修正
    this.customConverter
  )
}

// 自製的 pipe 函數
private pipe<T>(value: T, ...fns: Array<(arg: T) => T>): T {
  return fns.reduce((acc, fn) => fn(acc), value)
}

階段三：職責分離

將標記和還原邏輯抽取成獨立的私有方法：

將重複出現的 protectedChars 提升為類別屬性：

也不需要把匿名函數寫一坨在 pipe 裡面，這時要煩惱的只有方法的名字要怎麼才達意

但至少我們還有註解。

更進一步可以簡化方法內的參數名，因為 scope 很小，不會有認知負擔

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

export class ChineseConversionRule implements IRule {
  private baseConverter: ConvertText
  private customConverter: ConvertText
  private readonly protectedChars = ['台']  // 統一管理

  // ... constructor

apply(text: string): string {
  return this.pipe(
    text,
    // 1. 標記階段：將需要保護的字符標記為不轉換
    this.markProtectedChars,
    
    // 2. 轉換階段：使用 OpenCC 進行轉換
    this.baseConverter,
    
    // 3. 還原階段：將標記的字符還原為原始字符
    this.restoreProtectedChars,
    
    // 4. 使用自訂轉換器進行模糊字詞的修正
    this.customConverter
  )
}

  /**
   * 標記需要保護的字符
   */
  private markProtectedChars = (input: string): string => {
    return this.protectedChars.reduce((acc, c) => acc.replaceAll(c, `<<<${c}>>>`), input)
  }

  /**
   * 還原被標記的保護字符
   */
  private restoreProtectedChars = (input: string): string => {
    return this.protectedChars.reduce((acc, c) => {
      const convertedChar = this.baseConverter(c) // 例如：'台' -> '臺'
      return acc.replaceAll(`<<<${convertedChar}>>>`, c)
    }, input)
  }

重構成果

1. 簡潔性：主方法從 20 行縮減到 8 行
2. 可讀性：資料流向清晰，從上到下一目了然
3. 可測試性：每個步驟都是純函數，可以獨立測試
4. 可維護性：職責分離，邏輯集中管理
5. 函數式：無副作用，符合 FP 原則

效能考量

• 測試結果顯示功能完全正常，262 個測試案例全數通過，這是個大前提，沒有測試沒有重構
• 重構過程中沒有改變演算法複雜度
• Pipe 函數本身的開銷微乎其微

關於 Pipe 的選擇

在重構過程中考慮過使用現成的函式庫：

• Ramda：功能最完整的 FP 函式庫
• Lodash/fp：輕量級選擇
• fp-ts：型別安全的 FP 函式庫

最終選擇自製 pipe 函數的理由：

兩行程式碼，沒有多餘依賴，寫法完全貼合專案需求。

團隊看了就能用，不用再去學新的函式庫。

邏輯也很單純，後續維護起來相對輕鬆。

除非更大範圍的重複發生，不然不需要額外引用套件突增學習成本

1
2
3

private pipe<T>(value: T, ...fns: Array<(arg: T) => T>): T {
  return fns.reduce((acc, fn) => fn(acc), value)
}

RD 反饋

這次重構讓我深刻體會到函數式程式設計的優雅之處：

1. 資料即流水線：透過 pipe 讓資料在各個函數間流動
2. 純函數的威力：每個步驟都可預測、可測試
3. 組合勝過繼承：透過函數組合建構複雜邏輯
4. 漸進式重構：一步步改善，降低風險

從命令式到函數式的重構不僅讓程式碼變得更優雅，也提升了整體的可維護性。

雖然函數式程式設計有一定的學習曲線，但一旦掌握了基本概念，就能寫出更簡潔、更易懂的程式碼。

重構的關鍵在於：小步快跑，持續改善。每一次小的改進都讓程式碼朝著更好的方向發展，這正是軟體工藝精神的體現。

小結

嗯，小朋友很會用 AI 寫作文呢。

(fin)

前情提要

在實作強型別語言，經常會遇到一些僅次於命名的問題：

到底要建立多少層級的 DTO/型別？

什麼時候該抽象，什麼時候該保持簡單？

這篇文章記錄一個前端要求帶來的反思，如何在「架構純粹性」與「實用主義」之間找到平衡點？

問題場景

系統架構為 TypeScript 並實作 Clean Architecture。

我們有一個比對系統，Domain Entity 中的 statusCode 定義為 string | null，

但前端要求 API 必須回傳 string 型別，允許空字串而不處理 null。

1
2
3
4
5
6
7
8
9

// Domain Entity
export class Comparison {
  statusCode: string | null  // 業務邏輯：可能為空
}

// 前端期望的 API 回應
{
  "statusCode": ""  // 必須是 string，不能是 null
}

解決方案演進

第一版：UseCase 層建立完整 DTO

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// 建立回應 DTO
export interface ComparisonResponseDTO {
  id: string
  statusCode: string  // 轉換為 string
  // ... 其他欄位
}

// 建立 UseCase 回應型別
export type GetComparisonListResDTO = IDataAndCount<ComparisonResponseDTO>

// UseCase 中處理轉換
private toResponseDTO(comparison: Comparison): ComparisonResponseDTO {
  return {
    // ...
    statusCode: comparison.statusCode || '',
    // ...
  }
}

看起來很「Clean Architecture」，但真的有必要嗎？

關鍵觀點，有沒有可能過度設計了？

最終方案：Controller 邊界處理

1
2
3
4
5
6
7
8
9
10
11
12

// Controller 直接處理轉換
async getComparisonList(req: Request, res: Response): Promise<void> {
  const { data, count } = await this.getComparisonListUseCase.execute(input)
  
  res.status(200).json({
    data: data.map(comparison => ({
      ...comparison,
      statusCode: comparison.statusCode || ''
    })),
    pagination
  })
}

避免型別地獄的原則

1. YAGNI 原則 (You Aren’t Gonna Need It)

不要為了「完整性」而建立無意義的型別包裝

或是建立過多的 Mapper 類別

1
2
3
4
5

// ❌ 過度抽象
export type GetComparisonListResDTO = IDataAndCount<ComparisonResponseDTO>

// ✅ 直接使用泛型
IUseCase<GetComparisonListReqDTO, IDataAndCount<ComparisonResponseDTO>>

2. 什麼時候需要抽象化？

我的判斷，重複的時候，例如，當 2 個以上的 API 需要相同的型別時，才考慮抽象

也不排除可以能轉換極度複雜，這時有一個 Mapper 的導入反而可以減輕負擔時才導入。

架構／Design Pattern 應該服務 RD 而不是折摩 RD

1
2
3
4
5
6
7
8

// 如果只有一個 API 使用，直接 inline
data.map(item => ({ ...item, statusCode: item.statusCode || '' }))

// 如果多個 API 都需要，才建立共用函數或型別
const transformComparison = (item: Comparison) => ({
  ...item,
  statusCode: item.statusCode || ''
})

3. 複雜度評估

簡單的轉換邏輯不需要額外抽象：

1
2
3
4
5
6
7

// ✅ 簡單轉換，直接處理
statusCode: comparison.statusCode || ''

// ❌ 為簡單邏輯建立複雜抽象
private transformStatusCode(statusCode: string | null): string {
  return statusCode || ''
}

實用主義 vs 理論完美

現代 TypeScript 最佳實踐

1. 直接使用泛型 - 避免不必要的 type alias
2. 減少型別層級 - 除非有明確的業務意義
3. 保持簡潔 - 不為了「完整性」而建立無意義的包裝

架構決策的平衡點

進階判斷：何時需要抽象，何時保持簡單？

小結

Clean Architecture 的精神是將商業邏輯集中在核心，邊界負責格式適配。

不要被「層級完整性」綁架，重點是：

1. Domain 保持純粹 - 反映真實的業務狀態
2. UseCase 專注邏輯 - 編排業務流程，不處理格式
3. Controller 處理邊界 - HTTP 格式轉換在此進行
4. 實用主義優先 - 簡單的需求用簡單的方法

記住：改動越少越好，沒有必要就不要建一大堆型別。

架構是為了解決問題，不是為了展示理論知識。當實用主義與理論衝突時，選擇能讓團隊更有生產力的方案。

(fin)

前情提要

專案需要使用 PaddleOCR 進行文字辨識，但原始模型檔案需要從 PaddlePaddle 框架轉換成 ONNX 格式才能在不同環境中使用。

轉換完成後，面臨一個選擇：這些模型檔案要怎麼發布？放在專案內部？還是公開分享？

經過一番討論，決定將轉換後的 ONNX 模型公開發布到 Hugging Face Hub，一方面解決內部使用需求，另一方面也讓社群受益。

這篇記錄整個發布流程的實作過程與踩雷經驗。

目標

• 將 5 個 PaddleOCR ONNX 模型檔案 (208MB) 發布到 Hugging Face
• 建立完整的使用文檔與授權聲明
• 提供簡單的下載方式給其他開發者
• 確保版權合規 (原始模型為 Apache 2.0 授權)

模型檔案清單

轉換完成的檔案包含：

• PP-OCRv5_server_det_infer.onnx (84MB) - 文字檢測
• PP-OCRv5_server_rec_infer.onnx (81MB) - 文字識別
• UVDoc_infer.onnx (30MB) - 文檔矯正
• PP-LCNet_x1_0_doc_ori_infer.onnx (6.5MB) - 文檔方向
• PP-LCNet_x1_0_textline_ori_infer.onnx (6.5MB) - 文字方向
• PP-OCRv5_server_rec_infer.yml (145KB) - 配置檔案

平台選擇：為什麼是 Hugging Face？

本來考慮幾個選項：

• GitLab：現有平台，整合容易
• GitHub：開發者友好，但大檔案處理麻煩
• Hugging Face：AI 模型專業平台

最終選擇 Hugging Face 的原因：

• ✅ 完全免費，50GB 額度綽綽有餘
• ✅ 原生支援 ONNX 格式
• ✅ 內建 Git LFS，大檔案處理無痛
• ✅ 全球 CDN，下載速度快
• ✅ 社群友好，可能吸引貢獻者

實作過程

Phase 1: 準備階段

首先建立 Hugging Face 帳號並設定環境：

1
2
3
4
5

# 安裝 HF CLI
uv add huggingface_hub

# 設定 Token (需要 Write 權限)
export HF_TOKEN="your_token_here"

建立模型 Repository：

1
2
3
4
5
6
7
8
9
10
11
12
13

from huggingface_hub import create_repo, whoami

# 驗證登入
user = whoami()
print(f"登入用戶: {user['name']}")

# 建立 repository  
repo_url = create_repo(
    repo_id="paddleocr-test",
    repo_type="model",
    private=False
)
print(f"Repository 建立成功: {repo_url}")

Phase 2: 上傳模型檔案

1
2

export HF_TOKEN=your_token
hf upload marsena/paddleocr-test ./model_cache/paddleocr_onnx/ --repo-type=model

實際上傳時間約 3 分鐘，比預期快很多。

Phase 3: 撰寫文檔

Hugging Face 的 README.md 比一般 GitHub 專案更重要，因為它就是模型的門面。

撰寫重點：

1. 清晰的模型說明：每個檔案的用途
2. 具體的使用範例：Python 程式碼示範
3. 完整的授權聲明：避免版權爭議
4. 技術細節：系統需求、相容性

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# PaddleOCR ONNX Models

本倉庫提供 PaddleOCR v5 的 ONNX 格式模型檔案...

## 快速開始

```python
from huggingface_hub import hf_hub_download

# 下載檢測模型
det_model = hf_hub_download(
    repo_id="marsena/paddleocr-test",
    filename="PP-OCRv5_server_det_infer.onnx"
)

需要注意 YAML metadata 的格式問題，HF 會檢查語法：

1
2
3
4
5
6
7
8

---
tags:
- onnx
- ocr  
- paddleocr
- computer-vision
license: apache-2.0
---

Phase 4: 測試驗證

上傳完成後務必測試下載功能：

1
2
3
4
5
6

# 測試單檔下載
hf download marsena/paddleocr-test PP-OCRv5_server_det_infer.onnx

# 測試整包下載
hf download marsena/paddleocr-test --local-dir ./test_download \
  --exclude "README.md" --exclude ".gitattributes"

一些要注意的小問題

HF Token 權限設定

• Read：只能下載
• Write：可以上傳模型
• Admin：可以刪除 repo

建立 token 時記得選擇 Write 權限。

Git LFS 檔案大小限制

Hugging Face 對單檔大小有限制：

• 一般檔案：< 10MB
• LFS 檔案：< 50GB

我們的最大檔案 84MB，自動走 LFS 沒問題。

背景上傳的重要性

大檔案上傳可能需要 10-30 分鐘，SSH 連線容易斷開。務必使用 nohup 或 screen。

README 的 YAML 語法檢查

Hugging Face 會檢查 YAML metadata 語法，格式錯誤會有警告（但不影響功能）。

使用方式

發布完成後，其他開發者可以這樣使用：

1
2
3
4
5

# 下載所有模型到專案目錄
hf download marsena/paddleocr-test \
  --local-dir ./model_cache/paddleocr_onnx \
  --exclude "README.md" \
  --exclude ".gitattributes"

或在 Python 中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

from huggingface_hub import hf_hub_download
import os

model_files = [
    "PP-OCRv5_server_det_infer.onnx",
    "PP-OCRv5_server_rec_infer.onnx", 
    "UVDoc_infer.onnx",
    "PP-LCNet_x1_0_doc_ori_infer.onnx",
    "PP-LCNet_x1_0_textline_ori_infer.onnx",
    "PP-OCRv5_server_rec_infer.yml"
]

cache_dir = "model_cache/paddleocr_onnx"
os.makedirs(cache_dir, exist_ok=True)

for file in model_files:
    hf_hub_download(
        repo_id="marsena/paddleocr-test",
        filename=file,
        local_dir=cache_dir
    )

小結

整個發布流程花費約 5-8 小時：

• 準備和上傳：2 小時
• 文檔撰寫：3 小時
• 系統整合：2 小時
• 測試驗證：1 小時

Hugging Face Hub 確實是發布 AI 模型的好選擇，特別是：

1. 無痛 LFS：大檔案處理完全自動化
2. 全球加速：下載速度比自建服務快
3. 社群生態：容易被發現和使用
4. 版本控制：Git-based，開發者熟悉

如果你也有 ONNX 模型需要分享，不妨考慮 Hugging Face Hub。畢竟專業的事交給專業的平台來做，我們專注在模型本身就好。

參考連結

• 發布的模型
• Hugging Face 文檔
• PaddleOCR 原始專案

(fin)

前情提要

在開發 AI 應用時，我們遇到一些特殊的依賴管理需求，需要私有 Registry

在這個專案中，我們遇到了幾個挑戰：

1. 平台特化需求：Jetson 平台需要特製的 onnxruntime-gpu 版本，PyPI 上沒有現成的
2. 版本一致性：確保所有環境（開發、測試、生產）使用完全相同的依賴版本
3. 安全性考量：避免依賴外部不穩定的來源，降低供應鏈攻擊風險
4. 內部套件分發：團隊開發的內部工具需要有管道分發

私有 Registry 運作流程

私有 Package Registry 的運作包含三個階段：

1. 套件發布階段
   開發者 → 推送程式碼 → GitLab CI/CD → 構建套件 → 推送至 Package Registry

2. 套件管理階段
   Package Registry ← 特製版本套件（如 onnxruntime-gpu for Jetson）
   　　　　　　　　　← 內部工具套件
   　　　　　　　　　← 安全審核過的第三方套件

3. 套件使用階段
   專案 pyproject.toml → 指定私有來源 → 安裝依賴 → 取得正確版本

這樣確保所有環境都使用一致且可控的套件版本。

實作步驟

發佈套件到 GitLab Package Registry

在設定和使用私有 Registry 之前，我們需要先將套件上傳到 GitLab Package Registry。

使用 twine 上傳套件

twine 是 Python 官方推薦的套件上傳工具，會自動從 wheel 檔案中提取 metadata：

1
2
3
4
5
6
7
8

# 安裝 twine
pip install twine

# 上傳到 GitLab PyPI registry
twine upload --repository-url https://gitlab.com/api/v4/projects/{PROJECT_ID}/packages/pypi \
             --username gitlab+deploy-token-{TOKEN_ID} \
             --password {TOKEN} \
             your_package.whl

實際範例（以 ONNX Runtime 為例）：

1
2
3
4

twine upload --repository-url https://gitlab.com/api/v4/projects/70410750/packages/pypi \
             --username gitlab+deploy-token-9097451 \
             --password gldt-tQVwLxzydZBhn3WWnwtt \
             onnxruntime_gpu-1.23.0-cp310-cp310-linux_aarch64.whl

設定 GitLab Package Registry

首先，在 GitLab 專案中啟用 Package Registry，並建立 Deploy Token：

在 GitLab 專案設定中建立 Deploy Token, Settings → Repository → Deploy Tokens

權限：read_package_registry, write_package_registry

記下 token ID 和 token 值，格式如下：

• Token ID: deploy-token-{ID}

• Token: {TOKEN}

取得 Project ID

有三種方式可以找到 GitLab Project ID：

從專案首頁：

進入你的 GitLab 專案首頁
Project ID 會顯示在專案名稱下方
例如：Project ID: 12345678

從專案設定頁面：

進入 Settings → General
在最上方的 “General project settings” 區塊
可以看到 Project ID

從 GitLab API：

如果你在 CI/CD pipeline 中，可以直接使用環境變數 $CI_PROJECT_ID
這個變數會自動帶入當前專案的 ID

配置專案的依賴管理

在 pyproject.toml 中設定私有 registry：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 定義私有 index
[[tool.uv.index]]
name = "onnx"
url = "https://gitlab+deploy-token-{TOKEN_ID}:{TOKEN}@gitlab.com/api/v4/projects/{PROJECT_ID}/packages/pypi/simple"
default = false

# 指定套件來源
[tool.uv.sources]
onnxruntime-gpu = { index = "onnx" }

# 多平台依賴策略
dependencies = [
    # macOS ARM64 使用 CPU 版本
    "onnxruntime==1.19.0; sys_platform == 'darwin' and platform_machine == 'arm64'",
    # Jetson 使用私有倉庫的 GPU 版本
    "onnxruntime-gpu; sys_platform == 'linux' and platform_machine == 'aarch64'",
]

這裡的關鍵是使用條件依賴，根據不同平台安裝不同版本的套件。

開發者使用私有 Registry

根據專案的安全策略，RD 有幾種方式存取私有 registry：

選項 1：Token 內嵌在 pyproject.toml（簡單但不安全）

如果 pyproject.toml 中已經包含完整的認證 URL：

1
2
3
4
5

# 直接安裝依賴
uv sync

# 或使用 pip
pip install -e .

選項 2：使用環境變數（推薦）

在 pyproject.toml 中使用佔位符：

1

url = "https://deploy-token-{TOKEN_ID}:${GITLAB_TOKEN}@gitlab.com/api/v4/projects/{PROJECT_ID}/packages/pypi/simple"

RD 需要設定環境變數：

1
2

export GITLAB_TOKEN=your_deploy_token
uv sync

選項 3：使用認證檔案

設定 pip 或 uv 的認證檔案：

1
2
3
4
5

# 建立 pip 配置
cat > ~/.pip/pip.conf <<EOF
[global]
extra-index-url = https://deploy-token-{TOKEN_ID}:{TOKEN}@gitlab.com/api/v4/projects/{PROJECT_ID}/packages/pypi/simple
EOF

選項 4：企業內網存取

如果使用企業內網或 VPN：

1
2

# 連接 VPN 後直接使用
uv sync

CI/CD 中存取私有 Registry

專案在 GitLab CI/CD 中需要存取私有 Registry 時，有以下幾種方式：

方法 1：使用 CI_JOB_TOKEN（推薦）

1
2
3
4
5
6
7
8
9
10

# .gitlab-ci.yml
variables:
  PIP_INDEX_URL: https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/api/v4/projects/${REGISTRY_PROJECT_ID}/packages/pypi/simple
  PIP_EXTRA_INDEX_URL: https://pypi.org/simple

build:
  stage: build
  script:
    - pip install -e .
    - # 其他構建步驟

方法 2：使用 Deploy Token

在 CI/CD 變數中設定 GITLAB_DEPLOY_TOKEN：

1
2
3
4
5

build:
  stage: build
  script:
    - export PIP_INDEX_URL="https://deploy-token-{TOKEN_ID}:${GITLAB_DEPLOY_TOKEN}@gitlab.com/api/v4/projects/${REGISTRY_PROJECT_ID}/packages/pypi/simple"
    - pip install -e .

方法 3：配合 uv 使用

1
2
3
4
5
6
7

build:
  stage: build
  before_script:
    - export GITLAB_TOKEN=${CI_JOB_TOKEN}
  script:
    - uv sync
    - # 其他構建步驟

常見問題與解決方案

Deploy Token 權限不足？

確保 Deploy Token 有 read_package_registry 和 write_package_registry 權限。

套件版本衝突？

使用 uv 的 resolution markers 功能，明確指定版本解析策略。

Registry URL 格式錯誤？

GitLab PyPI registry URL 格式為：

1

https://gitlab.com/api/v4/projects/{PROJECT_ID}/packages/pypi/simple

注意將 {PROJECT_ID} 替換為實際的專案 ID。

小結

透過建立私有 Package Registry，我們成功解決了：

• 特製版本管理：Jetson 平台的特殊 ONNX Runtime 版本需求
• 依賴一致性：所有環境使用相同版本的套件
• 安全性提升：減少對外部來源的依賴
• 存取便利性：開發者和 CI/CD 都能輕鬆存取私有套件

這個架構不僅適用於 ONNX Runtime，也可以擴展到其他需要特殊管理的依賴套件。

(fin)

前情提要

四年前「怎麼建立一個網站？(四) - 自訂網域 EMail」已過時了，
當時透過 Google Domain 設定了自己的網域信箱，那種擁有 [email protected] 的專業度真的是滿到溢出來。

但是，現實總是殘酷的。

2023 年 Google Domain 宣布停止營運，我選擇轉移到了 Cloudflare。

更悲劇的是，Gmail 的應用程式密碼也在安全性考量下越來越不被推薦使用。

Google 對 Gmail SMTP 的使用限制越來越嚴格。

在開啟 2FA 的情況下，只能使用應用程式密碼，但是 Google 本身也不推薦這樣使用密碼。

問題分析

現有問題：

• Google Domain 停止服務，Cloudflare 雖然接管了域名，但沒有提供類似的信箱轉發服務
• Gmail 無法繼續使用 Email Forwarding 的密碼方式不再被推薦使用，我也沒有查到替代方案

需求：

• 能夠使用 [email protected] 收信，已完成(在 Cloudflare 設定 Email Forwarding)
• 能夠以 [email protected] 寄信，而且不會被標記為可疑郵件
• 免費或便宜的解決方案
• 設定要簡單快速

技術選擇的思考

經過一番調研，我把目標鎖定在幾個主流的 SMTP 服務：

1. Brevo (原 Sendinblue)：免費額度每天 300 封信，付費方案 $25/月
2. Mailjet：免費額度每天 200 封信，付費方案 $17/月
3. SendGrid：免費額度每天 100 封信
4. Amazon SES：按量計費，超便宜但設定複雜

綜合考量下，我選擇 Brevo 的理由：

• 價格最划算：免費額度最高（300封/天），對個人使用綽綽有餘
• 功能完整：不只是 SMTP，還有完整的郵件行銷功能
• 設定超快：API 整合簡單，文件齊全
• 信譽良好：歐洲公司，GDPR 合規，信件到達率高

備案是 Mailjet，但既然 Brevo 實際使用很順利，我就沒有去試了。

實作過程

Step 1: 註冊 Brevo 帳號

前往 Brevo 官網 註冊免費帳號，過程很簡單，不需要信用卡。

可以用 Google 帳號註冊，但是填寫一些資料，總體來說並不冗長繁瑣。

Step 2: 設定 Sending Domain

登入後台，進入「Senders & IP」→「Domains」，添加你的域名（如 marsen.me）。

Brevo 會要求你在 DNS 域名設定中添加幾筆記錄(我是使用 Cloudflare)來驗證域名擁有權：

設定過程也很傻瓜點擊跟著操作就會引導你登入 Cloudflare 的後台，不保証其他域名商有這麼方便，

會在 Cloudflare DNS 管理中添加：2 筆 CNAME 與 2 筆 TXT 記錄，應該是讓 Brevo 驗証網域所有權的。

DNS 生效後，Brevo 就會驗證通過。

Step 3: 設定收信

設定 Email Forwarding 這部分我直接在 Cloudflare 設定：

「Email」→「Email Routing」→「Routes」

添加轉發規則：

從：[email protected] 到我的 gmail

這樣就能收到寄往自訂域名的信了。

Step 4: 設定 Gmail 使用 Brevo SMTP

進入 Gmail 設定 > 帳戶和匯入 > 新增另一個電子郵件地址：

• 名稱：Marsen
• 電子郵件地址：[email protected]
• SMTP 伺服器：smtp-relay.brevo.com
• 通訊埠：587
• 使用者名稱：你的 Brevo 帳號 email
• 密碼：去 Brevo 後台「Account Settings」→「SMTP & API」生成的 SMTP Key
• 設定完成後，Gmail 會寄驗證信，確認後收到的信才不會有警告。

實測結果

設定完成實測：

• ✅ 收信正常：寄到 [email protected] 的信都能在 Gmail 收到
• ✅ 寄信正常：從 Gmail 可以選擇用 [email protected] 寄信
• ✅ 信譽良好：收件者不會看到「未驗證」警告

整個設定過程不到 20 分鐘。

一些要注意的小問題

DNS 生效時間
SPF、DKIM 記錄可能需要幾個小時才會完全生效，不要急著測試。

但是我實測約幾分鐘就生效了。

SMTP Key 不是密碼
Brevo 的 SMTP Key 是專門給 API 和 SMTP 用的，不是你登入密碼。

免費額度限制
每天 300 封信對我個人使用很夠，但如果你要大量寄信，記得升級付費方案。

參考

• Brevo 官方網站
• 重要事項：我們不建議使用應用程式密碼
• 怎麼建立一個網站？(四) - 自訂網域 EMail (2020年舊文)

系列文章

• 怎麼建立一個網站？(一)
• 怎麼建立一個網站？(二)
• 怎麼建立一個網站？(三)
• 怎麼建立一個網站？(四)
• 怎麼建立一個網站？(四)
• 怎麼建立一個網站？(五)

(fin)

前情提要

最近在 Code Review 時遇到一個有趣的題目：

檔案上傳功能中，檔案編碼修復應該放在 Middleware 還是 UseCase？

這個問題引發了我對 Clean Architecture 分層職責的重新思考，與團隊背後的設計哲學。

問題背景

在一個採用 Clean Architecture 的專案中，我們有兩個檔案上傳功能：

• 知識庫檔案上傳 - 支援 PDF、Word、圖片等多種格式
• 合約檔案上傳 - 原始合約支援 PDF/Word，簽署後合約只支援 PDF

當前系統架構包含：

• Middleware - Express 中介軟體層
• Controller - HTTP 請求處理層
• UseCase - 業務邏輯層
• Service - 基礎設施服務層

核心問題：分層職責如何劃分？

以下邏輯應該放在哪一層？

1. 檔案編碼修復 - 解決中文檔名亂碼問題 (latin1 → utf8)
2. 檔案類型驗證 - 檢查 MIME type 是否符合業務需求
3. 檔案大小限制 - 根據不同業務場景設定不同大小限制
4. JWT Token 驗證 - 檢查使用者身份
5. 檔案內容解析 - 提取 PDF/Word 文件內容

分析思路 — 職責角度

Middleware 的職責：偏向基礎設施

控制進出流程 → 例：API 請求進來先檢查 Token

過濾與轉換資料 → 例：將日期字串轉成標準格式

保護系統邊界 → 例：攔截未授權的存取

以下不舉例:

• 跨領域技術問題 (認證、編碼、錯誤處理)
• HTTP 協議相關 (請求解析、回應格式)
• 基礎設施關注點 (日誌、監控、安全)
• 與業務無關的技術細節

Use Case 的職責：偏向商業邏輯

驅動核心行為 → 例：建立一筆訂單流程

執行業務規則 → 例：檢查庫存是否足夠

協調內外資源 → 例：呼叫付款服務並更新資料庫

以下不舉例:

• 特定業務場景的規則 (不同業務有不同檔案限制)
• 領域知識驗證 (合約標題、內容檢查)
• 業務流程邏輯 (檔案處理、資料儲存)
• 動態配置的業務參數 (從環境變數讀取的業務限制)

實際案例分析

檔案編碼問題

技術問題 → 整個系統一體適用，選 Middleware ✅

細節分析:

• 這是 HTTP 上傳過程中的技術問題，不是業務邏輯
• 所有檔案上傳都需要這個處理，跨多個 UseCase
• 屬於請求處理層面的責任

檔案類型限制

業務邏輯 → 不同的上傳任務有不同限制，屬商業邏輯，選 UseCase ✅

細節分析:

• 不同業務場景有不同的檔案類型限制
• 這是領域知識，需要業務邏輯判斷
• 可能隨著業務需求變化而調整

這頭給你想

如果檔案大小限制要動態調整呢？

總結

好的架構設計不是憑感覺，而是要有明確的原則：

• Middleware = 技術基礎設施，處理 HTTP 層面的問題
• UseCase = 業務邏輯驗證，處理領域相關的規則

這種分層不只讓程式碼更好維護，也讓測試更容易撰寫，更符合單一職責原則。

下次在設計架構時，不妨問問自己：

• 這個邏輯是技術問題還是業務問題？
• 這個規則會因為業務需求變化嗎？
• 這個處理邏輯需要在多個地方重複嗎？

Clean Architecture 的精神就在於：讓業務邏輯獨立於技術細節。

(fin)

前情提要

在 code review 中 RD 寫了以下的程式

1
2
3

if (!await this.exists(fullPath)) {
  await fs.promises.mkdir(fullPath, { recursive: true })
}

看似合理的「檢查然後執行」（Check-Then-Act）模式可能導致的併發問題。

假設兩個請求同時上傳檔案到同一個不存在的目錄：

1
2
3
4
5

時間線：
T1: 請求A 執行 this.exists(fullPath) → 返回 false (目錄不存在)
T2: 請求B 執行 this.exists(fullPath) → 返回 false (目錄不存在)
T3: 請求A 執行 mkdir(fullPath) → 成功建立目錄
T4: 請求B 執行 mkdir(fullPath) → 可能拋出 EEXIST 錯誤(fs.promises.mkdir 已在底層排除這個問題)

雖然使用了 recursive: true，那前面的檢查很可能是不必要的行為。

為什麼會這樣？

問題的根源在於時間窗口。兩個步驟之間存在時間差，而這個時間差就是競態條件的溫床：

1
2
3
4
5

// ❌ 有時間窗口的寫法
if (!await this.exists(fullPath)) {  // 步驟1: 檢查
  // 👆 這裡到下面之間就是危險的時間窗口
  await fs.promises.mkdir(fullPath, { recursive: true })  // 步驟2: 執行
}

解決方案

方法1: 直接使用 mkdir（推薦）

1
2
3
4
5
6
7
8

async uploadFile(file: UploadedFile, pathToStore?: `/${string}`): Promise<string> {
  const fullPath = `${this.uploadDir}${pathToStore ?? ''}`
  // 直接建立目錄，recursive: true 會自動處理已存在的情況
  await fs.promises.mkdir(fullPath, { recursive: true })
  const uploadPath = path.join(fullPath, file.originalName)
  await fs.promises.writeFile(uploadPath, file.buffer)
  return uploadPath
}

為什麼 recursive: true 已經足夠

根據 Node.js 官方文件，fs.promises.mkdir(path, { recursive: true }) 具有以下特性：

1. 自動建立父目錄：如果父目錄不存在會自動建立
2. 處理已存在目錄：當 recursive 為 true 時，如果目錄已存在不會拋出錯誤
3. 簡化錯誤處理：避免了手動檢查目錄是否存在的需要

官方範例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import { mkdir } from 'node:fs';

// Create ./tmp/a/apple, regardless of whether ./tmp and ./tmp/a exist.
mkdir('./tmp/a/apple', { recursive: true }, (err) => {
  if (err) throw err;
});

這就像餐廳點餐的差別：

```typescript
// ❌ 競態條件版本（不好的做法）
if (餐廳沒有準備我要的餐) {  // 檢查
  請廚師準備這道餐        // 執行
}
// 問題：兩個客人可能同時檢查到「沒有」，然後都要求準備

// ✅ 直接執行版本（好的做法）
請廚師準備這道餐，如果已經有了就不用重複準備
// 廚師會自己判斷是否需要準備，避免重複工作

效能優勢

修復後還有意外的效能提升：

1
2
3
4
5
6

// 修復前：2次系統調用
await this.exists(fullPath)  // 系統調用1: stat()
await fs.promises.mkdir()    // 系統調用2: mkdir()

// 修復後：1次系統調用  
await fs.promises.mkdir(fullPath, { recursive: true })  // 系統調用1: mkdir()

經驗教訓

1. 避免 Check-Then-Act 模式：這是併發程式設計的經典陷阱，不過這次案例，執行的底層實作已處理好，所以不會有問題
2. 信任系統調用：現代 API 通常已經考慮了併發場景
3. 簡單就是美：移除不必要的檢查邏輯，程式碼更簡潔也更安全

參考

• Nodejs - fsPromises.mkdir(path[, options])

(fin)

前情提要

最近購買 Claude Code，在此同時也有試用 Github Copilot / Gitlab Duo / Gemini / Amazon Q

剛好手上有需求，是簡單的 API 串接，但是我們的系統架構有一些只有團隊知道的 Know How。

我想試試用 AI Agent 來協助我處理這些開發，需求簡單明確，但是技術細節並不少，

如果是新進 RD(即使有開發經驗)也不見得能掌握得很好，我來試試看 AI Agent 能作什麼程度。

這篇文章記錄我在基於 Clean Architecture 的 Node.js API 系統中實作 Web Search 功能的完整過程，包含架構設計、權限管理、錯誤處理等細節。

系統架構背景

專案採用 Clean Architecture 搭配 依賴注入 (Inversify)，技術棧包含：

• TypeScript + Express.js
• TypeORM (資料庫 ORM)
• Inversify (依賴注入容器)
• JWT (身份驗證)
• Zod (參數驗證)

架構分為四個主要層級：

1
2
3
4
5

src/
├── adapters/          # 外部介面層 - 控制器
├── domain/           # 領域層 - 核心業務邏輯  
├── infrastructure/   # 基礎設施層 - 外部依賴實作  
└── useCases/        # 應用層 - 業務用例

需求分析與設計決策

API 規格定義

• 端點: GET /api/v1/websearch?keyword=關鍵字
• 輸入: Query 參數 { keyword: string }
• 輸出: { data: [{ title: string, url: string, description: string }] }
• 結果數: 10 筆
• 權限: 所有 API 都需要權限檢查(我們之前開發好的 RBAC 權限系統 )，一個功能對應一個權限，為此我需要新增 web_search 權限

關鍵設計決策

1. 控制器選擇

決定將功能放在 BasicController 而非 ProjController，因為這是通用功能而非特定業務邏輯。

| 這裡我在需求上有明確告知 AI，實作上也沒有問題

2. 依賴關係
嚴格遵循 Clean Architecture 的依賴規則：

| 也有寫入 CLAUDE.md 的開發準則中，但 AI 會常常忘記這件事

1

Controller → UseCase → Service → External API

3. 環境變數策略

將 Google API 設定為非必要欄位，未設定時警告但不中斷其他服務。

| AI 提供很好的建議並快速完成開發

4. 錯誤處理設計

• 503: API 未設定
• 502: API 呼叫失敗
• 400: 參數錯誤 (Zod 驗證)

實作步驟詳解

Phase 1: 環境設定擴充

首先擴充環境變數設定，新增 Google Search API 相關設定：

1
2
3
4
5
6

# .env.example
# Google Search API Configuration
GOOGLE_API_KEY=your_google_api_key
GOOGLE_SEARCH_ENGINE_ID=your_search_engine_id  
GOOGLE_SEARCH_API_URL=https://www.googleapis.com/customsearch/v1
GOOGLE_SEARCH_RESULTS_COUNT=10

修改 envConfigService.ts
新增 getOptional() 方法支援可選配置：

1
2
3

public getOptional(key: string): string | undefined {
  return process.env[key]
}

Phase 2: 權限系統整合

建立資料庫遷移檔案，新增 web_search 權限：

1
2
3
4
5
6
7

INSERT INTO permissions (name, description) VALUES 
('web_search', 'Web Search API access permission');

-- 分配給 admin 和 member 角色
INSERT INTO role_permissions (role_id, permission_id) 
SELECT r.id, p.id FROM roles r, permissions p 
WHERE r.name IN ('admin', 'member') AND p.name = 'web_search';

Phase 3: 核心架構實作

1. 定義領域介面

src/domain/interfaces/webSearchService.ts

1
2
3
4
5
6
7
8
9

export interface WebSearchService {
  search(keyword: string): Promise<WebSearchResult[]>
}

export interface WebSearchResult {
  title: string
  url: string  
  description: string
}

2. Google Search Service 實作

src/infrastructure/services/googleSearchService.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

@injectable()
export class GoogleSearchService implements WebSearchService {
  constructor(
    @inject(TYPES.HttpClient) private readonly httpClient: IHttpClient,
    @inject(TYPES.EnvConfigService) private readonly envConfig: IEnvConfigService
  ) {}

  async search(keyword: string): Promise<WebSearchResult[]> {
    const apiKey = this.envConfig.getOptional('GOOGLE_API_KEY')
    const searchEngineId = this.envConfig.getOptional('GOOGLE_SEARCH_ENGINE_ID')
    
    if (!apiKey || !searchEngineId) {
      throw new AppError('Google Search API 未設定', 503)
    }

    const params = {
      key: apiKey,
      cx: searchEngineId, 
      q: keyword,
      num: this.envConfig.get('GOOGLE_SEARCH_RESULTS_COUNT', '10')
    }

    try {
      const response = await this.httpClient.get(
        this.envConfig.get('GOOGLE_SEARCH_API_URL'), 
        { params }
      )
      return this.transformGoogleResponse(response.data)
    } catch (error) {
      throw new AppError('搜尋服務暫時無法使用', 502)
    }
  }

  private transformGoogleResponse(data: any): WebSearchResult[] {
    if (!data.items) return []
    
    return data.items.map((item: any) => ({
      title: item.title,
      url: item.link,
      description: item.snippet || ''
    }))
  }
}

3. UseCase 層實作

src/useCases/ExecuteWebSearch.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

@injectable()
export class ExecuteWebSearch implements IUseCase<ExecuteWebSearchDTO, WebSearchResponseDTO> {
  constructor(
    @inject(TYPES.WebSearchService) private readonly webSearchService: WebSearchService
  ) {}

  async execute(input: ExecuteWebSearchDTO): Promise<WebSearchResponseDTO> {
    const results = await this.webSearchService.search(input.keyword)
    return { data: results }
  }
}

// DTO 定義
export interface ExecuteWebSearchDTO {
  keyword: string
}

export interface WebSearchResponseDTO {
  data: WebSearchResult[]
}

4. Controller 層實作

src/adapters/controllers/basicController.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import { z } from 'zod'

// Zod 驗證 schema
const webSearchQuerySchema = z.object({
  keyword: z.string().min(1, 'keyword 參數為必填且不能為空字串')
})

async webSearch(req: Request, res: Response): Promise<void> {
  // 使用 Zod 進行參數驗證
  const { keyword } = webSearchQuerySchema.parse(req.query)
  
  const input: ExecuteWebSearchDTO = { keyword }
  const result = await this.executeWebSearch.execute(input)
  
  res.status(200).json(result)
}

5. 路由設定

src/infrastructure/routes/basicRouter.ts

1
2
3
4
5

// 註冊路由，先執行權限檢查，再執行業務邏輯
r.get(`${basePath}/websearch`, 
  auth.user('web_search'),  // 權限中介軟體
  asyncWrapper(basicController.webSearch.bind(basicController))
)

Phase 4: 依賴注入設定

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// inversify.config.ts
// 註冊 UseCase
container.bind<IUseCase<ExecuteWebSearchDTO, WebSearchResponseDTO>>(
  TYPES.ExecuteWebSearch
).to(ExecuteWebSearch)

// 註冊 Service
container.bind<WebSearchService>(
  TYPES.WebSearchService
).to(GoogleSearchService)

// 更新 TYPES 常數
export const TYPES = {
  // ... existing types
  ExecuteWebSearch: Symbol.for('ExecuteWebSearch'),
  WebSearchService: Symbol.for('WebSearchService'),
}

測試與驗證

準備測試環境 – 取得測試 Token

1
2
3
4

curl -X 'POST' 'http://localhost:4578/api/v1/auth/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"account": "test_act", "password": "test_pwd"}'

測試案例設計

| AI　會自動幫我跑 End To End 測試（本來是 RD 用curl 或 postman 進行的工作）
| 案例的設計上也很細心，很多 RD 是只測試 Happy Case 的

正常功能測試(happy case)

1
2
3

curl -X GET "http://localhost:4578/api/v1/websearch?keyword=nodejs" \
  -H "Authorization: Bearer <token>"
# 預期: Google 搜尋結果 JSON

權限檢查失敗測試

1
2

curl -X GET "http://localhost:4578/api/v1/websearch?keyword=test"
# 預期: {"error":"Authentication invalid"}

參數驗證測試

1
2
3
4
5
6
7
8
9

# 缺少參數
curl -X GET "http://localhost:4578/api/v1/websearch" \
  -H "Authorization: Bearer <token>"
# 預期: Zod 驗證錯誤，400 status

# 空參數
curl -X GET "http://localhost:4578/api/v1/websearch?keyword=" \
  -H "Authorization: Bearer <token>"
# 預期: {"error":[{...,"message":"keyword 參數為必填且不能為空字串"}]}

錯誤處理機制

Zod 驗證整合

專案已內建 Zod 在 req/res 檢查參數與錯誤處理有很好的表現，是團隊的開發工具之一
但要提醒 AI 不然他會手刻一個錯誤處理給你（刻得也不差就是了）

1
2
3
4
5
6
7

// errorHandler.ts 已支援
{
  type: ZodError,
  status: 400,
  log: 'Zod validation error',
  getMsg: (err: ZodError) => err.errors,
}

❌ 錯誤方式：AI 手刻錯誤處理

1
2
3
4

if (!keyword || typeof keyword !== 'string') {
  res.status(400).json({ error: 'keyword 參數為必填且必須是字串' })
  return
}

✅ 正確方式：使用 Zod

1

const { keyword } = webSearchQuerySchema.parse(req.query)

使用 Zod 的好處：

• 統一的錯誤格式
• 自動整合到全域錯誤處理器
• 型別安全保證

中介軟體執行順序

重構算是這次需求的大目標，只要提示詞寫得夠好 AI 可以提供很完整的路由列表
而且重構的狀態也很正確，不過我的專案不大只有 30 隻左右的 API 參加價值可能不高

1

請求 → auth.user('web_search') → asyncWrapper → zod.parse() → 業務邏輯

這個順序確保：

1. 先檢查身份權限
2. 再進行參數驗證
3. 最後執行業務邏輯

Google Custom Search API 整合要點

商業需求的主邏輯，我一行程式沒寫只與 AI 互動就完成了這個功能，包含點對點的測試
不過在零信任原則下，還是請其他 RD 再作一次 Code Review 與完整測試

必要參數說明

• key: Google API Key
• cx: Custom Search Engine ID
• q: 搜尋關鍵字
• num: 結果數量

API 回應轉換

Google API 回應結構：

1
2
3
4
5
6
7
8
9

{
  "items": [
    {
      "title": "搜尋結果標題",
      "link": "https://example.com",
      "snippet": "搜尋結果摘要"
    }
  ]
}

轉換為系統格式：

1
2
3
4
5
6
7
8
9

{
  "data": [
    {
      "title": "搜尋結果標題",
      "url": "https://example.com", 
      "description": "搜尋結果摘要"
    }
  ]
}

小結

這次實作讓我深度體驗了 AI 與優良架構在實際專案中的運用。幾個關鍵收穫：

架構優勢

• 清晰的分層讓職責分明，測試容易
• 依賴注入讓元件可抽換，符合開放封閉原則
• 統一的錯誤處理機制，維護成本低

上面是原本的優勢，加上 AI 判讀後，可以高效產生 Clean Code

不太確定不良代碼會有什麼結果，很幸運是我不在那種環境之中

現在三個圈圈是有交集的，好又快又便宜(產出／單位時間)，

依照 AI 帶來的生產力與現有的 RD 相比，其實是很便宜的選擇。

良好的設計結合工具(AI)是提昇效率的手段,

3 個人可以當 ７ 個人用。至於為什麼是３個人，有機會再說了。

(fin)