本机执行 go run .,终端打印出监听地址,浏览器访问 127.0.0.1:8080/health 立刻拿到一段 JSON。把编译好的二进制传到 Linux 服务器,执行 ./websvc 没有报错,从办公网访问却一直是「连接被拒绝」。登服务器用 ss -lntp 一看,进程只监听了 127.0.0.1:8080,外部流量根本进不来;还有一次是二进制在这台机器上直接报找不到动态库,因为编译时开了 CGO,换到精简镜像里没有对应的系统库。

另一种常见开局发生在更早一步:go get github.com/gin-gonic/gin 卡在 downloading,几分钟后报网络超时。这通常不是 Gin 的问题,而是模块代理没有配置,或者公司网络只允许走内网镜像。Go 的依赖拉取和运行是两件独立的事,先把依赖拉下来,后面的启动才有意义。

这篇从空目录开始,把一个能跑、能验证、以后还能往上加功能的 Gin 服务搭起来。顺序是:先说明 Gin 负责什么、和标准库怎么选;再初始化模块、拉依赖;然后定目录、写 main.go、加 /health;最后真正编译运行,用 curl 看返回。Go 语法本身不在这一组文章里讲,默认你写过函数、结构体和基本的错误处理。

Gin 负责什么,什么情况下不该用它

Gin 是一个 Go 的 HTTP Web 框架。它把「按 URL 和方法找到处理函数」「把请求体解析成结构体」「串联中间件」「输出 JSON」这几件高频事情封好了,底层仍然用标准库的 net/http。所谓框架,在这里不是一整套全家桶,而是一层路由和上下文封装,项目结构、数据库、配置仍然要自己决定。

对比三种起步方式,差别主要在「谁来写重复代码」:

标准库 net/http

Go 1.22 之后,http.ServeMux 支持 GET /orders/{id} 这种带方法和路径参数的模式,路由能力比旧版强很多。没有第三方依赖,升级风险最低,但请求绑定、参数校验、分组中间件都要自己封装。适合接口很少、追求零依赖的内部服务。

Gin

路由树、分组、参数绑定、统一错误输出都有现成实现,文档和示例多,团队上手快。代价是引入一组第三方依赖,并且要理解它的上下文复用和中间件顺序,否则会写出难查的 bug。常规 JSON API 用它是合适的。

Echo

定位和 Gin 接近,路由、中间件、绑定也都有,API 风格略有不同。两者不存在谁绝对更好,选团队已经熟悉、社区维护正常的那个即可,不要在一个项目里混用两套框架。

维度net/httpGin
额外依赖无一个框架及其间接依赖
路径参数Go 1.22 起原生支持:id 写法,配套 c.Param
分组路由需要自己包一层r.Group 直接支持
请求绑定手写解码与校验ShouldBindJSON 加校验标签
中间件func(http.Handler) http.HandlerUse 链式注册,c.Next 控制顺序
可控程度最高,所有行为自己写中等,约定由框架定

判断标准可以很简单:如果服务只有三五个接口、团队不想维护框架升级,标准库足够;如果是会持续增加路由、需要统一鉴权和日志的业务 API,Gin 省下来的重复代码远大于学习成本。不要因为「别人都在用」就选框架,也不要为了显得克制,在几十个接口里手写一套半成品路由。

go.mod、go.sum 与依赖拉取

Go 模块(module)是一组包的版本边界。一个仓库通常就是一个模块,模块路径写在 go.mod 里,别人通过这个路径引用你的包。go.mod 记录三件事:模块名、本模块要求的最低 Go 版本、直接和间接依赖的版本;go.sum 记录每个依赖内容的校验和,防止同一版本在不同机器上被替换成别的代码。

从空目录开始,先初始化模块,再拉 Gin。版本建议钉住,不要在发布流程里用 @latest,否则今天构建和下周构建可能拿到不同的框架行为:

go mod init demo/websvc
go get github.com/gin-gonic/gin@v1.10.1
go mod tidy

