gosdk

gosdk

Go 語言通用開發工具包 (Shared SDK)，提供設定管理、HTTP 服務骨架、程式碼產生器、版本管理、通用通知、編碼轉換等可重用模組，作為 Go 專案的基礎函式庫使用。

本 repo 同時是 Claude Code plugin：除了作為 Go 函式庫被 import，也可安裝為 Claude Code plugin 取得 9 個 Go 專用 skills 與 golang-refactor agent。安裝方式見最下方 Claude Code Plugin.

業務領域 (Business Domains)

設定管理 (Configuration Management)

統一管理應用程式設定來源，支援 .env、YAML、JSON 及 embed.FS 四種格式，透過 Viper 實現階層式設定合併。各格式採用雙檔案載入模式：固定讀取 base 檔案（.env、config.yaml、settings.json），再合併同名 .local 覆寫檔（.env.local、config.local.yaml、settings.local.json），不再依賴 PROFILE 環境變數。同時支援 APP_ 前綴環境變數自動綁定。DB 連線另由獨立的 db 套件負責（見下一節），不在 config/ 範圍。

領域流程 (Domain Flow):

1. 呼叫 config.Default()（可加 WithAppName("myapp") 等 option）啟動設定載入；搜尋目錄固定為 .、./conf、~/.config/<appName>
2. EnvConfig.Load() 讀取 .env → .env.local 並合併至全域 Viper
3. YamlConfig.Load() 讀取 config.yaml → config.local.yaml 並合併至全域 Viper
4. JsonConfig.Load() 讀取 settings.json → settings.local.json 並合併至全域 Viper
5. 啟用 APP_ 前綴環境變數自動綁定（viper.AutomaticEnv()）
6. 下游模組透過 viper.GetString() 或 viper.Unmarshal() 取得設定值

核心實體 (Key Entities): Config 介面, EnvConfig, YamlConfig, JsonConfig, FSConfig

相關處理器 (Related Handlers): config.Default(), GetAppConfigDir(), WithAppName(), WithDefaultValue(), NewEnvConfig(), NewYamlConfig(), NewJsonConfig(), NewFSConfig()

---

資料庫連線 (Database Services)

每種儲存型態是一個獨立的 service:有自己的型別、自己的全域 singleton、自己的扁平 viper key (例如 SQLITE_PATH、MYSQL_DSN、POSTGRES_DSN)。micro-service 概念下,一個 process 內不應該存在兩個同型態的 service;InitSQLite() / InitMySQL() / InitPostgres() 在第二次呼叫時會回傳 error,守護 singleton 不變性。

領域流程 (Domain Flow):

1. config.Default() 載入設定後,呼叫端用 viper.IsSet("SQLITE_PATH") / viper.IsSet("MYSQL_DSN") / viper.IsSet("POSTGRES_DSN") 判斷是否啟用該儲存
2. 呼叫 db.InitSQLite() / db.InitMySQL() / db.InitPostgres() 從 viper 讀取設定、開啟連線、設為 singleton
3. 任何地方透過 db.DefaultSQLite.DB() / db.DefaultMySQL.DB() / db.DefaultPostgres.DB() 取得 *gorm.DB
4. 結束時呼叫 db.DefaultSQLite.Close() / db.DefaultMySQL.Close() / db.DefaultPostgres.Close() 釋放連線

核心實體 (Key Entities): Service 介面, SQLite struct, MySQL struct, Postgres struct, DefaultSQLite / DefaultMySQL / DefaultPostgres singleton

相關處理器 (Related Handlers): db.InitSQLite(), db.InitMySQL(), db.InitPostgres(), db.DefaultSQLite.DB(), db.DefaultSQLite.Close(), db.DefaultMySQL.DB(), db.DefaultMySQL.Close(), db.DefaultPostgres.DB(), db.DefaultPostgres.Close()

---

HTTP 服務 (HTTP Service)

基於 Gin 框架提供 HTTP 服務骨架，包含預設路由註冊、health check 端點、ping/pong 端點、stats 資訊端點，以及 Correlation ID 請求追蹤與 Helmet 安全性標頭中介層。設計為可嵌入其他 Go 專案的服務基礎模組。

領域流程 (Domain Flow):

1. main() 依序執行：config.Default() → log.Init() → 資料庫連線 → HTTPServer()
2. HTTPServer() 建立 gin.Default() 引擎，掛載 mw.CorrelationID() 與 mw.Helmet() 中介層
3. router.Default(s) 註冊 /stats 路由，回傳版本、Profile、設定檔路徑及 Correlation ID
4. router.HealthRouterGroup(s) 透過 gin-healthcheck 套件提供 /healthz 端點
5. router.PingRouterGroup(s) 提供 /ping/ 端點，回應 {"message": "pong"}
6. 伺服器監聽 server.host:server.port 設定值（預設 :8080）

核心實體 (Key Entities): Stats 結構, CorrelationHeader 常數

相關處理器 (Related Handlers): HTTPServer(), router.Default(), StatsHandler(), HealthRouterGroup(), PingRouterGroup(), mw.CorrelationID(), mw.GetCorrelationID(), mw.Helmet()

---

程式碼產生 (Code Generation)

提供兩個 CLI 工具：stringer 為增強版常數列舉產生器，從 Go AST 解析常數定義並自動產生 String()、List()、ValueList()、Map()、ValueMap() 五個方法；gotmpl 為模板渲染引擎，透過 Cobra CLI 讀取 YAML 設定，搭配 gomplate 函式庫渲染嵌入的 Go 模板。

領域流程 (Domain Flow) — stringer:

1. CLI 解析 -type、-output、-trimprefix、-linecomment、-tags 等參數
2. Generator.ParsePackage() 使用 golang.org/x/tools/go/packages 載入目標套件語法樹
3. File.GenDecl() 遍歷 AST 常數宣告，收集符合目標型別的 Value 清單
4. Generator.Generate() 根據連續序列數量選擇 buildOneRun / buildMultipleRuns / buildMap 策略產生 String() 方法
5. GeneratorEx.generate() 額外呼叫 buildListFn / buildValueListFn / buildMapFn / buildValueMapFn 產生四個輔助函式
6. Generator.Format() 格式化並輸出至指定檔案

領域流程 (Domain Flow) — gotmpl:

1. Cobra root command 解析 --config 參數，透過 Viper 讀取 YAML 設定
2. 設定反序列化為 TemplateLoader 結構
3. TemplateLoader.Load() 從 embed.FS 載入 .tmpl 模板
4. 使用 gomplate.CreateFuncs 提供進階模板函式進行渲染，輸出至 stdout

核心實體 (Key Entities): Generator, GeneratorEx, File, Package, Value, TemplateLoader

相關處理器 (Related Handlers): Generator.ParsePackage(), Generator.Generate(), GeneratorEx.generate(), SplitIntoRuns(), File.GenDecl(), TemplateLoader.Load()

---

版本管理 (Version Management)

提供 versioning CLI 工具，用於管理專案的語義版本號（Semantic Versioning）。從 version 檔案讀取與寫入版本資訊，支援 major、minor、patch 三個子命令分別遞增對應的版本號碼。設計為 CI/CD 流程中的版本自動化工具。

領域流程 (Domain Flow):