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，再改代码”这个纪律。否则文档永远滞后。
