Installation - zhoudm1743/go-util GitHub Wiki

本指南将帮助您快速安装和配置 Go-Util，包括系统要求、安装方法、依赖管理和环境配置。

📋 系统要求

Go 版本要求

最低版本: Go 1.18+
推荐版本: Go 1.21+
最新测试: Go 1.23

# 检查 Go 版本
go version

# 输出示例：go version go1.21.0 linux/amd64

操作系统支持

Go-Util 支持所有 Go 支持的平台：

操作系统	架构	状态
Linux	amd64, arm64, 386	✅ 完全支持
macOS	amd64, arm64 (M1/M2)	✅ 完全支持
Windows	amd64, 386	✅ 完全支持
FreeBSD	amd64, arm64	✅ 支持

🚀 快速安装

方法 1: 安装核心包 (推荐)

# 安装 Go-Util 核心包
go get github.com/zhoudm1743/go-util

# 验证安装
go mod tidy

方法 2: 安装指定版本

# 安装最新稳定版本
go get github.com/zhoudm1743/go-util@latest

# 安装指定版本 (推荐生产环境)
go get github.com/zhoudm1743/[email protected]

# 安装预发布版本
go get github.com/zhoudm1743/go-util@main

方法 3: 独立包安装

# 只安装 JSONx 包
go get github.com/zhoudm1743/go-util/jsonx

# 只安装 JWT 包  
go get github.com/zhoudm1743/go-util/jwt

# 同时安装多个独立包
go get github.com/zhoudm1743/go-util/jsonx github.com/zhoudm1743/go-util/jwt

📦 依赖管理

Go Modules (推荐)

使用 Go Modules 管理依赖：

# 初始化新项目
mkdir my-go-project
cd my-go-project
go mod init my-go-project

# 添加 Go-Util 依赖
go get github.com/zhoudm1743/go-util

# 查看 go.mod 文件
cat go.mod

示例 go.mod 文件：

module my-go-project

go 1.21

require (
    github.com/zhoudm1743/go-util v1.4.0
    github.com/zhoudm1743/go-util/jsonx v0.0.0-20241215000000-000000000000
    github.com/zhoudm1743/go-util/jwt v0.0.0-20241215000000-000000000000
)

版本固定

生产环境建议固定版本：

# 固定到特定版本
go mod edit -require=github.com/zhoudm1743/[email protected]

# 更新到最新版本
go get -u github.com/zhoudm1743/go-util

# 查看可用版本
go list -m -versions github.com/zhoudm1743/go-util

依赖分析

# 查看依赖图
go mod graph | grep go-util

# 检查依赖健康状况
go mod verify

# 清理未使用的依赖
go mod tidy

🛠️ 项目配置

基础项目结构

推荐的项目结构：

my-project/
├── go.mod
├── go.sum
├── main.go
├── internal/
│   ├── config/
│   ├── handler/
│   └── service/
├── pkg/
│   └── utils/
└── cmd/
    └── server/

导入配置

在您的 Go 文件中导入：

package main

import (
    // 核心包
    util "github.com/zhoudm1743/go-util"
    
    // 独立包
    "github.com/zhoudm1743/go-util/jsonx"
    "github.com/zhoudm1743/go-util/jwt"
)

func main() {
    // 使用核心功能
    str := util.Str("hello_world").Snake2Camel().String()
    
    // 使用独立包
    j := jsonx.Object().Set("message", str)
    token, _ := jwt.GenerateHS256([]byte("secret"), jwt.MapClaims{"data": str})
    
    fmt.Printf("Result: %s, Token: %s\n", j.ToJSON(), token)
}

别名配置

推荐的导入别名：

import (
    // 简短别名
    util "github.com/zhoudm1743/go-util"
    "github.com/zhoudm1743/go-util/jsonx"
    "github.com/zhoudm1743/go-util/jwt"
    
    // 或者具体别名（避免冲突）
    goUtil "github.com/zhoudm1743/go-util"
    goJSON "github.com/zhoudm1743/go-util/jsonx"
    goJWT "github.com/zhoudm1743/go-util/jwt"
)

