Go Template 使用指南

本文档介绍在 MCP Gateway 中如何使用 Go Template 来处理请求和响应数据。Go Template 提供了强大的模板功能，可以帮助我们灵活地处理数据转换和格式化。

基础语法

Go Template 使用 {{}} 作为定界符，在定界符内可以使用各种函数和变量。在 MCP Gateway 中，我们主要使用以下几种变量：

配置变量

.Config: 服务级别的配置
.Args: 请求参数

运行时变量

.Request: 原始请求信息
.Response: 上游服务响应信息

常见用例

1. 从环境变量获取配置

config:
  Authorization: 'Bearer {{ env "AUTH_TOKEN" }}'  # 从环境变量中获取配置

使用 env 函数可以安全地从环境变量中获取敏感信息，避免在配置文件中硬编码。

2. 从请求头中提取值

headers:
  Authorization: "{{.Request.Headers.Authorization}}"   # 透传客户端的 Authorization 头
  Cookie: "{{.Config.Cookie}}"                          # 使用服务配置中的值

3. 构建请求体

requestBody: |-
  {
    "username": "{{.Args.username}}",
    "email": "{{.Args.email}}"
  }

4. 处理响应数据

responseBody: |-
  {
    "id": "{{.Response.Data.id}}",
    "username": "{{.Response.Data.username}}",
    "email": "{{.Response.Data.email}}",
    "createdAt": "{{.Response.Data.createdAt}}"
  }

5. 处理嵌套的响应数据

对于复杂的嵌套数据结构，可以层层访问：

responseBody: |-
  {
    "id": "{{.Response.Data.id}}",
    "username": "{{.Response.Data.username}}",
    "email": "{{.Response.Data.email}}",
    "createdAt": "{{.Response.Data.createdAt}}",
    "preferences": {
      "isPublic": {{.Response.Data.preferences.isPublic}},
      "showEmail": {{.Response.Data.preferences.showEmail}},
      "theme": "{{.Response.Data.preferences.theme}}",
      "tags": {{.Response.Data.preferences.tags}}
    }
  }

6. 处理数组数据

当需要处理响应中的数组数据时，可以使用 Go Template 的 range 功能：

responseBody: |-
  {
    "total": "{{.Response.Data.total}}",
    "rows": [
      {{- $len := len .Response.Data.rows -}}
      {{- $rows := fromJSON .Response.Data.rows }}
      {{- range $i, $e := $rows }}
      {
        "id": {{ $e.id }},
        "detail": "{{ $e.detail }}",
        "deviceName": "{{ $e.deviceName }}"
      }{{ if lt (add $i 1) $len }},{{ end }}
      {{- end }}
    ]
  }

数组处理技巧说明

这个例子展示了如何：

使用 fromJSON 函数将 JSON 字符串转换为可遍历的对象
使用 range 遍历数组
使用 len 函数获取数组长度
使用 add 函数进行数学运算
使用条件语句 if 来控制数组元素之间的逗号分隔

7. 在 URL 中使用参数

动态构建 URL 路径：

endpoint: "http://localhost:5236/users/{{.Args.email}}/preferences"

8. 处理复杂对象数据

当需要将请求或者响应的对象、数组之类的复杂结构转成 JSON 的话，可以使用 toJSON 函数：

requestBody: |-
  {
    "isPublic": {{.Args.isPublic}},
    "showEmail": {{.Args.showEmail}},
    "theme": "{{.Args.theme}}",
    "tags": {{.Args.tags}},
    "settings": {{ toJSON .Args.settings }}
  }

此处的 settings 是一个复杂对象，使用 toJSON 函数后，会自动将 settings 转换为 JSON 字符串。

9. 安全获取嵌套字段（safeGet/safeGetOr）

当嵌套对象中的某一层为 null（或不存在）时，直接访问会在模板渲染阶段报错。例如：

responseBody: |-
  {
    "id": "{{.Response.Data.id}}",
    "username": "{{.Response.Data.username}}",
    "email": "{{.Response.Data.email}}",
    "createdAt": "{{.Response.Data.createdAt}}",
    "theme": "{{.Response.Data.preferences.theme}}"  # 如果 preferences 为 null，会报错
  }

为了解决这个问题，新增了两个函数：safeGet 和 safeGetOr。

safeGet <path> <root>：安全读取嵌套字段；若任意中间层为 nil/不存在，则返回空值（不会报错）。
safeGetOr <path> <root> <default>：在 safeGet 的基础上提供默认值；当取值失败时返回 <default>。

示例数据（正常情况）：

