Context.JSON() 是 Echo 框架内置标准方法,自动设置 Content-Type、序列化并写入响应;支持自定义状态码,需避免 nil 指针、不可序列化类型及错误的 charset 设置,推荐统一错误响应结构。

Context.JSON() 是最直接的返回方式
Context.JSON() 是 Echo 框架内置的标准方法,底层自动设置 Content-Type: application/json、调用 json.Marshal() 序列化,并写入 HTTP 响应体。它适合绝大多数结构化数据返回场景。
- 必须传入合法的 Go 值(如 struct、map、slice),不能是 nil 指针或未导出字段过多的匿名 struct(会导致序列化为空对象)
- 状态码默认是 200,但支持第一个参数传入自定义状态码,例如:
c.JSON(201, user) - 如果
json.Marshal()失败(比如含不可序列化的类型如func、chan、循环引用),会返回 500 错误并打印 panic 日志——这在生产环境容易被忽略,建议对关键响应做预检查
遇到中文乱码?检查 JSON 字符编码
Echo 默认使用 UTF-8 编码,但若响应中出现方块或问号,大概率是前端没正确识别 charset,或中间件/代理覆盖了 header。
- 不要手动拼接
Content-Type: application/json; charset=utf-8:Echo 的JSON()已内置 charset,重复设置可能触发浏览器解析异常 - 避免在
JSON()前调用c.Header("Content-Type", ...),否则会覆盖 Echo 内部设置 - Nginx 或 CDN 如果启用了 gzip 且未配置
gzip_vary on,也可能导致 charset 丢失,需同步检查服务端配置
需要控制时间格式或忽略空字段?用自定义 struct tag
JSON() 底层走标准 encoding/json,所以完全支持原生 tag:
将包含oralBroadcastingList、materialList、bgmInfo等字段的JSON视频素材转换为剪映API可用的自然语言描述,用于生成视频制作指令,包括素材匹配、时间轴计算、字幕同步、特殊效果处理等。
- 时间字段常用:
CreatedAt time.Time <code>json:"created_at" time_format:"2006-01-02T15:04:05Z" - 忽略零值字段:
Name string <code>json:"name,omitempty" - 完全排除字段:
Password string <code>json:"-" - 注意:如果字段是指针(如
*string),omitempty仅在指针为 nil 时生效;若指针非 nil 但指向空字符串,仍会序列化出来
返回错误 JSON?别直接用 JSON() 包装 error 类型
Go 的 error 接口本身无法被 json.Marshal() 正常处理(只会输出 {"Error":"..."} 这种不兼容前端约定的结构),而且易暴露内部信息。
- 正确做法是构造统一错误响应结构,例如:
c.JSON(400, map[string]string{"error": "invalid email"}) - 更推荐封装一个响应助手函数,统一处理 success/error 格式,避免每个 handler 重复写
map[string]interface{} - 切忌把
err.Error()直接塞进 JSON 返回给前端——调试时可临时加,上线前必须移除或替换为用户友好的提示
实际开发中,真正麻烦的不是怎么调 JSON(),而是响应结构是否稳定、字段命名是否前后端对齐、时间/浮点数精度是否一致。这些细节一旦上线就很难改。

















