Go语言RESTful API设计规范_Golang接口设计最佳实践-Golang-PHP中文网

go restful api核心在于可维护性：路由须用r.group()按资源隔离并前置版本号；请求体必须强类型结构体+json标签；http状态码需语义化（404/201/400等）；错误应统一拦截处理，id类型须与存储一致。

go语言restful api设计规范_golang接口设计最佳实践

Go 语言写 RESTful API，核心不是“能不能跑”，而是“别人敢不敢调、改起来疼不疼、出问题查不查得清”——这三点直接由路由设计、错误码、分层结构和响应格式决定。

直接在根引擎上注册 r.GET("/users", h.GetUser) 看似简单，但很快会失控：版本升级要改所有路径、中间件无法按资源启停、权限控制粒度变粗。Gin 的 r.Group() 是唯一合理起点。

版本号必须前置，比如 r.Group("/api/v1")，而不是 /users/v1 —— 后者破坏资源语义，也增加反向代理配置复杂度
嵌套资源用子 Group，例如订单属于用户：users := r.Group("/users"); orders := users.Group("/:user_id/orders")，避免拼接字符串构造路径
不要在 Group 内混用不同资源，比如 users.GET("/products", ...) —— 这会让路由表语义混乱，后续加监控或限流时无法按资源维度打标

用 map[string]interface{} 解析 JSON 虽然灵活，但等于放弃类型安全、文档生成、IDE 提示和字段校验能力。所有入参必须走强类型结构体。

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

结构体字段必须带 json: 标签，且与前端约定一致，比如 Name string `json:"name"`；漏掉标签会导致字段始终为空
必填字段加 binding:"required"，如 Email string `json:"email" binding:"required,email"`，c.ShouldBindJSON() 会自动返回 400
禁止在 handler 里手动 json.Unmarshal() —— 绕过 ShouldBindJSON() 就等于绕过 Gin 的错误统一处理机制，400 错误不会被拦截，日志和监控缺失

返回全用 200 OK + 自定义 code 字段，是 Go 新手最常踩的坑。客户端无法靠状态码做重试、缓存或路由判断，前端 fetch 的 response.ok 永远为 true，错误流控彻底失效。

资源不存在必须用 http.StatusNotFound (404)，不是 200 + {"code": 404, "msg": "not found"}
创建成功必须用 http.StatusCreated (201)，并设 Location header，比如 c.Header("Location", "/api/v1/users/"+id)
业务校验失败（如余额不足）用 http.StatusBadRequest (400)，而非 500 —— 500 表示服务端崩溃，不该用于预期中的业务拒绝

每个 handler 里写 if err != nil { c.JSON(...); return } 重复又易错。真正健壮的服务，错误应从 service 层透出，由中间件或全局 error handler 拦截。

service 层错误不要包装成 fmt.Errorf("failed to create user: %w", err) 后直接扔给 handler —— 这会让原始错误类型丢失，无法区分是 DB 超时还是参数错
推荐用自定义 error 类型实现 StatusCode() int 方法，比如 type AppError struct { Code int; Msg string }，再在中间件中统一调 err.StatusCode()
Gin 的 c.Error() 不是摆设：它把 error 注入上下文，可被 gin.RecoveryWithWriter 或自定义中间件捕获，比满屏 if err != nil 更可靠

最易被忽略的一点：URI 中的 ID 类型必须和后端存储一致。用 string 接口 ID（如 UUID）就别在 service 层转成 int 查数据库，否则 404 和 500 边界会模糊——本该 404 的非法 ID，可能因类型转换 panic 成 500。