📚 课程目录第2章环境搭建与项目初始化

2. 环境搭建与项目初始化：Go语言环境配置、GinGo模块安装、使用命令行创建第一个GinGo项目

在开始《GinGo业务接口编排实战》之前，必须搭建一套干净、可复现的开发环境。本章将依次完成：Go语言环境配置、GinGo模块安装，以及通过命令行创建第一个GinGo项目。所有操作均基于macOS/Linux终端，Windows用户请使用Git Bash或WSL2。

2.1 Go语言环境配置

GinGo框架基于Go 1.21+，推荐使用Go 1.22或更高版本。请按以下步骤完成安装与验证。

2.1.1 下载与安装

访问 Go官方下载页面（https://go.dev/dl/），选择对应操作系统的安装包。
macOS用户推荐使用Homebrew：brew install go。
Linux用户下载tar包后解压至 /usr/local：sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz。
Windows用户直接运行MSI安装程序，默认路径 C:\Go。

2.1.2 环境变量配置

确保以下环境变量已正确设置：

变量名	推荐值	说明
`GOROOT`	`/usr/local/go` 或 `C:\Go`	Go安装根目录
`GOPATH`	`$HOME/go` 或 `%USERPROFILE%\go`	工作区目录，存放源码与依赖
`GOBIN`	`$GOPATH/bin`	编译后的可执行文件目录
`PATH`	追加 `$GOROOT/bin` 和 `$GOBIN`	使go命令全局可用

验证命令： 打开终端执行 go version，输出应类似 go version go1.22.5 darwin/amd64。再执行 go env GOPATH 确认工作区路径。

2.2 GinGo模块安装

GinGo采用Go Modules管理依赖，无需全局安装。每个项目独立引入GinGo模块。但为了加速后续项目创建，建议先拉取模块缓存。

2.2.1 设置Go代理（国内用户必选）

go env -w GOPROXY=https://goproxy.cn,direct
go env -w GO111MODULE=on

2.2.2 预拉取GinGo模块

mkdir -p $GOPATH/cache && cd $GOPATH/cache
go mod init cache
go get github.com/gingo/gingo@latest

此操作会将GinGo及其依赖下载至本地缓存，后续创建项目时无需重复下载。

2.3 使用命令行创建第一个GinGo项目

GinGo提供脚手架工具 gingo-cli，可快速生成项目骨架。以下是完整创建流程。

2.3.1 安装gingo-cli

go install github.com/gingo/gingo-cli@latest

安装完成后，执行 gingo-cli version 验证。

2.3.2 创建项目

gingo-cli new my-first-gingo
cd my-first-gingo

执行后，脚手架自动生成以下目录结构：

my-first-gingo/
├── cmd/
│   └── server/
│       └── main.go          # 应用入口
├── internal/
│   ├── handler/             # HTTP处理器
│   ├── service/             # 业务逻辑层
│   ├── repository/          # 数据访问层
│   └── model/               # 数据模型
├── config/
│   └── config.yaml          # 配置文件
├── api/
│   └── router.go            # 路由注册
├── go.mod
└── go.sum

2.3.3 启动项目

go run cmd/server/main.go

终端输出：

[GinGo] 2025/06/15 10:30:00 Server started on :8080
[GinGo] 2025/06/15 10:30:00 Swagger UI available at http://localhost:8080/swagger/index.html

访问 http://localhost:8080/health 应返回 {"status":"ok"}。

项目初始化流程图： 以下SVG展示了从环境配置到项目启动的完整链路。

2.4 项目结构详解

GinGo采用分层架构，各层职责清晰。下表列出核心目录及其作用：

目录/文件	职责	是否必须
`cmd/server/main.go`	应用入口，初始化配置、启动HTTP服务	是
`internal/handler/`	HTTP请求处理层，参数校验、响应组装	是
`internal/service/`	业务逻辑层，编排多个数据源或外部接口	是
`internal/repository/`	数据访问层，封装数据库或缓存操作	推荐
`internal/model/`	数据模型定义，包括请求/响应结构体	是
`config/config.yaml`	应用配置，如端口、数据库连接、日志级别	是
`api/router.go`	路由注册，将URL路径绑定到Handler	是

常见错误： 初学者常将业务逻辑直接写在handler中，导致handler臃肿且难以测试。请务必遵循 handler → service → repository 的调用链，保持各层单一职责。

2.5 验证开发环境

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

# 1. 确认Go版本
go version

# 2. 确认gingo-cli可用
gingo-cli version

# 3. 确认项目可编译
cd my-first-gingo
go build ./...

# 4. 确认服务可启动（后台运行）
go run cmd/server/main.go &
sleep 2
curl -s http://localhost:8080/health | grep "ok" && echo "SUCCESS" || echo "FAILED"

若输出 SUCCESS，则环境搭建与项目初始化全部完成。

2.6 环境配置速查表

以下表格汇总了关键配置项，方便快速排查问题：

检查项	命令	期望结果
Go版本	`go version`	≥ 1.21
模块模式	`go env GO111MODULE`	`on`
代理地址	`go env GOPROXY`	包含 `goproxy.cn` 或 `direct`
GinGo模块	`go list -m github.com/gingo/gingo`	显示版本号
CLI工具	`which gingo-cli`	返回路径，非 `not found`
服务端口	`lsof -i :8080`	显示 `server` 进程