Golang如何实现RESTful API_Golang REST接口设计规范

restful 路由须严格遵循 http 方法语义，推荐使用 chi 等框架显式绑定方法；json 处理应区分“未提供”与“提供为空”，响应用 dto 过滤敏感字段；错误需统一封装为 json 格式；中间件必须覆盖 cors、jwt 验证与限流；openapi 文档应通过 swaggo 或 oapi-codegen 生成并契约先行。

RESTful 路由设计要严格遵循 HTTP 方法语义

GET 不该修改数据，POST 不该用于幂等创建，PUT 必须能完整替换资源——这是 Go 实现 REST API 的底线。很多项目用 http.HandleFunc 手写路由，结果把 GET /users/delete?id=123 当成“删除用户”，这违反 REST 原则，也绕过中间件鉴权和日志统一处理。

推荐用标准库 http.ServeMux 或轻量框架如 chi，显式绑定方法：

router.Get("/users", listUsers) router.Post("/users", createUser) router.Get("/users/{id}", getUser) router.Put("/users/{id}", updateUser) router.Delete("/users/{id}", deleteUser)

注意：chi 的 {id} 是路径参数，不是查询参数；若用 gorilla/mux，语法类似但需调用 Vars(r) 提取；标准库不支持路径参数，得自己解析 r.URL.Path，容易出错。

JSON 请求/响应必须做结构体字段控制与错误映射

Go 的 json.Marshal 默认导出所有大写字段，且对空值、零值不做区分。前端传 {"name": ""}，后端结构体若定义为 type User { Name String `json:"name"` }，解码后 Name 就是空字符串，无法判断是“用户真叫空名”还是“前端没传”。

立即学习“go语言免费学习笔记（深入）”；

实操建议：

• 请求体结构体用指针字段 + omitempty，例如 Name *string `json:"name,omitempty"`，这样可区分“未提供”和“提供为空”
• 响应体结构体避免直接暴露数据库模型，用专用 DTO（如 UserResponse），并统一加 json:"-" 过滤敏感字段（如 PasswordHash）
• 错误响应不要返回 http.Error 原始文本，而应统一封装为 { "error": "invalid_id", "message": "ID must be numeric" } 格式，并设状态码为 400/404/500 等

中间件链必须覆盖 CORS、JWT 验证、请求限流三类基础能力

没有中间件的 Go HTTP 服务等于裸奔。常见错误是把鉴权逻辑写进 handler 内部，导致重复、漏判、难以测试。

典型中间件顺序（从外到内）：

• cors.Handler：用 rs/cors，别手写 header，尤其注意预检请求（OPTIONS）必须透传
• authMiddleware：检查 Authorization: Bearer xxx，解析 JWT，把 user_id 注入 context.Context，后续 handler 用 r.Context().Value("user_id") 获取
• rateLimitMiddleware：按 IP 或 user_id 限流，推荐 uber-go/ratelimit，避免用内存 map 自实现（并发不安全）

注意：chi 中间件执行顺序依赖注册顺序，Use() 在前的先执行；若用标准库，需手动包装 http.Handler，容易漏掉 return 导致后续 handler 仍执行。

Go 的 net/http 默认不支持 OpenAPI 文档自动生成

很多团队以为写完 handler 就算完成 API，结果前端靠看代码猜字段、改接口不敢动、联调全靠群吼。Go 生态里没有像 SpringDoc 那样开箱即用的方案。

可行路径只有两个：

• 手动维护 openapi.yaml：用 swaggo/swag，在 handler 上加注释如 // @Success 200 {Object} UserResponse，再运行 swag init 生成 docs，适合中小项目，但注释易过期
• 代码优先生成：用 deepmap/oapi-codegen，先写 OpenAPI spec，再生成 Go server stub 和 client，适合契约先行团队，但学习成本高、迭代慢

别碰 go-swagger——已归档，不维护；也别信“用反射自动扫描 Struct 生成文档”的轮子，字段描述、示例值、枚举约束全丢失。

真正难的不是生成文档，而是让所有人接受“接口变更必须先改 spec，再改代码”这个纪律。否则文档永远滞后。