WORK STORY / 03

把 Folder Structure 提升成可執行規則

CONTEXT

情境

當 Repository、Shared Packages 與產品數量逐漸增加後，我開始遇到另一種問題。

即使大家都知道：

  • Component 應該放哪裡
  • Business Logic 應該在哪一層
  • Context、Hook、Service 各自負責什麼

不同工程師實作後，還是很容易形成不同的 Dependency Direction。

久了之後，Folder Structure 就只剩：

「檔案看起來放得很整齊」

但實際 Dependency 已經互相穿透。

例如 Component 直接碰 Service、底層模組反向依賴上層，甚至 Type Definition 放錯 Owner，都可能逐漸形成 Circular Dependency。

DECISION & ACTION

我的判斷與做法

所以我開始把 Folder Structure 從「資料夾命名規範」往 Architecture Rule 發展。

我重新定義各 Layer 的責任，例如：

  • pages
  • containers
  • components
  • hooks
  • contexts
  • services
  • utils

並進一步定義它們之間允許的 Import Direction。

例如 Component 不應直接取得 Service；Context、Hook、Container 各自只能從特定 Layer 取得能力；TypeScript Type 也必須有明確 Owner，而不是為了方便到處引用。

這些關係除了用文件與 Dependency Diagram 描述之外，也逐漸透過 ESLint Rule 約束 Import，讓架構規則不只是寫給人看的說明。

OUTCOME

形成的結果

Folder Structure 不再只是：

「這個檔案應該放在哪個 Folder？」

而開始回答：

「這個 Layer 應該知道哪些事情，又不應該知道哪些事情？」

團隊可以用同一套結構理解模組責任，也能在開發階段提早發現不合理的跨層 Dependency。

REFLECTION

留下的思考

這也是我後來一直延續的觀念：

如果一條工程規則真的重要，就不應該只存在文件裡。

文件適合解釋「為什麼」，但能由工具判斷的事情，最好由工具直接判斷。

否則規範最後還是會變成工程師必須靠記憶維持的一套默契。