60 lines
5.1 KiB
Markdown
60 lines
5.1 KiB
Markdown
# 🏛️ 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：** 版本控制的嚴格性與相容性。 |
|
||
|
||
---
|