5.1 KiB
5.1 KiB
🏛️ Cursor Rules: Go Kernel Mode 1.25.1
最高指導原則： 以 Linus Torvalds 的實用主義為核心，融合 Go 語言三巨頭 (Pike, Thompson, Griesemer) 的簡潔與併發哲學。
核心目標： 構建極致高效 (Performance-First)、極度簡潔 (Simplicity)、且完全受控 (Control) 的 Go 後端服務。
1. 最小化原則 (Minimization Principle)
核心：保持規模的簡潔、專注、易於理解。
| 規則 ID | 規則內容 (Go 實踐) | 哲學依據 |
|---|---|---|
| M1 | Stdlib-First： 強制優先 使用 Go 標準庫 (net/http, context, sync, io, database/sql)。任何外部依賴的引入必須有不可替代的理由。 |
Pike/Thompson： 簡潔與正交性。 |
| M2 | No-Fat-Frameworks： 禁止 使用大型、功能過載的 Web 框架。僅允許使用 Go 標準庫或極輕量的路由/工具庫 (如 go-chi/chi)，以維持對 性能瓶頸的完全控制。 |
Linus Torvalds： 實用與控制。 |
| M3 | Small Interfaces： 介面 (Interfaces) 必須 小且專一 (er 慣例，如 io.Reader)。介面應定義在使用者 (Consumer) 端，以促進模組間的低耦合。 |
Robert Griesemer： 語言設計的嚴謹。 |
| M4 | Explicit Errors： 錯誤處理必須使用 Go 慣用的多回傳值 (value, error) 模式。嚴禁 使用 panic 或 recover 來控制正常的業務流程錯誤。 |
Go 慣例： 錯誤是流程的一部分。 |
2. 結構化原則 (Structural Principle)
核心：使用分層架構管理職責邊界，促進可測試性和可維護性。
| 規則 ID | 規則內容 (Go 實踐) | 哲學依據 |
|---|---|---|
| S1 | Internal-First Layout： 核心業務邏輯必須放置在 internal/ 目錄中，不允許被外部專案直接導入。執行入口點必須在 cmd/{servicename}。 |
Griesemer/Go 慣例： 嚴謹的專案封裝。 |
| S2 | Clean Architecture Layers： 服務應至少分為 transport (I/O, 如 net/http Handler)、service (核心業務邏輯) 和 repository (數據存取)。層次間透過 介面 隔離。 |
Pike/Thompson： 關注點分離 (Separation of Concerns)。 |
| S3 | Concurrency Management： 併發操作 (如背景任務、Worker Pool) 必須明確使用 Goroutine 和 Channel 封裝。Goroutine 的生命週期 必須使用 context.Context 進行取消與超時控制。 |
Rob Pike： Go 併發模型的正確實踐。 |
| S4 | Config Isolation： 設定檔 (.env, 環境變數) 只能在 cmd 或專門的 config 套件中讀取。核心業務邏輯 (Service Layer) 絕不允許直接存取環境變數。 |
Linus Torvalds： 清晰的邊界控制。 |
3. 精準引用原則 (Precise Reference Principle)
核心：所有依賴必須顯式、高效、可追溯。
| 規則 ID | 規則內容 (Go 實踐) | 哲學依據 |
|---|---|---|
| P1 | Raw SQL Control： 數據層存取必須使用 原生 SQL 語句，並搭配 sqlx 或 sqlc 輔助。嚴禁 使用大型、會自動生成複雜查詢的 ORM，以確保對效能的完全控制。 |
Linus Torvalds： 控制數據流與效率。 |
| P2 | Dependency Injection (DI)： 所有依賴（例如 service 依賴 repository）必須通過 建構函式 (例如 NewUserService(repo Repository)) 顯式注入，避免使用全局變數。 |
Griesemer/Go 慣例： 顯式的依賴關係。 |
| P3 | I/O Context Passing： 任何涉及 I/O (網路、DB) 的函式，其第一個參數必須是 context.Context，以便傳播截止時間和取消訊號。 |
Go 慣例： 資源管理的標準。 |
| P4 | Structured Logging： 使用 log/slog 進行結構化日誌記錄。日誌中必須包含 Request ID 或 Trace ID，以實現 可觀察性 (Observability)。 |
Linus/實用主義： 快速診斷問題的能力。 |
4. 一致性原則 (Consistency Principle)
核心：保持專案的程式碼風格、命名方式、結構的統一，減少團隊摩擦。
| 規則 ID | 規則內容 (Go 實踐) | 哲學依據 |
|---|---|---|
| C1 | Mandatory Formatting： 所有提交的程式碼必須通過 gofmt 或 goimports 格式化。禁止 違反官方程式碼風格的程式碼。 |
Robert Griesemer： 語言設計的嚴謹性與工程規範。 |
| C2 | Go Naming Conventions： 變數和函式應簡短。未導出的私有成員使用小寫開頭。簡寫必須保持一致（如 HTTP 寫成 http，而非 Http）。 |
Rob Pike： 簡潔與慣例。 |
| C3 | Testing In-Package： 單元測試程式碼 (e.g., _test.go) 應與被測試程式碼保持在 同一套件，以實現對私有函式和變數的全面測試。 |
Linus/Go 慣例： 穩定性與可靠性。 |
| C4 | Go Modules & Version： 專案必須使用 Go Modules 進行依賴管理，並且針對 Go 1.25 版本進行編寫和測試。 | Linus/Griesemer： 版本控制的嚴格性與相容性。 |