新手完成Go项目关键在于建立可落地的开发节奏：先用go mod初始化、net/http写基础服务、flag管理配置，再完成交叉编译、stdout日志、健康检查和SIGTERM信号处理。
Go 新手想从零开始完成一个完整项目，关键不在“学完所有语法”，而在建立可落地的开发节奏：用最小可行路径把需求跑通，再逐步加固。下面按真实协作场景中的典型流程拆解。
初始化项目并管理依赖用 go mod
别碰 GO111MODULE=off 时代的老习惯。新项目第一行命令必须是：
go mod init example.com/myapp
这会生成 go.mod 文件，并自动记录后续所有 go get 引入的依赖及其精确版本。常见错误包括：
- 在已有
go.mod的目录外执行go run main.go—— 会 fallback 到 GOPATH 模式，依赖行为不可控 - 手动编辑
go.sum—— 它是校验文件，应由go mod tidy自动维护 - 升级依赖只改
go.mod不运行go mod tidy—— 实际构建时可能拉不到对应版本
HTTP 服务起步：用 net/http 而非框架
新手过早引入 Gin / Echo 容易掩盖基础问题。先写一个能响应 JSON 的 main.go：
package main
import (
"encoding/json"
"log"
"net/http"
)
func handler(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
}
func main() {
http.HandleFunc("/health", handler)
log.Println("server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}
注意点：
-
http.ListenAndServe第二个参数为nil表示使用默认http.DefaultServeMux，够用 - 不要在 handler 里 panic 后直接返回 500 —— Go 默认会打印堆栈但不中断请求，需显式
http.Error或用中间件捕获 - 本地调试时用
curl -v http://localhost:8080/health看状态码和响应头，比浏览器更可靠
读配置：优先用 flag + 环境变量，别急着写 YAML 解析器
多数小项目只需控制端口、调试开关等几个参数。用标准库 flag 就够了：
package main
import (
"flag"
"log"
"net/http"
)
var (
port = flag.String("port", "8080", "server port")
debug = flag.Bool("debug", false, "enable debug mode")
)
func main() {
flag.Parse()
if *debug {
log.SetFlags(log.Lshortfile | log.LstdFlags)
}
http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
w.Write([]byte("OK"))
})
log.Printf("starting server on :%s", *port)
log.Fatal(http.ListenAndServe(":"+*port, nil))
}
启动方式：
go run main.go -port 3000 -debug-
PORT=3000 go run main.go（需代码中加os.Getenv("PORT")fallback）
别一上来就集成 viper —— 它解决的是多环境、多格式、热加载等复杂场景，新手项目反而因配置层级太深导致改了不生效。
部署前必做三件事：编译、日志、健康检查
本地能跑 ≠ 可部署。上线前确认：
- 用
GOOS=linux GOARCH=amd64 go build -o myapp .交叉编译，别直接传 macOS 二进制到 Linux 服务器 - 日志输出到
stdout（而非文件），方便容器平台（如 Docker、K8s）统一采集；禁用log.Fatal，它会直接退出进程，不利于优雅重启 - 暴露
/health或/ready端点，返回 HTTP 200 即可，别加数据库连通性检查 —— 初始阶段它只会让部署卡在 probe 失败
真正容易被忽略的是信号处理：Go 进程默认不响应 SIGTERM，K8s 删除 Pod 时会 kill -15，若没监听就会立即终止，正在处理的请求丢掉。哪怕只加两行也值得：
import "os/signal"
// 在 main 函数里
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGTERM, syscall.SIGINT)
<-sigChan
log.Println("shutting down...")
// 这里可以调用 http.Server.Shutdown()