本机实际拉取成功后,go.mod 的开头是这样,依赖数量比想象中多,因为 Gin 自带校验、JSON 编解码等间接依赖:

module demo/websvc

go 1.27.3

require (
	github.com/bytedance/sonic v1.11.6 // indirect
	github.com/gin-gonic/gin v1.10.1
	github.com/go-playground/validator/v10 v10.20.0 // indirect
	github.com/goccy/go-json v0.10.2 // indirect
	github.com/json-iterator/go v1.1.12 // indirect
	github.com/mattn/go-isatty v0.0.20 // indirect
	github.com/ugorji/go/codec v1.2.12 // indirect
	golang.org/x/net v0.25.0 // indirect
	google.golang.org/protobuf v1.34.1 // indirect
	gopkg.in/yaml.v3 v3.0.1 // indirect
)

go mod tidy 会删掉代码里没用到的依赖,补齐缺失的间接依赖。它应该在提交前跑一次,并且把 go.mod 与 go.sum 一起提交。只提交其中一个,别人拉代码后构建会报校验失败,或者悄悄换了版本。

拉取失败时先看代理。Go 默认的模块代理在部分网络环境不可达,可以临时切换:

$env:GOPROXY='<镜像地址>,direct'
go env GOPROXY
go get github.com/gin-gonic/gin@v1.10.1

direct 表示代理不可用时直连源站。公司内部一般会提供自己的 Athens 或 Nexus 代理,问清地址后写进 go env -w GOPROXY=...,不要每个项目各配一套。私有仓库还需要 GOPRIVATE,否则代理会去公网找不存在的模块。

构建机不能联网时,可以提前把依赖缓存下来。go mod download 只下载模块到本地缓存,不编译;go mod vendor 则把依赖复制进项目里的 vendor 目录,构建时加 -mod=vendor 就不走网络。后者适合离线发布,代价是仓库体积变大、依赖更新要重新 vendor,小团队按自己的网络条件选一种即可。

目录结构:cmd 与 internal 的分工

单文件起一个服务没问题,但接口一多,所有处理函数塞在 main.go 里会迅速失控。Go 官方没有强制目录规范,社区比较通用的是 cmd 放可执行入口,internal 放不对外暴露的实现。名字不是重点,边界才是:入口只负责装配,业务逻辑不要写在 main 里。

cmd/websvc只做参数解析、依赖装配、启动和优雅停机,尽量不超过一百行。
internal/httpapi路由注册、中间件、请求与响应的结构体,这一层只关心 HTTP。
internal/service业务规则,比如下单要先校验库存、再写订单,它不直接碰 gin.Context。
internal/store数据库与外部服务访问,负责 SQL、事务和连接池,向上暴露接口。

实际目录可以按下面的方式展开。这里用缩进表示层级,不要用制表符画线,复制到终端也不会乱:

websvc/
  cmd/websvc/main.go
  internal/config/config.go
  internal/httpapi/router.go
  internal/httpapi/health.go
  internal/service/order.go
  internal/store/postgres.go
  migrations/
  go.mod
  go.sum

internal 这个名字有实际作用:Go 规定其他模块不能导入 internal 目录下的包。把实现放进去,等于告诉外部「这些不是公共 API」,以后改函数签名不用考虑兼容。反过来,如果你确实想让别的项目复用,就放到顶层普通包,不要为了「看起来规范」把所有东西都塞进 internal。

小服务不必一次拆到四层。更实际的做法是先用 main.go 加一个 internal/httpapi 跑通,等出现第二个业务对象、开始有跨表事务时,再把 service 和 store 拆出来。目录是为减少修改成本服务的,提前拆得太细,改一个字段要动五个文件,反而更慢。

最小 main.go 与 /health

