Skip to content

元件形狀 · 七條正交軸線

與 blueprint 的關係:這七條軸線就是預設藍圖的 componentShape 資料。各軸線標註的初篩規則(max-paramsmax-statementsmax-lines)會進 lint config當作檢視入口;結論本身則轉譯進手冊與 AI Agent 守則。

元件與 composable 的形狀由七條軸線衡量。七條軸線構成「集合」,而非「流程」:彼此正交、各自獨立判斷 —— 不得以「符合第三條,故第一條自動成立」的方式推論。編號僅為識別用途,不代表順序;輕微的改動不必逐條套用。

本部分的檢查規則幾乎全數落於 ◐ 與 ○ 級 —— 元件形狀屬於設計判斷,此即信念第七條的體現。

1. 所有權反轉 —— 誰需要衍生狀態,誰自行持有

父元件不應預先計算後逐層傳遞 props;子元件應直接匯入 composable 或 hook 自行計算。實際案例:props 數量自 17 降至 7。

2. 介面收縮 —— 輸入收窄、輸出精簡

三種手法:拆分多重關注點;將帶有不變量的平行原始狀態收斂為單一建模狀態;將對稱的成對輸出收斂為同型物件。數量與大小僅為弱訊號;狀態是否經過建模方為審查的判斷重點。初篩規則:max-params

3. 單一職責拆分 —— 依責任邊界切分,而非依大小

命名檢驗法:不使用「和」便無法說清職責者,即應拆分。解散(將內容歸還各自的歸屬處)亦屬拆分的一種。例外:共用且必須同步的可寫狀態 —— 強行拆分將製造同步錯誤。初篩規則:max-statements

4. 協調層外殼 —— 頁面僅做協調

路由與識別碼解析、載入狀態外殼、共享資料來源、跨子元件的生命週期 —— 頁面不代替個別子元件計算衍生值。實際案例:明細頁自 6,666 行縮減至 552 行。初篩規則:max-lines(作用於 pages 層)。

5. 可寫狀態的作用域 —— 置於「寫入者與讀取者」的最近共同祖先

唯有確實跨界共享的可寫狀態才向上移動;需跨路由持續存在者,改置於網址查詢參數或狀態儲存庫。「未來可能共享」屬於過度設計 —— 確認需要共享時再行上提。

6. 生命週期內化 —— 生命週期屬於職責的一部分即應內建

呼叫端應取得「已啟動且會自行清理」的單元,而非自行接線 onMounted / useEffect。實際案例:19 個匯出項收斂為呼叫端的一行程式碼。

7. 純函式不等於 composable —— 純函式與響應式單元不得混置

「一個匯出函式」不等於「一個檔案」:責任的切分在函式層級進行,檔案的切分僅在接近 max-lines 門檻時進行。對外暴露的應是單元做成的決定,而非原料。


檢查與審查的分工(貫穿七條軸線):一個單元可能行數少、複雜度低、依賴數量少 —— 各項量測全數通過 —— 卻是原始狀態的傾倒場,或將衍生值存成可變參照;量測工具對此毫無所覺。檢查警告是審查的進場點,而非結論。