網絡 (Net)

net 套件提供 HTTP 回應處理、並發檔案下載及常用指針輔助函數。

安裝

import "github.com/leoheung/go-patterns/net"

API 參考

並發下載

使用多個 Goroutine 進行分片下載，並自動追蹤進度。

// 使用 4 個併發數下載檔案到指定目錄
err := net.DownloadFileByConcurrent("https://example.com/file.zip", "./downloads/", 4)

流式下載

將任意 io.Reader 流式傳輸到 HTTP 回應，自動設置正確的標頭。支援固定大小和分塊傳輸模式。

// 已知檔案大小的流式下載
fileData := bytes.NewReader(fileBytes)
size := int64(len(fileBytes))
net.StreamDownloadHandler(w, fileData, "report.pdf", "application/pdf", &size)

// 未知檔案大小的流式下載（使用分塊傳輸）
s3Reader := getS3ObjectReader(key)
net.StreamDownloadHandler(w, s3Reader, "backup.zip", "application/zip", nil)

參數說明：

• w: HTTP ResponseWriter
• reader: 任意 io.Reader（檔案、記憶體緩衝、S3 物件等）
• filename: 顯示給用戶的下載檔案名稱
• contentType: MIME 類型（例如 "application/pdf", "application/octet-stream"）
• size: 檔案大小指標（可選，傳入 nil 則使用分塊傳輸）

WebSocket 管理器

高級 WebSocket 連接管理框架。詳見 WebSocket 文檔。

import "github.com/leoheung/go-patterns/net/wrapsocket"

// 創建 WebSocket Handler
handler := wrapsocket.NewDefaultHandler(nil)

// 設置回調
handler.SetOnConnect(func(conn *wrapsocket.Conn) {
    fmt.Printf("客戶端已連接: %s\n", conn.ID)
})

handler.SetOnMessage(func(conn *wrapsocket.Conn, msg *wrapsocket.Message) {
    // 回傳消息
    conn.Write(ctx, msg.Type, msg.Data)
})

http.ListenAndServe(":8080", handler)

特性：

• 連接生命週期管理
• 心跳檢測
• 分組廣播
• 元數據存儲

HTTP 回應工具

為 Web 服務提供標準化的 JSON 及 CSV 回應格式。

// 返回標準化的 JSON 成功回應
net.ReturnJsonResponse(w, http.StatusOK, map[string]string{"message": "success"})

// 返回標準化的 JSON 錯誤回應
net.ReturnErrorResponse(w, http.StatusBadRequest, "輸入無效")

// 返回 CSV 檔案下載回應
headers := []string{"ID", "姓名"}
rows := [][]string{{"1", "Alice"}, {"2", "Bob"}}
net.ReturnCSVResponse(w, "users.csv", headers, rows)

Chi 路由工具

// 打印 Chi 路由器中所有已註冊的路由
net.PrintCHIRoutes(r)

指針輔助函數

用於快速建立基本類型的指針（在處理資料庫模型的可選字段時非常有用）。

s := net.PtrString("hello")
i := net.PtrInt(100)
b := net.PtrBool(true)
t := net.PtrTime(time.Now())

完整範例

package main

import (
    "net/http"
    "github.com/go-chi/chi/v5"
    "github.com/leoheung/go-patterns/net"
)

func main() {
    r := chi.NewRouter()

    r.Get("/api/data", func(w http.ResponseWriter, r *http.Request) {
        data := struct {
            ID   int    `json:"id"`
            Name string `json:"name"`
        }{ID: 1, Name: "Pattern"}

        net.ReturnJsonResponse(w, http.StatusOK, data)
    })

    // 打印路由結構用於調試
    net.PrintCHIRoutes(r)

    // 在背景並發下載檔案
    go net.DownloadFileByConcurrent("https://example.com/large-file.bin", "./tmp/", 8)

    http.ListenAndServe(":8080", r)
}

特性

• 並發下載: 自動計算分片並支持斷點續傳邏輯（視服務端支持而定），自動提取原始文件名。
• 標準化回應: 統一的 UniversalResponse 結構，包含 isSuccess 標誌。
• 路由可視化: 方便地查看 Chi 路由器的層級結構與中間件。
• 類型指針化: 簡化 Go 中基本類型轉指針的操作。