Golang编写优雅的API接口：RESTful风格在语言学习中的应用-Golang-PHP中文网

go写restful api的优雅在于状态码、content-type、错误结构三者严格对齐：400仅用于解析失败，404专指资源不存在，201限于post创建成功；响应必须统一json格式与固定schema，禁止混用字段名或裸数据。

golang编写优雅的api接口：restful风格在语言学习中的应用

Go 写 RESTful API 的“优雅”不在于框架多炫，而在于状态码、Content-Type、错误结构这三处是否始终对齐——错一处，前端就得多写一层 try/catch 或 if-else。

HTTP 状态码不能只靠 http.Error() 填充

net/http 的 http.Error() 默认塞 500，且不设 Content-Type；gin 的 c.AbortWithStatusJSON(400, ...) 虽然设了 JSON，但若没统一错误结构，前端仍要反复判断 error、message、err 字段名。

400 Bad Request 只用于参数解析失败（如 id 不是整数、JSON 字段缺失）
404 Not Found 必须严格对应资源不存在（如 GET /users/999），别把“用户已注销”或“权限不足”塞进去
201 Created 仅限 POST 成功且服务端生成了新 URI（如返回 Location: /users/123），PUT/PATCH 不适用
用 w.WriteHeader(400) 时，必须紧跟着 w.Header().Set("Content-Type", "application/json")，否则前端 fetch 得到的是 text/plain 类型响应

JSON 响应体结构必须全局一致

前端调用接口时，不会关心你是用 gin 还是 chi，只认 {"error": "...", "code": 400, "data": null} 这种固定 schema。一旦某个 handler 返回 {"msg": "xxx"}，前端就要加分支逻辑。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

定义统一响应结构体，例如：type Response struct { Code int `json:"code"` Error string `json:"error"` Data interface{} `json:"data,omitempty"` }
所有 handler 都走 json.NewEncoder(w).Encode(Response{...})，禁止直接 fmt.Fprintf(w, "{...}")
中间件里统一拦截 panic，包装成 Response{Code: 500, Error: "internal error"}，而不是让 panic 漏到外层
别在 handler 里用 log.Fatal 或 os.Exit，它们会杀掉整个 HTTP server

路径参数、查询参数、请求体必须分清来源和校验方式

同一个字段出现在不同位置，处理逻辑完全不同：路径里的 id 是字符串，得转 int 并检查溢出；查询参数 limit 要设默认值；JSON body 里的 email 必须用 binding:"required,email" 校验。

路径参数用 c.Param("id")（gin）或 chi.URLParam(r, "id")（chi），拿到后立即做类型转换和范围检查
查询参数优先用 c.GetQuery("page", &page)，避免手动 strconv.Atoi(c.Query("page")) 忘判 err
JSON 请求体必须用 c.ShouldBindJSON(&req)，它自动触发 struct tag 中的 binding 规则；别用 json.Unmarshal 手动解，会绕过校验
禁止把路径参数、查询参数、body 混在一个 struct 里 bind——它们语义不同，校验规则也不同

map[interface{}]interface{} 在 json.Marshal 时必然 panic

这是 Go 类型系统最常被忽略的坑：从 yaml.Unmarshal 或某些动态解析库来的 map，key 是 interface{}，而 json.Marshal 只接受 map[string]interface{}。

收到 map[interface{}]interface{} 后，先用 reflect.ValueOf(m).MapKeys() 检查所有 key 是否为 string 类型
更稳做法：定义明确 struct，哪怕字段是 json.RawMessage，先 json.Unmarshal 到 struct，再按需解析子字段
永远别信文档里写的 “generic map”，Go 没有泛型 map，只有具体 key 类型的 map
如果必须支持任意 key，用 map[string]interface{} 接收，前端传过来的 JSON object key 天然是 string

真正难的不是写出能跑的 API，而是让第 1 个 handler 和第 100 个 handler 在状态码含义、错误字段名、Content-Type 设置上完全一致——这种一致性没法靠单测覆盖，只能靠约束和习惯。