下面这段代码就是本机实际运行的版本。它创建引擎、注册两个路由、启动监听。为了看清启动日志,这里用 gin.Default(),它自带日志和 panic 恢复两个中间件;生产上更常见的做法是用 gin.New() 后自己选择中间件,下一篇会展开。代码里的 binding:"required" 是校验标签,请求缺字段时 Gin 会直接返回 400,不用手写判断。

package main

import (
	"log/slog"
	"net/http"
	"os"
	"time"

	"github.com/gin-gonic/gin"
)

type healthResp struct {
	Status  string `json:"status"`
	Service string `json:"service"`
	Time    string `json:"time"`
}

type createOrderReq struct {
	UserID string  `json:"user_id" binding:"required"`
	Amount float64 `json:"amount" binding:"required,gt=0"`
}

func main() {
	port := os.Getenv("APP_PORT")
	if port == "" {
		port = "8080"
	}

	r := gin.Default()

	r.GET("/health", func(c *gin.Context) {
		c.JSON(http.StatusOK, healthResp{
			Status:  "ok",
			Service: "go-web-demo",
			Time:    time.Now().UTC().Format(time.RFC3339),
		})
	})

	r.POST("/v1/orders", func(c *gin.Context) {
		var req createOrderReq
		if err := c.ShouldBindJSON(&req); err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}
		c.JSON(http.StatusCreated, gin.H{"id": "ord_1001", "user_id": req.UserID, "amount": req.Amount})
	})

	slog.Info("http server starting", "addr", ":"+port, "mode", gin.Mode())
	if err := r.Run(":" + port); err != nil {
		slog.Error("server exited", "err", err)
		os.Exit(1)
	}
}

几个容易忽略的点。第一,结构体字段必须大写导出,JSON 编码器才看得到;想让返回是 user_id 而不是 UserID,靠 json 标签,不靠改字段名。第二,c.JSON 会自动设置 Content-Type: application/json; charset=utf-8 并写入状态码,不需要额外设置响应头。第三,/health 不查数据库、不调下游,它只回答「进程还在不在」。把依赖检查塞进这里,数据库一抖动,负载均衡就把所有实例摘掉,小故障会被放大成整体不可用。

创建成功的响应用了 201 而不是 200,因为请求产生了新资源;如果只是查询,用 200 更准确。示例里返回体用 gin.H 拼了一个临时 map,字段顺序不固定、类型也不受约束,演示够用;真实项目应该定义响应结构体,至少让字段名和类型在编译期可见,避免某个分支少返回一个字段。

启动日志里的 mode=debug 来自 Gin 的默认模式。它会打印每个路由和每次请求,开发时有用,生产上会带来额外开销和敏感路径泄露,部署时用 GIN_MODE=release 或代码里调 gin.SetMode(gin.ReleaseMode) 关掉。日志里还有一条「信任所有代理」的警告,意思是 c.ClientIP() 可能被伪造,放到反向代理后面时要显式设置可信代理地址。

真正跑一遍:编译、启动与 curl

先编译再运行,能把「依赖问题」和「运行问题」分开。本机执行下面的命令,编译产物放在当前目录:

go build -o websvc.exe .
$env:APP_PORT="18081"
.\websvc.exe

这里用 18081 而不是 8080,是因为本机 8080 已经被另一个服务占用。端口被占时 Gin 会返回 listen tcp :8080: bind: An attempt was made to access a socket in a way forbidden by its access permissions.,随后进程退出。启动日志的关键几行如下,时间、端口都是实际输出:

