Golang Web项目如何对接前端接口_前后端交互规范说明

接口响应必须统一为JSON格式，顶层字段固定为code、msg、data；code为整数状态码，msg为提示信息，data为业务数据；传参须明确路径（JSON body或form），时间字段严格使用RFC3339格式。

接口返回结构必须统一用 JSON，且顶层字段固定

Go 后端不能直接返回裸数据或 map[string]interface{}，前端无法稳定解析。所有 HTTP 接口（GET/POST 等）响应体必须是标准 JSON，顶层结构一致：

{
  "code": 0,
  "msg": "success",
  "data": {}
}

code 为整数：0 表示成功，非 0 表示业务错误（如 4001 表示参数缺失，401 表示未登录）；msg 是可读提示，不用于程序判断；data 为实际业务数据，失败时可为

null 或空对象。

• 不要在中间件或 handler 里用 json.NewEncoder(w).Encode(...) 直接输出原始 map，容易漏字段、类型错乱
• 定义统一响应结构体，例如：type Resp struct { Code int `json:"code"` Msg string `json:"msg"` Data interface{} `json:"data"` }
• 避免在 data 中嵌套 code/msg —— 这会破坏前端统一拦截逻辑

前端传参必须走 Content-Type: application/json 或 application/x-www-form-urlencoded

除非是文件上传，否则禁止用 GET 传复杂参数（如过滤条件数组、嵌套对象）。Gin/Echo 等框架默认不自动解析 GET 查询字符串到结构体深层字段，容易出错。

• POST /api/user/list 应该用 application/json 传 body：

  {"page": 1, "size": 20, "tags": ["go", "web"]}

• 若用 form 提交（如登录页），则用 application/x-www-form-urlencoded，后端用 c.ShouldBind(&req)（Gin）或 r.ParseForm() + 显式取值
• 禁止混合使用：URL query + JSON body，会导致参数来源混乱，调试困难
• Gin 中若用 c.ShouldBindJSON()，请求头没带 Content-Type: application/json 会静默失败（返回空结构体），务必检查 header

401 和 403 必须严格区分，且响应体仍需符合统一格式

前端依赖状态码做路由跳转或弹窗，但不能只靠状态码判断错误类型 —— 某些代理或 CDN 会重写 status code，所以 code 字段和 HTTP 状态码要协同一致。

• 未登录：HTTP 状态码设为 401，code 字段填 401，msg 可为 "login required"
• 权限不足：HTTP 状态码用 403，code 填 403，msg 如 "no permission"
• 其他业务错误（如库存不足）：HTTP 状态码仍用 200，靠 code 区分，避免触发前端全局 error 拦截器误跳转
• 所有情况都必须返回完整 {code, msg, data} 结构，不能只写 http.Error(w, "...", 401)

时间字段统一用 RFC3339 格式字符串，禁止传 Unix 时间戳或自定义格式

前端 Date 对象对时间字符串解析容错性差，2025-05-20 14:30:00 或 1716225000 都可能被误读为本地时间或 NaN。

• Go 中序列化时间字段必须用：time.Time.Format(time.RFC3339)，例如 "2025-05-20T14:30:00+08:00"
• 结构体中时间字段应声明为 time.Time，并加 JSON tag：CreatedAt time.Time `json:"created_at"`
• 不要在 SQL 查询里用 UNIX_TIMESTAMP() 或 DATE_FORMAT() 拼字符串 —— 交给 Go 层统一格式化
• 前端收到后可用 new Date(str) 直接解析，无需额外适配

跨域、CSRF、敏感字段脱敏这些点不在接口规范主干里，属于部署和安全配置范畴。真正让前后端不撕逼的，是坚持这四条：结构定死、传参路径清晰、状态码与业务码对齐、时间格式无歧义。其余都是锦上添花。