编辑“︁Gin模板与JSON混合响应”︁（章节）

= Gin模板与JSON混合响应 =

在Web开发中，经常需要根据客户端需求返回不同格式的响应。Gin框架允许开发者灵活地结合'''HTML模板渲染'''和'''JSON数据'''响应，这种混合模式特别适合需要同时服务Web页面和API请求的应用场景。

== 概念解析 ==

Gin的混合响应机制基于HTTP的`Accept`头或路径后缀（如`.json`）判断响应格式。其核心原理可表示为：

<math>
\text{ResponseType} = \begin{cases}
\text{HTML} & \text{if } \text{Accept: text/html} \\
\text{JSON} & \text{if } \text{Accept: application/json}
\end{cases}
</math>

=== 技术优势 ===
* '''前后端解耦'''：同一路由处理Web和API请求
* '''代码复用'''：共享业务逻辑和数据模型
* '''渐进增强'''：逐步从传统服务端渲染迁移到前后端分离

== 基础实现 ==

以下示例展示如何根据请求头返回不同格式：

<syntaxhighlight lang="go">
package main

import (
	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()
	r.LoadHTMLGlob("templates/*")

	r.GET("/user", func(c *gin.Context) {
		data := gin.H{
			"name":  "Alice",
			"email": "alice@example.com",
		}

		switch c.NegotiateFormat(gin.MIMEHTML, gin.MIMEJSON) {
		case gin.MIMEHTML:
			c.HTML(200, "user.html", data)
		case gin.MIMEJSON:
			c.JSON(200, data)
		}
	})

	r.Run(":8080")
}
</syntaxhighlight>

=== 文件结构 ===
<pre>
project/
├── main.go
└── templates/
    └── user.html
</pre>

== 高级内容：内容协商 ==

Gin通过`NegotiateFormat`实现RFC 7231定义的内容协商：

<mermaid>
sequenceDiagram
    Client->>Server: GET /user (Accept: text/html)
    Server->>Client: 200 OK (text/html)
    Client->>Server: GET /user (Accept: application/json)
    Server->>Client: 200 OK (application/json)
</mermaid>

=== 格式检测优先级 ===
1. URL后缀（如`.json`）
2. `Accept`请求头
3. 默认格式（可设置`Default()`）

== 实战案例：电商产品页 ==

假设需要实现一个同时支持网页和API访问的产品详情页：

<syntaxhighlight lang="go">
// 数据结构
type Product struct {
	ID          int     `json:"id"`
	Name        string  `json:"name"`
	Price       float64 `json:"price"`
	Description string  `json:"description"`
}

// 处理器
func getProduct(c *gin.Context) {
	product := Product{
		ID:          101,
		Name:       "Wireless Mouse",
		Price:      29.99,
		Description: "Ergonomic design with 12-month battery",
	}

	if c.Request.Header.Get("Accept") == "application/json" {
		c.JSON(200, product)
	} else {
		c.HTML(200, "product.html", gin.H{
			"product": product,
		})
	}
}
</syntaxhighlight>

=== 模板示例（templates/product.html） ===
<syntaxhighlight lang="html">
<!DOCTYPE html>
<html>
<head>
    <title>{{ .product.Name }}</title>
</head>
<body>
    <h1>{{ .product.Name }}</h1>
    <p>Price: ${{ .product.Price }}</p>
    <p>{{ .product.Description }}</p>
</body>
</html>
</syntaxhighlight>

== 响应对比 ==

'''Web请求输出:'''
<pre>
HTTP/1.1 200 OK
Content-Type: text/html

<!DOCTYPE html>
<html>...<!-- 渲染后的HTML --></html>
</pre>

'''API请求输出:'''
<pre>
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 101,
  "name": "Wireless Mouse",
  "price": 29.99,
  "description": "Ergonomic design..."
}
</pre>

== 最佳实践 ==

1. '''统一数据源'''：确保模板和JSON使用相同的数据结构
2. '''错误处理'''：实现格式感知的错误响应
3. '''性能优化'''：对JSON响应启用`gin.IndentedJSON`调试或`gin.PureJSON`生产环境
4. '''版本控制'''：通过`Accept`头包含API版本（如`application/vnd.api.v1+json`）

== 常见问题 ==

'''Q: 如何强制返回特定格式？'''
A: 使用URL后缀或查询参数：
<syntaxhighlight lang="go">
format := c.Query("format")
if format == "json" {
    c.JSON(200, data)
} else {
    c.HTML(200, "page.html", data)
}
</syntaxhighlight>

'''Q: 混合响应会增加服务器负载吗？'''
A: 模板渲染比纯JSON略耗资源，但差异通常在毫秒级。可通过缓存策略优化。

== 扩展阅读 ==

* HTTP内容协商 (RFC 7231)
* Gin框架的[Render接口](https://github.com/gin-gonic/gin#rendering)
* 响应式Web设计原则

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin模板渲染]]