zophos

← Notes · 28-入口要薄:領域邏輯別住在 main.md

入口要薄:領域邏輯別住在 main

程式的入口(main)是接線:解析參數、把東西建起來、啟動主迴圈。很容易順手把領域邏輯也丟進去——怎麼建一個 provider、設定檔在哪、某份衍生狀態怎麼同步。但接著,下層模組就會往上伸進 main 去拿這些東西。依賴箭頭指向了入口檔,方向反了。入口該是最薄的消費者,往下依賴領域模組;領域模組永遠不依賴 main。

main 是放「開機時發生的事」的地方,所以領域邏輯會慢慢黏上來。不知不覺,它同時還 host 了:怎麼建一個模型後端、認得哪些 provider 名字、怎麼把活的後端和設定調和、MCP 的設定檔讀寫……全都因為「開機要用到」。

一開始無害。問題在別人開始來拿。


氣味:下層模組往上伸手

當指令處理那層需要「這是不是一個認得的 provider?」「把後端和設定調和一下」「MCP 設定檔在哪?」——它就從 main import 這些。

一個模組,依賴著binary 的入口檔。

這是味道最濃的地方:依賴的箭頭應該指向穩定、被共用的東西,而 main 是光譜的另一端——它是最上層、最善變、最「這支程式專屬」的檔案。讓底下的模組反過來依賴它,等於把「最不該被依賴的東西」擺到了被依賴的位置。


修法:領域各自成模組

把那些領域邏輯搬出 main,各自成一個模組:

  • provider 的領域(認得的名字、建後端、後端↔設定的調和)→ 一個 provider 模組。
  • MCP 的設定(那個 mcp.json 檔、從 keyring 解析秘密)→ 一個 mcp 模組,跟「協定客戶端」那個 mcp(在另一個 crate 裡)分工清楚。

每個模組只往下依賴:資料層、核心。它們都不認得 main。而指令層和 main 現在都往下依賴這些模組。

          main  ─┐
                 ├─▶ provider / mcp (領域模組) ─▶ 資料、核心
       command ─┘

入口於是變回最薄的消費者

main 現在只剩接線:載入設定、把 harness 建起來、連好 MCP server、跑迴圈。它依賴那些領域模組,而沒有任何東西依賴 main。

這跟共用指令那篇是同一條原則的另一面:依賴朝內、指向抽象/領域,不指向善變的外層。那篇講的是把指令集從兩個前端裡反出來;這篇講的是別讓領域邏輯卡在入口檔被人往上拿。兩者都是在修「依賴指錯方向」。


怎麼察覺

有一個很好用的檢查:grep 你的模組有沒有 import 入口檔(main)裡的東西。如果有模組在 use crate::<某個住在 main 的函式>,那個函式就是在喊「我想要自己的模組」。入口檔該被依賴的次數是零。


總結

  1. main 會黏上領域邏輯。 因為開機在那裡發生,怎麼建後端、設定檔在哪都順手丟進去。

  2. 氣味是下層往上伸手。 模組 use crate::<main 裡的東西>——依賴指向了最上層、最善變的入口檔,方向反了。

  3. 領域各自成模組,依賴朝下。 provider、mcp 各一個模組,只依賴資料與核心;指令層和 main 都往下依賴它們(同共用指令的「依賴朝內」)。

  4. 入口是最薄的消費者。 main 只接線、依賴領域模組,而沒有東西依賴 main。用「有沒有模組 import 入口檔」來自檢。