Golang Gin 微服務架構開發規範

.cursorrules

# .cursorrules - Golang Gin 微服務架構開發規範 (v2.0)
# 最後更新時間: 2025-06-19

rules:

  # 專案結構與格式規範
  project_structure:
    - path: "**/*.go"
      formatter: gofumpt                # Go 程式碼格式化工具，保持風格一致性
      linter: golangci-lint             # Go 程式碼靜態檢查（推薦設定全部 recommended 規則）
      test_framework: testify           # Go 單元測試框架
      mock_framework: gomock            # Go Mock 框架，便於單元測試隔離外部依賴

    - path: "**/*.proto"
      formatter: buf                    # Protobuf 定義檔案格式化
      linter: buf lint                  # Protobuf 檔案語義檢查

    - path: "proto/**"
      generator: buf generate           # 透過 buf 自動生成 gRPC 與 Protobuf SDK

  # YAML 檔案配置規範
  yaml_configuration:
    - path: "**/*.yaml"
      formatter: prettier               # YAML 格式化工具，確保風格統一
      encrypted_sensitive_files:
        - local.yaml                    # 本地開發敏感資料
        - secret.yaml                   # 秘密檔案（如密碼、金鑰）
      encryption_tool: age              # 敏感檔案加密工具，需配合 git hook 確保提交前已加密

  # Docker 容器化規範
  containerization:
    - path: "Dockerfile"
      linter: hadolint                  # Dockerfile 最佳實踐檢查工具

  # Kubernetes 配置規範
  kubernetes:
    - path: "k8s/**"
      formatter: prettier               # Kubernetes YAML 檔案格式化工具
      deployment_tool: Helm v3          # 使用 Helm v3 管理多環境部署 (values overrides)
      secret_manager: External Secrets Operator (整合 GCP Secret Manager)

  # 基礎設施即程式碼規範
  infrastructure:
    - path: "infra/**"
      formatter: terraform fmt          # Terraform 檔案格式化
      linter: terraform validate        # Terraform 結構驗證

  # CI/CD 工作流程配置
  ci_cd:
    - path: ".github/workflows/**.yaml"
      formatter: prettier               # CI/CD 工作流 YAML 格式化
      workflow:
        build_and_test: GitHub Actions（單元與整合測試，自動觸發於 PR 與主分支 Push）
        container_image_push: GitHub Actions（容器映像推送至 GCP Artifact Registry）
        deployment: Argo CD（staging 環境自動部署，production 手動審核批准）

    - image_registry: GCP Artifact Registry
      security_scan_tool: Trivy         # 容器安全掃描，確保無漏洞映像進入生產環境

  # 相依套件自動更新
  dependencies:
    manager: Renovate                   # 自動管理與更新相依套件版本

  # 功能旗標管理
  feature_management:
    tool: Unleash                       # 功能開關管理

  # 程式碼品質與安全規範
  code_quality_and_security:
    code_quality:
      tool: SonarCloud                  # 程式碼品質分析平台
    security:
      xss_protection: bluemonday        # 跨站腳本攻擊（XSS）防護工具
      encryption_at_rest: 
        database_encryption: GCP Cloud SQL/CockroachDB Cloud's default encryption with CMEK (Customer-Managed Encryption Keys)
        secret_management: GCP Secret Manager # 用於管理應用程式密鑰，而非直接加密靜態資料

  # 觀察性（Observability）配置
  observability:
    logging:
      structured_logging: Zap           # 結構化日誌庫
      platform: Google Cloud Logging

    monitoring:
      platform: Google Cloud Monitoring # 基礎設施與應用效能監控

    tracing:
      platform: Google Cloud Trace
      sampling_rate: 0.1（10%）          # 初始採樣率 10%
      adaptive_sampling: true           # 根據流量與成本，動態調整採樣率，避免過度成本

    error_tracking:
      tool: Sentry                      # 錯誤追蹤與即時告警平台

  # 性能分析與除錯
  performance_and_debugging:
    profiling:
      tool: pprof                       # 性能分析工具 (Production 環境需嚴格存取控制)
    debugging:
      tool: Delve                       # Go 除錯工具 (僅限開發與 staging 使用)
    http_tracing:
      tool: net/http + httptrace        # HTTP 呼叫效能排查工具

  # 微服務通訊與事件管理
  communication_and_events:
    rpc_framework: gRPC                 # 微服務內部 RPC 通訊協定
    schema_management:
      tool: Buf Schema Registry         # Protobuf Schema 管理與註冊工具

    event_schema:
      specification: AsyncAPI, CloudEvents, Protobuf # 事件規格標準與格式

    event_stream:
      platform: NATS JetStream
      retry_and_dlq: true               # 重試機制與死信佇列支援

  # 資料管理規範
  data_management:
    database:
      primary: CockroachDB              # 主資料庫
      migration_tool: golang-migrate    # 資料庫 schema migration 工具
      sql_client: sqlc, pgxpool
      connection_pooling:               # 資料庫連線池建議配置
        max_conns: 100                  # 應根據負載測試結果調整
        min_conns: 10
        max_conn_lifetime: 1h
      distributed_lock:
        database: CockroachDB
        implementation_strategy:
          - 使用資料列鎖 (SELECT FOR UPDATE)
          - 租約模式 (Lease Pattern)
      operator:
        tool: CockroachDB Operator

    financial_accounting_database:
      database: TigerBeetle
      client: tigerbeetle-go                     # 官方 Go 客戶端
      use_case: >
        用於需要極高一致性與效能的金融級會計總帳 (Ledger) 系統，
        例如交易、餘額追蹤與雙邊記帳。
        不應用於通用資料儲存。
      schema_management: >
        透過 TigerBeetle 的原生格式定義帳戶 (Account) 與轉帳 (Transfer) 結構，
        並在應用程式啟動時進行初始化或驗證。不使用傳統 SQL migration。
      transaction_model: >
        原生支援兩階段提交 (Two-Phase Commit)，提供嚴格可序列化 (Strict Serializable) 隔離等級，
        確保金融交易的原子性與正確性。

    cache:
      tool: Redis Cluster
      client: go-redis
      consistency_strategy: Cache Aside (先更新資料庫，再刪除快取，以降低不一致風險)

    graph_database:
      database: Dgraph
      service: friendship-service

    search:
      engine: ElasticSearch             # 全文搜尋引擎

  # 彈性測試與穩定性規範
  resilience:
    chaos_engineering:
      tool: Chaos Mesh
      environments:
        - staging
        - pre-production
      production_usage_policy: 禁止直接使用於 production，除非經 SRE 團隊特批
    load_testing:
      tool: k6
      policy: >
        關鍵 API 需建立負載測試腳本，
        並在重大改版或上線前執行，
        確保符合預期的 TPS 與延遲指標。

  # API Gateway 與服務網格規範
  api_gateway_and_service_mesh:
    api_gateway:
      platform: Kong Gateway
      rate_limiting: true
      jwt_authentication:
        verification: Kong Gateway 使用 JWKS Endpoint (由 Authing 提供)
        failure_handling: 未授權請求回傳 HTTP 401，由 Auth Service 處理重新登入或續期

    service_mesh:
      platform: Kong Mesh
      circuit_breaker: true             # 自動服務斷路與重試機制

  # API 文件規範
  api_documentation:
    - standard: OpenAPI 3.0
      generation_tool: swag               # 透過 Go 註解自動生成
      ui: Swagger UI
      ci_cd_integration: 於 CI 流程中自動生成並驗證文件是否過期

  # 認證與授權規範
  authentication_and_authorization:
    authentication:
      provider: Authing                 # OAuth2 認證
      sms_verification: EngageLab       # 簡訊驗證
      jwt_handling:
        issuance_and_refresh: Auth Service 透過 Authing 管理 Refresh Token 流程
        blacklist_strategy: Redis 存儲 Token 黑名單，即時撤銷 Token

    authorization:
      tool: Open Policy Agent (OPA)     # 政策授權管理

  # 架構設計模式規範
  architecture_patterns:
    architecture:
      style: Domain-driven Design (DDD) # 領域驅動設計
      repository_pattern: true          # 資料存取抽象化
      cqrs: true                        # CQRS 模式 (僅適用於複雜或高效能讀取需求的領域，避免濫用)
      asynchronous_processing: Temporal # 非同步處理引擎

    transaction_management:
      pattern: Saga                     # 分散式交易模式
      orchestrator: Temporal            # 交易管理引擎
      compensation_policy: 明確定義每個步驟補償措施，考量冪等性
    
    dependency_injection:
      framework: Uber Fx                # 依賴注入框架，促進模組化與降低耦合性

    configuration_management:
      tool: Viper                       # 統一設定管理工具，負責 local.yaml 載入與管理

  # 即時通訊與語音規範
  realtime_and_voice:
    realtime_communication: Centrifugo
    voice_communication: Agora

  # 通知推播整合工具規範
  notification_integration:
    provider: EngageLab                        # 推播通知服務供應商
    integration_protocol: REST API             # 與 EngageLab 整合使用 REST API
    webhook_support: true                      # 支援 Webhook 回調通知，用以處理通知狀態追蹤
    authentication_method: Basic Auth          # 使用基本認證 (Basic Auth) 方式存取 EngageLab API
    sensitive_config_storage: GCP Secret Manager # API 金鑰等敏感資訊統一存放於 GCP Secret Manager

  # CDN 規範
  cdn:
    provider: Cloudflare

  # 本地開發環境設定
  local_development:
    go_modules: go.work                # 本地模組管理，避免 replace

  # 專案構建管理
  project_build_management:
    monorepo:
      tool: Pants                      # Monorepo 管理工具 (註：學習曲線較高，需確保團隊能力)

  # Go 語言版本規範
  golang_version:
    minimum: "1.22"                      # 最低支援版本
    recommendation: ">= 1.22"            # 建議使用的版本範圍
    features_used:
      - 原生錯誤包裝 (%w)                  # Go 1.13+ 提供原生錯誤包裝，更佳的錯誤追蹤能力
      - 泛型 (Generics)                   # Go 1.18+ 引入泛型，提升共用函式庫與資料結構複用性
      - workspace 模式 (go.work)          # Go 1.18+ 提供 workspace 模式，取代 replace 管理本地模組
      - context.WithCancelCause           # Go 1.20+ 提供更豐富的 context 取消原因

  # 版本控制與提交訊息規範
  version_control:
    git_commit_message:
      format: Conventional Commits       # 統一 Git commit 訊息格式，利於自動化與版本管理
  
  # 錯誤處理規範
  error_handling:
    standard:
      library: Go 原生 errors（fmt.Errorf + %w） # 使用 Go 原生錯誤包裝功能
      practice: >
        統一使用 Go 原生錯誤包裝方式（fmt.Errorf + %w），
        搭配 errors.Is 與 errors.As 判斷錯誤類型，便於處理與分類錯誤。
        錯誤堆疊追蹤與日誌則透過 Sentry 處理，
        無須自行實作額外的錯誤堆疊追蹤。