🐳 Docker 环境

Dockerfile 示例

FROM golang:1.21-alpine AS builder

WORKDIR /app

# 复制依赖文件
COPY go.mod go.sum ./

# 下载依赖
RUN go mod download

# 复制源码
COPY . .

# 编译应用
RUN CGO_ENABLED=0 GOOS=linux go build -o main .

# 运行镜像
FROM alpine:latest

RUN apk --no-cache add ca-certificates
WORKDIR /root/

COPY --from=builder /app/main .

CMD ["./main"]

Docker Compose

version: '3.8'

services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - GO_ENV=production
      - JWT_SECRET=your-jwt-secret-here
    volumes:
      - ./config:/app/config:ro

🔧 IDE 配置

VS Code

推荐的 VS Code 配置 (.vscode/settings.json)：

{
    "go.useLanguageServer": true,
    "go.languageServerFlags": ["-rpc.trace"],
    "go.lintTool": "golangci-lint",
    "go.formatTool": "goimports",
    "go.generateTestsFlags": ["-exported"],
    "editor.formatOnSave": true,
    "go.buildOnSave": "package",
    "go.vetOnSave": "package"
}

推荐扩展：

{
    "recommendations": [
        "golang.go",
        "ms-vscode.vscode-json",
        "redhat.vscode-yaml"
    ]
}

GoLand/IntelliJ

在 GoLand 中配置：

File → Settings → Go → Build Tags & Vendoring
- Build tags: json,jwt,enum
File → Settings → Go → Go Modules
- Enable Go modules integration: ✅
- Proxy: https://proxy.golang.org,direct

Vim/Neovim

使用 vim-go 插件配置：

" .vimrc 配置
let g:go_fmt_command = "goimports"
let g:go_autodetect_gopath = 1
let g:go_list_type = "quickfix"

let g:go_highlight_types = 1
let g:go_highlight_fields = 1
let g:go_highlight_functions = 1
let g:go_highlight_methods = 1

🌐 代理配置

中国用户配置

# 设置 Go 模块代理 (七牛云)
go env -w GOPROXY=https://goproxy.cn,direct

# 或者使用阿里云
go env -w GOPROXY=https://mirrors.aliyun.com/goproxy/,direct

# 设置私有模块跳过代理
go env -w GOPRIVATE=*.corp.example.com,rsc.io/private

企业环境配置

