@vincent119/go-copilot-rules 1.0.0

package/.agent_agy/skills/go-ci-tooling/SKILL.md

@@ -0,0 +1,533 @@
+---
+name: go-ci-tooling
+description: |
+  Go CI/CD 工具配置：Makefile、golangci-lint、GitHub Actions、Docker、測試覆蓋率、
+  自動化流程、Pre-commit Hook。
+
+  **適用場景**：設計 CI/CD Pipeline、配置 golangci-lint、撰寫 Makefile、
+  Docker 多階段建置、測試自動化、程式碼品質檢查、GitHub Actions。
+
+  **關鍵字**：ci/cd, makefile, golangci-lint, github actions, docker, pre-commit,
+  test coverage, lint, build automation, continuous integration, pipeline
+---
+
+# Go CI/CD 與工具配置規範
+
+> **相關 Skills**：本規範建議搭配 `go-testing-advanced`（測試）與 `go-graceful-shutdown`（建置）
+
+---
+
+## Makefile
+
+### 基本結構
+
+```makefile
+.PHONY: help
+help: ## 顯示此說明
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+# 變數
+BINARY_NAME=myapp
+VERSION?=dev
+COMMIT=$(shell git rev-parse --short HEAD)
+BUILD_TIME=$(shell date -u '+%Y-%m-%d_%H:%M:%S')
+
+# Go 變數
+GOBASE=$(shell pwd)
+GOBIN=$(GOBASE)/bin
+GOCMD=go
+GOBUILD=$(GOCMD) build
+GOTEST=$(GOCMD) test
+GOMOD=$(GOCMD) mod
+
+# Ldflags（注入版本資訊）
+LDFLAGS=-ldflags "-X main.Version=$(VERSION) -X main.Commit=$(COMMIT) -X main.BuildTime=$(BUILD_TIME)"
+
+.PHONY: build
+build: ## 建置二進位檔
+	@echo "Building $(BINARY_NAME)..."
+	$(GOBUILD) $(LDFLAGS) -o $(GOBIN)/$(BINARY_NAME) ./cmd/server
+
+.PHONY: test
+test: ## 執行單元測試
+	$(GOTEST) -v -race -coverprofile=coverage.out ./...
+
+.PHONY: test-coverage
+test-coverage: test ## 測試覆蓋率報告
+	$(GOCMD) tool cover -html=coverage.out -o coverage.html
+	@echo "Coverage report: coverage.html"
+
+.PHONY: lint
+lint: ## 執行 Linter
+	@which golangci-lint > /dev/null || (echo "Installing golangci-lint..." && go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest)
+	golangci-lint run --timeout=5m
+
+.PHONY: fmt
+fmt: ## 格式化程式碼
+	gofmt -s -w .
+	goimports -w .
+
+.PHONY: tidy
+tidy: ## 整理依賴
+	$(GOMOD) tidy
+	$(GOMOD) verify
+
+.PHONY: clean
+clean: ## 清理建置產物
+	@echo "Cleaning..."
+	@rm -rf $(GOBIN)
+	@rm -f coverage.out coverage.html
+
+.PHONY: docker-build
+docker-build: ## 建置 Docker Image
+	docker build -t $(BINARY_NAME):$(VERSION) .
+
+.PHONY: run
+run: build ## 執行應用程式
+	$(GOBIN)/$(BINARY_NAME)
+
+.PHONY: install-tools
+install-tools: ## 安裝開發工具
+	@echo "Installing development tools..."
+	go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+	go install golang.org/x/tools/cmd/goimports@latest
+	go install go.uber.org/mock/mockgen@latest
+
+.PHONY: generate
+generate: ## 執行 go generate
+	go generate ./...
+
+.PHONY: all
+all: tidy fmt lint test build ## 執行所有檢查與建置
+```
+
+### 進階：依賴追蹤
+
+```makefile
+# 只在原始碼變更時重新建置
+$(GOBIN)/$(BINARY_NAME): $(shell find . -name '*.go')
+	@echo "Source changed, rebuilding..."
+	$(GOBUILD) $(LDFLAGS) -o $@ ./cmd/server
+
+.PHONY: build
+build: $(GOBIN)/$(BINARY_NAME)
+```
+
+---
+
+## golangci-lint 配置
+
+### .golangci.yml
+
+```yaml
+run:
+  timeout: 5m
+  tests: true
+  skip-dirs:
+    - mocks
+    - vendor
+  skip-files:
+    - ".*\\.pb\\.go$"
+    - ".*_gen\\.go$"
+
+linters:
+  enable:
+    - errcheck       # 檢查未處理的錯誤
+    - gosimple       # 簡化程式碼
+    - govet          # Go vet
+    - ineffassign    # 檢測無效的賦值
+    - staticcheck    # 靜態分析
+    - typecheck      # 型別檢查
+    - unused         # 檢查未使用的變數
+    - gofmt          # 格式檢查
+    - goimports      # Import 排序
+    - misspell       # 拼寫檢查
+    - gocritic       # 程式碼評論
+    - godox          # 檢查 TODO/FIXME
+    - revive         # 取代 golint
+    - cyclop         # 循環複雜度
+    - dupl           # 重複程式碼檢測
+    - gosec          # 安全性檢查
+    - gocognit       # 認知複雜度
+    - nestif         # 巢狀 if 檢查
+    - prealloc       # Slice 預分配
+    - gci            # Import 排序
+    - lll            # 行長度檢查
+
+linters-settings:
+  errcheck:
+    check-blank: true
+    check-type-assertions: true
+
+  govet:
+    check-shadowing: true
+
+  gocognit:
+    min-complexity: 15
+
+  cyclop:
+    max-complexity: 15
+
+  lll:
+    line-length: 120
+
+  revive:
+    rules:
+      - name: exported
+        severity: warning
+      - name: unexported-return
+        severity: warning
+      - name: indent-error-flow
+        severity: warning
+
+  gosec:
+    excludes:
+      - G104  # 允許部分未檢查的錯誤（需有註釋）
+      - G304  # 允許檔案路徑來自變數
+
+issues:
+  exclude-rules:
+    # 測試檔案放寬限制
+    - path: _test\.go
+      linters:
+        - dupl
+        - gosec
+        - gocognit
+        - cyclop
+
+    # Mock 檔案不檢查
+    - path: mock/
+      linters:
+        - all
+
+  max-issues-per-linter: 50
+  max-same-issues: 3
+```
+
+---
+
+## GitHub Actions
+
+### .github/workflows/ci.yml
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: '1.21'
+          cache: true
+
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v3
+        with:
+          version: latest
+          args: --timeout=5m
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: testdb
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+
+      redis:
+        image: redis:7
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 6379:6379
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: '1.21'
+          cache: true
+
+      - name: Run tests
+        run: |
+          go test -v -race -coverprofile=coverage.out -covermode=atomic ./...
+        env:
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/testdb?sslmode=disable
+          REDIS_URL: redis://localhost:6379
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage.out
+          flags: unittests
+          fail_ci_if_error: true
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: '1.21'
+          cache: true
+
+      - name: Build
+        run: make build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: binary
+          path: bin/myapp
+```
+
+### .github/workflows/release.yml
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: '1.21'
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v4
+        with:
+          version: latest
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+---
+
+## Docker
+
+### Dockerfile（多階段建置）
+
+```dockerfile
+# Stage 1: Builder
+FROM golang:1.21-alpine AS builder
+
+# 安裝必要工具
+RUN apk add --no-cache git make
+
+WORKDIR /app
+
+# 複製 go.mod 和 go.sum（利用快取）
+COPY go.mod go.sum ./
+RUN go mod download
+
+# 複製原始碼
+COPY . .
+
+# 建置
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
+    go build -ldflags="-s -w" -o bin/myapp ./cmd/server
+
+# Stage 2: Runtime
+FROM alpine:latest
+
+# 安裝 CA 憑證與時區資料
+RUN apk --no-cache add ca-certificates tzdata
+
+WORKDIR /app
+
+# 複製二進位檔
+COPY --from=builder /app/bin/myapp .
+
+# 複製設定檔（可選）
+COPY ./configs ./configs
+
+# 建立非 root 使用者
+RUN addgroup -g 1000 appuser && \
+    adduser -D -u 1000 -G appuser appuser && \
+    chown -R appuser:appuser /app
+
+USER appuser
+
+EXPOSE 8080
+
+ENTRYPOINT ["./myapp"]
+```
+
+### .dockerignore
+
+```
+# Git
+.git
+.gitignore
+
+# IDE
+.vscode
+.idea
+*.swp
+
+# Build artifacts
+bin/
+coverage.out
+coverage.html
+
+# Docs
+docs/
+*.md
+
+# Tests
+*_test.go
+
+# Temp files
+tmp/
+*.log
+```
+
+---
+
+## Pre-commit Hook
+
+### .pre-commit-config.yaml
+
+```yaml
+repos:
+  - repo: https://github.com/golangci/golangci-lint
+    rev: v1.54.2
+    hooks:
+      - id: golangci-lint
+        args: ['--timeout=5m']
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+```
+
+### 安裝
+
+```bash
+# 安裝 pre-commit
+pip install pre-commit
+
+# 安裝 Hooks
+pre-commit install
+
+# 手動執行（所有檔案）
+pre-commit run --all-files
+```
+
+---
+
+## 測試覆蓋率
+
+### Coverage Badge（README）
+
+```markdown
+[![codecov](https://codecov.io/gh/username/repo/branch/main/graph/badge.svg)](https://codecov.io/gh/username/repo)
+```
+
+### 本地生成報告
+
+```bash
+# HTML 報告
+make test-coverage
+open coverage.html
+
+# 終端顯示
+go test -coverprofile=coverage.out ./...
+go tool cover -func=coverage.out
+
+# 按套件統計
+go test -coverprofile=coverage.out ./...
+go tool cover -func=coverage.out | grep -E '^total:'
+```
+
+---
+
+## 檢查清單
+
+**Makefile**
+- [ ] 包含 `help` 目標（自動生成說明）
+- [ ] 定義常用任務（build、test、lint、clean）
+- [ ] 注入版本資訊到二進位檔（Ldflags）
+- [ ] 支援依賴追蹤（原始碼變更時重建）
+
+**golangci-lint**
+- [ ] 配置 `.golangci.yml`
+- [ ] 啟用關鍵 Linter（errcheck、gosimple、staticcheck、gosec）
+- [ ] 設定合理的超時時間（5 分鐘）
+- [ ] 排除生成的程式碼（*.pb.go、mock/）
+
+**GitHub Actions**
+- [ ] CI Pipeline 包含 lint、test、build
+- [ ] 整合測試使用 Service Containers（Postgres、Redis）
+- [ ] 上傳測試覆蓋率到 Codecov
+- [ ] Release 自動化（GoReleaser）
+
+**Docker**
+- [ ] 使用多階段建置（減少映像大小）
+- [ ] 設定非 root 使用者
+- [ ] 利用建置快取（分離 go mod download）
+- [ ] 配置 `.dockerignore`
+
+**Pre-commit**
+- [ ] 安裝 `.pre-commit-config.yaml`
+- [ ] 執行 golangci-lint
+- [ ] 檢查檔案格式（trailing whitespace、EOF）
+- [ ] 防止提交大檔案
+
+**測試覆蓋率**
+- [ ] 目標覆蓋率 ≥ 80%
+- [ ] CI 自動檢查覆蓋率
+- [ ] 重要邏輯 100% 覆蓋
+- [ ] 生成 HTML 報告供查看