{
  "id": "28050608-7f39-42cf-be06-4982135dada9",
  "username": "2",
  "email": "1",
  "createdAt": "2025-09-12T11:43:16.086506+08:00",
  "preferences": {
    "isPublic": false,
    "showEmail": true,
    "theme": "light",
    "tags": [],
    "settings": {},
    "notifications": []
  }
}

当 preferences 为 null 时：

{
  "id": "28050608-7f39-42cf-be06-4982135dada9",
  "username": "2",
  "email": "1",
  "createdAt": "2025-09-12T11:43:16.086506+08:00",
  "preferences": null
}

这时：

# 使用 safeGet：不会报错，渲染为空值（显示为 <no value>）
responseBody: |-
  {
    "id": "{{.Response.Data.id}}",
    "username": "{{.Response.Data.username}}",
    "email": "{{.Response.Data.email}}",
    "createdAt": "{{.Response.Data.createdAt}}",
    "theme": "{{ safeGet "Response.Data.preferences.theme" . }}"
  }

# 使用 safeGetOr：提供默认值
responseBody: |-
  {
    "id": "{{.Response.Data.id}}",
    "username": "{{.Response.Data.username}}",
    "email": "{{.Response.Data.email}}",
    "createdAt": "{{.Response.Data.createdAt}}",
    "theme": "{{ safeGetOr "Response.Data.preferences.theme" . "light" }}"
  }

内置函数

目前支持以下内置函数：

env - 环境变量

获取环境变量的值

Authorization: 'Bearer {{ env "AUTH_TOKEN" }}'

add - 数学运算

执行整数加法运算

{{ if lt (add $i 1) $len }},{{ end }}

fromJSON - JSON 解析

将 JSON 字符串转换为可遍历的对象

{{- $rows := fromJSON .Response.Data.rows }}

toJSON - JSON 序列化

将对象转换为 JSON 字符串

"settings": {{ toJSON .Args.settings }}

safeGet - 安全读取字段

安全地读取嵌套字段；若任意中间层为 nil 或不存在，返回空值而不报错。

{{ safeGet "Response.Data.preferences.theme" . }}

safeGetOr - 安全读取字段并提供默认值

在 safeGet 的基础上提供默认值；当取值失败时返回默认值。

{{ safeGetOr "Response.Data.preferences.theme" . "light" }}

模板调试技巧

使用日志输出

在开发过程中，可以通过日志查看模板变量的实际值

分步构建

对于复杂的模板，建议先构建简单版本，然后逐步添加复杂逻辑

测试边界情况

确保模板在各种数据情况下都能正确工作，包括空值、null 值等

最佳实践

安全性

避免在模板中直接暴露敏感信息
使用环境变量存储密钥和密码
对用户输入进行适当的验证和转义

性能

避免在模板中进行复杂的计算
合理使用缓存机制
对于大量数据处理，考虑在上游服务中预处理

维护性

保持模板简洁明了
添加适当的注释说明
使用有意义的变量名

扩展功能

如果需要添加新的模板函数，可以：

描述具体的使用场景，创建 issue 说明需求
欢迎实现后 PR，但目前只接受通用用途的函数

Go Template 官方文档

查看 Go Template 的完整文档和高级用法

快速开始

安装部署

配置说明

Web 配置

客户端使用

开发文档

API 文档

端点示例

基础语法

配置变量

运行时变量

常见用例

1. 从环境变量获取配置

2. 从请求头中提取值

3. 构建请求体

4. 处理响应数据

5. 处理嵌套的响应数据

6. 处理数组数据

7. 在 URL 中使用参数

8. 处理复杂对象数据

9. 安全获取嵌套字段（safeGet/safeGetOr）

内置函数

模板调试技巧

最佳实践

扩展功能

更多资源

Go Template 官方文档

​基础语法

配置变量

运行时变量

​常见用例

​1. 从环境变量获取配置

​2. 从请求头中提取值

​3. 构建请求体

​4. 处理响应数据

​5. 处理嵌套的响应数据

​6. 处理数组数据

​7. 在 URL 中使用参数

​8. 处理复杂对象数据

​9. 安全获取嵌套字段（safeGet/safeGetOr）

​内置函数

​模板调试技巧

​最佳实践

​扩展功能

​更多资源

Go Template 官方文档

基础语法

常见用例

1. 从环境变量获取配置

2. 从请求头中提取值

3. 构建请求体

4. 处理响应数据

5. 处理嵌套的响应数据

6. 处理数组数据

7. 在 URL 中使用参数

8. 处理复杂对象数据

9. 安全获取嵌套字段（safeGet/safeGetOr）

内置函数

模板调试技巧

最佳实践

扩展功能

更多资源