Golang开发接口设计怎么做？RESTful规范落地建议-Golang-PHP中文网

go写restful接口核心是可维护性：路由须复数路径+http方法定语义，请求/响应结构体需json标签与类型控制，错误须标准状态码+结构化json。

golang开发接口设计怎么做？restful规范落地建议

Go 写 RESTful 接口不是“能跑就行”，而是要让别人调得明白、改得安心、出问题查得快——核心就三条：路由必须用复数路径+HTTP 方法定语义，请求/响应结构体必须带 json: 标签且字段类型可控，错误必须返回标准状态码+结构化 JSON。

路由必须用复数名词 + 路径参数，别拼 query 或动词

常见错误是写 /getUser?id=123 或 /deleteUser/123，这本质是 RPC 风格，绕过中间件、无法缓存、OpenAPI 工具识别不了。正确做法是：

/users（集合）对应 GET/POST；/users/{id}（单个资源）对应 GET/PUT/PATCH/DELETE
用 chi 或 gin.Group() 管理嵌套，比如 users.Group("/:user_id/orders")，别手动拼 /users/123/orders
版本号前置：r.Group("/api/v1")，不是 /users/v1，也不是 Accept 头——反向代理和日志都认路径
标准库 http.ServeMux 不支持 {id} 语法，硬解析 r.URL.Path 容易漏边界、错匹配，建议直接上 chi

结构体字段必须显式声明 `json:` 标签，且区分“未提供”和“提供为空”

漏掉 json: 标签，字段永远为空；用 map[string]interface{} 接收请求体，等于放弃校验、IDE 提示和文档生成能力。实操要点：

Golang Google Wire

在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind（接口→实现）、wire.Struct、wire.Value、wire.Interface

下载

请求体字段全用指针 + omitempty，例如 Name *string `json:"name,omitempty"`，这样能判断前端到底传没传这个字段
必填字段加 binding:"required"（Gin）或自定义 validator，c.ShouldBindJSON() 会自动返回 400，别自己 json.Unmarshal()
响应体禁止直接返回 DB 模型，用专用 DTO，敏感字段加 json:"-"，比如 PasswordHash string `json:"-"`

错误响应必须用标准 HTTP 状态码，别塞进 200 里

返回 200 OK + {"code": 404, "msg": "not found"} 是最常见坑——前端 fetch().ok 永远为 true，重试、缓存、监控全失效。该怎么做：

资源不存在 → w.WriteHeader(http.StatusNotFound)（404），不是 200
参数校验失败 → http.StatusUnprocessableEntity（422），比 400 更精准
创建成功 → http.StatusCreated（201），并设 Location header 指向新资源
统一封装错误响应结构：{"code": "invalid_email", "message": "邮箱格式错误"}，不暴露原始 error 字符串

中间件顺序不能乱，鉴权必须在业务逻辑之前

把 JWT 解析、权限校验写进 handler 里，会导致重复、漏判、难测。标准链路应该是：recovery → logging → CORS → auth → RBAC → handler。关键点：

鉴权中间件必须提前终止请求，失败时直接 w.WriteHeader(401) 或 403 并返回结构化错误，别让请求继续往下走
限流中间件要返回 X-RateLimit-Limit 和 X-RateLimit-Remaining header，方便客户端自适应
所有中间件的 panic 必须被 recovery 捕获，否则整个服务可能挂掉，别依赖 defer 手写 recover

最常被忽略的是路径参数校验和状态码语义一致性：比如 /users/{id} 中的 {id} 如果是数字，应在路由层做正则匹配（chi 支持 /{id:\d+}），而不是等进 handler 再 parse 出错；还有 DELETE /users/{id} 成功后必须返回 204 No Content，不是 200，这点连很多老项目都在错。