用 net/http 可构建最小可用 RESTful API：按 HTTP 方法分发请求、用闭包注入依赖、显式设 Content-Type、统一错误处理；需 gorilla/mux 支持路径参数与子路由；JSON 序列化推荐指针字段区分“未提供”与“空值”；中间件须正确调用 next.ServeHTTP 并处理 panic。
用 net/http 搭建最小可用 RESTful 路由
Go 标准库的 net/http 足够支撑轻量级 RESTful API，无需一开始就引入框架。关键在于按 HTTP 方法分发请求，而非靠路径前缀硬编码。
常见错误是把所有 handler 塞进一个函数里，导致难以测试和维护。正确做法是为每个资源定义独立 handler，并用闭包注入依赖（如数据库连接）：
func userHandler(db *sql.DB) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
switch r.Method {
case "GET":
// 用 r.URL.Query().Get("id") 解析 query 参数
id := r.URL.Query().Get("id")
if id == "" {
http.Error(w, "missing id", http.StatusBadRequest)
return
}
// ... 查询逻辑
case "POST":
// 用 json.NewDecoder(r.Body).Decode() 解析 JSON body
default:
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
}
}
}
- 避免直接操作
r.URL.Path做字符串匹配——易出错且不支持路径参数（如/users/{id}） - 所有 handler 必须显式设置
Content-Type: application/json; charset=utf-8，否则前端可能解析失败 - 不要在 handler 内部 panic，要用
http.Error或自定义 error writer 统一处理错误响应格式
用 gorilla/mux 支持路径参数与子路由
当需要 /api/v1/users/{id} 这类动态路径，或按版本、模块组织路由时，gorilla/mux 是最轻量可靠的选型。它不侵入 handler 签名，兼容标准 http.Handler。
典型陷阱是忽略路由顺序：mux 按注册顺序匹配，Path("/users/{id}") 必须放在 Path("/users/me") 之后，否则后者永远无法命中。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
r := mux.NewRouter()
r.HandleFunc("/health", healthHandler).Methods("GET")
api := r.PathPrefix("/api/v1").Subrouter()
api.HandleFunc("/users", userCreateHandler).Methods("POST")
api.HandleFunc("/users/{id:[0-9]+}", userGetHandler).Methods("GET") // 正则约束防止误匹配
- 路径参数必须用
{name:pattern}显式声明正则，否则{id}会匹配任意字符（包括斜杠），引发越界路由 - 子路由（
Subrouter()）不继承父级中间件，需单独挂载日志、CORS 等中间件 - 避免嵌套过深的 Subrouter，三层以上建议拆成独立 Router 实例，便于单元测试隔离
JSON 序列化时绕开 json.Marshal 的零值陷阱
Go 的 struct 默认字段零值（0、""、nil）会被序列化进 JSON，但 REST API 通常希望省略空字段，或区分“未提供”和“显式设为空”。直接用 json:",omitempty" 不可靠——它会吃掉 false、0、""，但有时你需要保留它们。
真正可控的方式是组合使用 json:",omitempty" 和指针字段：
type User struct {
ID int64 `json:"id"`
Name string `json:"name,omitempty"` // 空字符串不输出
Email *string `json:"email,omitempty"` // nil 字段不输出；*string 可区分 “未传” 和 “传了空字符串”
Active *bool `json:"active,omitempty"` // 同理，可表达三态：未提供 / true / false
}
- 不要对所有字段加
omitempty，比如ID是主键，即使为 0 也必须返回 - 接收请求时，用指针字段 +
json.Unmarshal可准确判断字段是否被客户端显式设置 - 数据库扫描到 struct 时，注意
sql.NullString等类型需额外实现json.Marshaler接口，否则序列化为{"String":"xxx","Valid":true}
中间件里别漏掉 next.ServeHTTP 的调用时机
写日志、鉴权、CORS 中间件时，最常犯的错误是忘记调用 next.ServeHTTP(w, r)，或者在错误分支里提前 return 却没写 return，导致后续 handler 仍被执行。
正确模式是：中间件函数返回 http.Handler，内部用闭包捕获 next，并严格控制执行流：
func authMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
token := r.Header.Get("Authorization")
if token == "" {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return // 必须 return，否则 next 仍会执行
}
// 验证 token...
if !valid {
http.Error(w, "invalid token", http.StatusUnauthorized)
return
}
// 注入用户信息到 context
ctx := context.WithValue(r.Context(), "user_id", userID)
r = r.WithContext(ctx)
next.ServeHTTP(w, r) // 正确位置：仅在验证通过后调用
})
}
- 中间件链中任意一环 panic，整个请求会崩溃——务必用 defer+recover 包裹，但更推荐用
http.Server.ErrorLog记录并返回 500 - 不要在中间件里修改
w.Header()后再调用next.ServeHTTP，某些 handler 可能已写入响应头，导致header already writtenpanic - CORS 中间件必须在所有业务 handler 之前注册，否则预检请求（OPTIONS）可能被路由忽略
路径参数正则、指针字段语义、中间件 return 控制——这三点在本地调试时不易暴露，上线后才突然出问题。动手前先想清楚：这个字段客户端到底有没有权利不传？这个路由会不会被其他路径意外覆盖？这个中间件挂在哪一层才不会干扰 header 写入？