[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
[GIN-debug] GET    /health                   --> main.main.func1 (3 handlers)
[GIN-debug] POST   /v1/orders                --> main.main.func2 (3 handlers)
[GIN-debug] Listening and serving HTTP on :18081
2026/11/07 08:27:45 INFO http server starting addr=:18081 mode=debug

另开一个终端,用 curl 调健康检查和下单接口。先看健康检查:

curl -i http://127.0.0.1:18081/health

实际返回:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 06 Nov 2026 23:57:02 GMT
Content-Length: 69

{"status":"ok","service":"go-web-demo","time":"2026-11-06T23:57:02Z"}

再发一个合法订单,注意 JSON 里的字段名用的是带下划线的标签名:

curl -i -X POST http://127.0.0.1:18081/v1/orders \
  -H "Content-Type: application/json" \
  -d '{"user_id":"u_42","amount":128.5}'

实际返回 201 Created,金额按浮点原样回显。接着发一个缺字段、金额为负的请求,验证校验标签真的生效:

curl -i -X POST http://127.0.0.1:18081/v1/orders \
  -H "Content-Type: application/json" \
  -d '{"amount":-1}'

实际返回 400,错误信息由 Gin 的校验器拼出:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Content-Length: 194

{"error":"Key: 'createOrderReq.UserID' Error:Field validation for 'UserID' failed on the 'required' tag\nKey: 'createOrderReq.Amount' Error:Field validation for 'Amount' failed on the 'gt' tag"}

访问一个没注册的路径,返回的是纯文本 404 page not found,不是 JSON。这个差异在前后端联调时经常造成误会:前端按 JSON 解析失败,以为是服务挂了,其实只是路由写错。要统一错误格式,需要自己注册 NoRoute,这个留到路由那篇处理。

go run . 也能达到同样效果,首次编译会慢一些,本机这次在依赖已缓存的情况下仍然等了大约一分钟才看到监听日志。日常开发用 go run . 省事,排查启动参数或做性能观察时用编译后的二进制,行为更接近线上。验证完在运行窗口按 Ctrl+C 停掉进程,再确认端口已经释放,不要把它一直留在后台占着端口,否则下一次启动会撞上「地址已在使用」。

配置从环境变量来,启动时就校验

端口、数据库地址、密钥这些东西不能写死在代码里。简单服务用环境变量就够了,不必一上来就引入配置中心。关键是两点:所有配置在启动时读一次并校验,缺失或格式错误就立刻退出;配置结构集中在一个包里,不要在每个 handler 里散着 os.Getenv。

package config

import (
	"fmt"
	"os"
	"strconv"
)

type Config struct {
	Port    int
	DBURL   string
	Env     string
}

func Load() (Config, error) {
	var c Config
	raw := os.Getenv("APP_PORT")
	if raw == "" {
		raw = "8080"
	}
	port, err := strconv.Atoi(raw)
	if err != nil || port < 1 || port > 65535 {
		return c, fmt.Errorf("APP_PORT 不是合法端口: %q", raw)
	}
	c.Port = port
	c.DBURL = os.Getenv("DATABASE_URL")
	c.Env = os.Getenv("APP_ENV")
	if c.Env == "" {
		c.Env = "dev"
	}
	if c.Env == "prod" && c.DBURL == "" {
		return c, fmt.Errorf("生产环境必须设置 DATABASE_URL")
	}
	return c, nil
}

这段代码在启动时把错误暴露出来,而不是等到第一个请求打进来才发现数据库地址为空。生产环境里最贵的故障是「服务起来了,但每个请求都失败」,它会让健康检查误判、让发布流程以为成功。启动校验是最后一道便宜的保险。

密钥只放环境变量或密钥管理服务,不要提交 .env,也不要把密钥打进镜像。环境变量在进程列表和崩溃日志里可能泄露,能接受这一点再放;更严格的做法是启动时从密钥服务读取,进程内只保留内存副本。无论哪种,代码里都不要打印完整配置,日志里只打「已加载,端口多少,环境名是什么」。

现象、原因与第一步

现象真实原因第一步查什么
go get 卡住或超时模块代理不可达,或私有仓库没配 GOPRIVATEgo env GOPROXY,换成可用代理后重试
启动报端口被占用本机已有服务监听同一端口,或上一次的进程没退干净ss -lntp 或 netstat -ano 找到占用进程
服务在服务器上起不来编译平台不对,或 CGO 依赖的系统库在镜像里不存在看 file websvc 的架构,必要时用 CGO_ENABLED=0 重编
本机能访问,外部连不上监听地址是 127.0.0.1,或防火墙、安全组没放行ss -lntp 看监听地址,再从另一台机器测端口
访问路径返回 404方法或路径拼错,路由没注册,或前缀不一致看启动日志里的路由表,确认方法、路径和大小写
JSON 字段名不对结构体字段没导出,或缺少 json 标签检查字段首字母是否大写,标签是否写成 json:"user_id"
请求体明明有值却报 400Content-Type 不是 application/json,或字段类型不匹配用 curl -i 看请求头,核对数字与字符串类型
日志里一堆 mode=debug没设 GIN_MODE=release,框架按开发模式运行检查部署环境变量和 gin.SetMode 调用
go.sum 校验失败依赖被替换,或只提交了 go.mod 没提交 go.sum确认两个文件都在版本库,执行 go mod verify

边界与代价

Gin 的上下文对象是复用的。框架用对象池减少每次请求的分配,请求结束后 *gin.Context 会被放回池里,下一次请求可能拿到同一个对象。所以不能把 c 存进全局变量,也不能在 go func 里直接用它;需要异步处理时先 c.Copy(),并且只复制需要的值。这个坑在「日志异步上报」和「后台任务」里最容易踩,表现是日志里混进了别的请求的路径或用户。

框架带来的便利是有边界的。Gin 不负责数据库、不负责配置、不负责任务队列,它也不会替你决定错误码和响应格式。很多项目用了 Gin 仍然写出一堆重复代码,因为把业务逻辑直接塞进 handler,框架只省了路由那一层。真正的结构收益来自 cmd、internal 的边界,而不是选哪个框架。

依赖很轻,但不是零。一次 go get 拉下来几十个间接包,升级 Gin 时可能被动升级 JSON 库或校验库。小服务、内部工具、只需要三五个接口的场景,标准库 net/http 加少量手写封装往往更省心:没有框架升级负担,行为全部可见。选择之前先估算接口数量和团队维护能力,不要为了「以后可能变大」提前背上框架。

还有两个现实代价。第一,Gin 的绑定标签很强大,但错误信息是英文且偏底层,直接返回给前端体验很差;需要自己包一层错误映射,这属于额外的维护成本。第二,路由冲突、通配符写法、可信代理这些细节,框架不会在编译期提醒你,只能靠启动日志和测试发现。把「启动后跑一遍关键 curl」写进发布检查单,比事后看监控便宜得多。

当天能自己验证的练习

  1. 在空目录执行 go mod init demo/websvc,再执行 go get github.com/gin-gonic/gin@v1.10.1,打开 go.mod 数一数有多少条 indirect,然后用 go mod why github.com/bytedance/sonic 看它为什么被引入。
  2. 把示例 main.go 的 APP_PORT 改成已被占用的端口,观察启动日志和退出码,再用 netstat -ano 找到占用者。
  3. 启动服务后执行 curl -i http://127.0.0.1:端口/health,确认状态码、Content-Type 和 JSON 字段;再把路由改成 /healthz,确认旧路径返回 404 的正文是什么样。
  4. 用 curl 发一个 amount 为字符串的请求,观察 400 的错误文字;再把 Content-Type 去掉重发,对比两次错误信息的差别。
  5. 设置 GIN_MODE=release 后重启,对比启动日志少了哪些行、访问一次接口后是否还有逐请求日志。

小结

三句话:Gin 只是路由和上下文的封装,项目结构仍要自己定;go.mod 与 go.sum 一起提交,依赖版本钉住;服务启动后必须能用一条 curl 验证,否则「跑起来了」只是感觉。

骨架搭好之后,下一个问题自然出现:路由怎么分组、中间件按什么顺序执行、鉴权失败为什么处理函数还会跑。这些都属于请求生命周期,下一篇从一个「忘了 c.Abort()、鉴权失败后接口照样返回数据」的真实写法开始,把 Gin 的中间件链拆开讲。