# 企业代理配置
export GOPROXY=https://your-company-proxy.com
export GONOPROXY=github.com/your-company/*
export GOSUMDB=off  # 如果使用内部模块

网络问题排查

# 测试网络连接
go env GOPROXY
curl -I https://proxy.golang.org

# 强制重新下载
go clean -modcache
go mod download

# 详细日志
GOPROXY=direct go get -v github.com/zhoudm1743/go-util

✅ 安装验证

基础验证

创建测试文件 test_install.go：

package main

import (
    "fmt"
    util "github.com/zhoudm1743/go-util"
    "github.com/zhoudm1743/go-util/jsonx"
    "github.com/zhoudm1743/go-util/jwt"
)

func main() {
    fmt.Println("🚀 Go-Util 安装验证")
    
    // 测试核心包
    fmt.Println("\n📦 核心包测试:")
    str := util.Str("hello_world").Snake2Camel().String()
    fmt.Printf("  字符串转换: hello_world → %s ✅\n", str)
    
    arr := util.Arrays(1, 2, 3, 4, 5).Filter(func(n int) bool { return n%2 == 0 })
    fmt.Printf("  数组过滤: [1,2,3,4,5] → %v ✅\n", arr.ToSlice())
    
    // 测试 JSONx
    fmt.Println("\n🚀 JSONx 包测试:")
    j := jsonx.Object().Set("name", "Go-Util").Set("version", "v1.4.0")
    jsonStr, _ := j.ToJSON()
    fmt.Printf("  JSON 创建: %s ✅\n", jsonStr)
    
    // 测试 JWT
    fmt.Println("\n🔐 JWT 包测试:")
    secret := []byte("test-secret")
    claims := jwt.MapClaims{"test": "data"}
    token, err := jwt.GenerateHS256(secret, claims)
    if err == nil {
        fmt.Printf("  JWT 生成: %s... ✅\n", token[:20])
    }
    
    fmt.Println("\n🎉 所有测试通过！Go-Util 安装成功！")
}

运行验证：

go run test_install.go

预期输出：

🚀 Go-Util 安装验证

📦 核心包测试:
  字符串转换: hello_world → HelloWorld ✅
  数组过滤: [1,2,3,4,5] → [2 4] ✅

🚀 JSONx 包测试:
  JSON 创建: {"name":"Go-Util","version":"v1.4.0"} ✅

🔐 JWT 包测试:
  JWT 生成: eyJhbGciOiJIUzI1NiIs... ✅

🎉 所有测试通过！Go-Util 安装成功！

性能基准验证

# 运行基准测试
go test -bench=. -benchmem github.com/zhoudm1743/go-util/...

# 检查特定功能性能
go test -bench=BenchmarkJSONx -benchmem github.com/zhoudm1743/go-util/jsonx

🔄 版本升级

升级到最新版本

# 升级核心包
go get -u github.com/zhoudm1743/go-util

# 升级独立包
go get -u github.com/zhoudm1743/go-util/jsonx
go get -u github.com/zhoudm1743/go-util/jwt

# 清理依赖
go mod tidy

版本回退

# 回退到指定版本
go mod edit -require=github.com/zhoudm1743/[email protected]
go mod download

# 验证版本
go list -m github.com/zhoudm1743/go-util

升级注意事项

# 检查变更日志
curl -s https://api.github.com/repos/zhoudm1743/go-util/releases/latest

# 测试兼容性
go test ./...

# 检查废弃警告
go vet ./...

🚨 常见问题

1. Go 版本过低

错误: package github.com/zhoudm1743/go-util: go.mod requires go >= 1.18

解决:

# 升级 Go 版本
# 访问 https://golang.org/dl/ 下载最新版本

# 或使用版本管理工具
# macOS (Homebrew)
brew install go

# Linux (使用 g)
curl -sSL https://git.io/g-install | sh -s
g install latest

2. 网络连接问题

错误: dial tcp: lookup proxy.golang.org: no such host

解决:

# 使用国内镜像
go env -w GOPROXY=https://goproxy.cn,direct

# 或直接从源码安装
go env -w GOPROXY=direct

3. 模块缓存问题

错误: verifying module: checksum mismatch

解决:

# 清理模块缓存
go clean -modcache

# 重新下载
go mod download
go mod verify

4. 导入路径错误

错误: package github.com/zhoudm1743/go-util/v2 is not in GOROOT

解决:

// ❌ 错误的导入
import "github.com/zhoudm1743/go-util/v2"

// ✅ 正确的导入
import "github.com/zhoudm1743/go-util"

5. 依赖冲突

错误: require github.com/zhoudm1743/go-util: version "v1.4.0" invalid

解决:

# 检查依赖冲突
go mod graph | grep go-util

# 强制更新
go get github.com/zhoudm1743/go-util@latest
go mod tidy

🎯 下一步

安装完成后，您可以：

🚀 快速开始 - 5分钟上手指南
📚 基础概念 - 了解核心理念
🚀 JSONx完整指南 - 学习JSON操作
🔐 JWT完整指南 - 掌握认证方案

💬 获取帮助

如果安装过程中遇到问题：

🔍 查看FAQ - 常见问题解答
🐛 报告问题 - GitHub Issues
💬 社区讨论 - 技术交流
📧 邮件支持 - [email protected]

🎉 恭喜！您已成功安装 Go-Util，开始您的高效 Go 开发之旅吧！