2. Go 环境搭建与项目初始化

本章是实战骨架的起点。你将完成 Go SDK 安装、工作区配置以及使用 go mod init 创建第一个模块化项目。正确的环境搭建能避免后续开发中 90% 的依赖与路径问题。

2.1 Go SDK 安装与版本选择

Go 官方维护两个主要版本线：Go 1.22.x（最新稳定版）与 Go 1.21.x（LTS 长期支持版）。本课程推荐使用 Go 1.22.2 或更高版本，以支持最新的 for range 整数循环与增强的 http.ServeMux 路由模式。

操作系统	安装方式	安装路径（默认）
macOS (Intel/Apple Silicon)	brew install go@1.22	/usr/local/go
Ubuntu/Debian	wget + tar -C /usr/local -xzf	/usr/local/go
Windows	MSI 安装包 / winget install Go	C:\Program Files\Go

2.2 GOPATH 与 Go Modules 配置

Go 的包管理经历了两个时代：GOPATH 模式（Go 1.11 之前）与 Go Modules 模式（Go 1.11+，Go 1.16 起默认启用）。本课程全程使用 Go Modules，你只需理解 GOPATH 的遗留概念即可。

特性	GOPATH 模式	Go Modules 模式
项目位置	必须放在 $GOPATH/src 下	任意目录
依赖版本	无版本概念（所有依赖拉取最新）	精确版本锁定（go.mod + go.sum）
环境变量	必须设置 GOPATH	可选设置 GOPATH（仅用于缓存）
推荐度	❌ 不推荐新项目使用	✅ 官方推荐

配置步骤（macOS/Linux 示例）：

1. 打开 ~/.zshrc 或 ~/.bashrc。
2. 添加以下环境变量：

export GOPATH=$HOME/go
export GOBIN=$GOPATH/bin
export PATH=$PATH:/usr/local/go/bin:$GOBIN

3. 执行 source ~/.zshrc 使配置生效。
4. 运行 go env GOPATH 确认输出为 /Users/你的用户名/go。

2.3 使用 go mod init 创建项目骨架

我们将创建一个名为 rate-limit-skeleton 的项目，作为后续限流、熔断与权限验证的载体。

步骤 1：创建项目目录并初始化模块

mkdir -p ~/projects/rate-limit-skeleton
cd ~/projects/rate-limit-skeleton
go mod init github.com/yourname/rate-limit-skeleton

执行后，目录下会生成 go.mod 文件，内容类似：

module github.com/yourname/rate-limit-skeleton

go 1.22.2

步骤 2：创建骨架目录结构

mkdir -p cmd/server
mkdir -p internal/middleware
mkdir -p internal/ratelimit
mkdir -p internal/circuitbreaker
mkdir -p internal/auth
mkdir -p pkg/config
mkdir -p pkg/logger

步骤 3：创建入口文件 cmd/server/main.go

package main

import "fmt"

func main() {
    fmt.Println("Rate Limit Skeleton starting...")
}

步骤 4：验证项目可编译

go build ./cmd/server/

如果编译成功且无报错，说明环境搭建与项目初始化全部完成。

2.4 验证环境与常见问题排查

完成上述步骤后，执行以下命令进行完整验证：

go version
go env GOPATH
go env GOMODCACHE
go build ./cmd/server/
./server

如果一切正常，终端应输出 Rate Limit Skeleton starting...。

常见错误	原因	解决方案
go: command not found	Go 未安装或 PATH 未配置	重新安装 SDK 并检查 /usr/local/go/bin 是否在 PATH 中
cannot find module providing package	go.mod 缺失或模块路径错误	确认在项目根目录执行 go mod init
package xxx is not in GOROOT	GOPATH 与 Go Modules 混用	设置 GO111MODULE=on 并确保项目不在 $GOPATH/src 下