Skip to content
This repository was archived by the owner on Jul 14, 2025. It is now read-only.

Commit 8b352c0

Browse files
iFuryStiFurySt
committed
Add Go Template usage guide
1 parent 43f4515 commit 8b352c0

File tree

9 files changed

+1049
-0
lines changed

9 files changed

+1049
-0
lines changed

‎docs/configuration/templates.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Go Template 使用指南
2+
3+
本文档介绍在 MCP Gateway 中如何使用 Go Template 来处理请求和响应数据。Go Template 提供了强大的模板功能，可以帮助我们灵活地处理数据转换和格式化。
4+
5+
## 基础语法
6+
7+
Go Template 使用 `{{}}` 作为定界符，在定界符内可以使用各种函数和变量。在 MCP Gateway 中，我们主要使用以下几种变量：
8+
9+
- `.Config`: 服务级别的配置
10+
- `.Args`: 请求参数
11+
- `.Request`: 原始请求信息
12+
- `.Response`: 上游服务响应信息
13+
14+
## 常见用例
15+
16+
### 1. 从环境变量获取配置
17+
18+
```yaml
19+
config:
20+
Authorization: 'Bearer {{ env "AUTH_TOKEN" }}' # 从环境变量中获取配置
21+
```
22+
23+
### 2. 从请求头中提取值
24+
25+
```yaml
26+
headers:
27+
Authorization: "{{.Request.Headers.Authorization}}" # 透传客户端的 Authorization 头
28+
Cookie: "{{.Config.Cookie}}" # 使用服务配置中的值
29+
```
30+
31+
### 3. 构建请求体
32+
33+
```yaml
34+
requestBody: |-
35+
{
36+
"username": "{{.Args.username}}",
37+
"email": "{{.Args.email}}"
38+
}
39+
```
40+
41+
### 4. 处理响应数据
42+
43+
```yaml
44+
responseBody: |-
45+
{
46+
"id": "{{.Response.Data.id}}",
47+
"username": "{{.Response.Data.username}}",
48+
"email": "{{.Response.Data.email}}",
49+
"createdAt": "{{.Response.Data.createdAt}}"
50+
}
51+
```
52+
53+
### 5. 处理嵌套的响应数据
54+
55+
```yaml
56+
responseBody: |-
57+
{
58+
"id": "{{.Response.Data.id}}",
59+
"username": "{{.Response.Data.username}}",
60+
"email": "{{.Response.Data.email}}",
61+
"createdAt": "{{.Response.Data.createdAt}}",
62+
"preferences": {
63+
"isPublic": {{.Response.Data.preferences.isPublic}},
64+
"showEmail": {{.Response.Data.preferences.showEmail}},
65+
"theme": "{{.Response.Data.preferences.theme}}",
66+
"tags": {{.Response.Data.preferences.tags}}
67+
}
68+
}
69+
```
70+
71+
### 6. 处理数组数据
72+
73+
当需要处理响应中的数组数据时，可以使用 Go Template 的 range 功能：
74+
75+
```yaml
76+
responseBody: |-
77+
{
78+
"total": "{{.Response.Data.total}}",
79+
"rows": [
80+
{{- $len := len .Response.Data.rows -}}
81+
{{- $rows := fromJSON .Response.Data.rows }}
82+
{{- range $i, $e := $rows }}
83+
{
84+
"id": {{ $e.id }},
85+
"detail": "{{ $e.detail }}",
86+
"deviceName": "{{ $e.deviceName }}"
87+
}{{ if lt (add $i 1) $len }},{{ end }}
88+
{{- end }}
89+
]
90+
}
91+
```
92+
93+
这个例子展示了如何：
94+
1. 使用 `fromJSON` 函数将 JSON 字符串转换为可遍历的对象
95+
2. 使用 `range` 遍历数组
96+
3. 使用 `len` 函数获取数组长度
97+
4. 使用 `add` 函数进行数学运算
98+
5. 使用条件语句 `if` 来控制数组元素之间的逗号分隔
99+
100+
### 7. 在 URL 中使用参数
101+
102+
```yaml
103+
endpoint: "http://localhost:5236/users/{{.Args.email}}/preferences"
104+
```
105+
106+
## 内置函数
107+
108+
目前支持以下内置函数：
109+
110+
1. `env`: 获取环境变量的值
111+
```yaml
112+
Authorization: 'Bearer {{ env "AUTH_TOKEN" }}'
113+
```
114+
115+
2. `add`: 执行整数加法运算
116+
```yaml
117+
{{ if lt (add $i 1) $len }},{{ end }}
118+
```
119+
120+
3. `fromJSON`: 将 JSON 字符串转换为可遍历的对象
121+
```yaml
122+
{{- $rows := fromJSON .Response.Data.rows }}
123+
```
124+
125+
如果需要添加新的模板函数，可以
126+
1. 描述具体的使用场景，创建 issue 说明需求
127+
3. 欢迎实现后PR，但目前只接受通用用途的函数
128+
129+
## 更多资源
130+
131+
- [Go Template 官方文档](https://pkg.go.dev/text/template)

‎i18n/de/configuration/templates.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Go Template Anleitung
2+
3+
Dieses Dokument beschreibt die Verwendung von Go Template in MCP Gateway zur Verarbeitung von Anfrage- und Antwortdaten. Go Template bietet leistungsstarke Template-Funktionen, die uns helfen, Daten flexibel zu transformieren und zu formatieren.
4+
5+
## Grundlegende Syntax
6+
7+
Go Template verwendet `{{}}` als Begrenzer, innerhalb derer verschiedene Funktionen und Variablen verwendet werden können. In MCP Gateway verwenden wir hauptsächlich die folgenden Variablen:
8+
9+
- `.Config`: Service-Level-Konfiguration
10+
- `.Args`: Anfrageparameter
11+
- `.Request`: Originale Anfrageinformationen
12+
- `.Response`: Upstream-Service-Antwortinformationen
13+
14+
## Häufige Anwendungsfälle
15+
16+
### 1. Konfiguration aus Umgebungsvariablen abrufen
17+
18+
```yaml
19+
config:
20+
Authorization: 'Bearer {{ env "AUTH_TOKEN" }}' # Konfiguration aus Umgebungsvariable abrufen
21+
```
22+
23+
### 2. Werte aus Anfrage-Headern extrahieren
24+
25+
```yaml
26+
headers:
27+
Authorization: "{{.Request.Headers.Authorization}}" # Authorization-Header des Clients weiterleiten
28+
Cookie: "{{.Config.Cookie}}" # Wert aus der Service-Konfiguration verwenden
29+
```
30+
31+
### 3. Anfrage-Body erstellen
32+
33+
```yaml
34+
requestBody: |-
35+
{
36+
"username": "{{.Args.username}}",
37+
"email": "{{.Args.email}}"
38+
}
39+
```
40+
41+
### 4. Antwortdaten verarbeiten
42+
43+
```yaml
44+
responseBody: |-
45+
{
46+
"id": "{{.Response.Data.id}}",
47+
"username": "{{.Response.Data.username}}",
48+
"email": "{{.Response.Data.email}}",
49+
"createdAt": "{{.Response.Data.createdAt}}"
50+
}
51+
```
52+
53+
### 5. Verschachtelte Antwortdaten verarbeiten
54+
55+
```yaml
56+
responseBody: |-
57+
{
58+
"id": "{{.Response.Data.id}}",
59+
"username": "{{.Response.Data.username}}",
60+
"email": "{{.Response.Data.email}}",
61+
"createdAt": "{{.Response.Data.createdAt}}",
62+
"preferences": {
63+
"isPublic": {{.Response.Data.preferences.isPublic}},
64+
"showEmail": {{.Response.Data.preferences.showEmail}},
65+
"theme": "{{.Response.Data.preferences.theme}}",
66+
"tags": {{.Response.Data.preferences.tags}}
67+
}
68+
}
69+
```
70+
71+
### 6. Array-Daten verarbeiten
72+
73+
Bei der Verarbeitung von Array-Daten in Antworten können Sie die range-Funktionalität von Go Template verwenden:
74+
75+
```yaml
76+
responseBody: |-
77+
{
78+
"total": "{{.Response.Data.total}}",
79+
"rows": [
80+
{{- $len := len .Response.Data.rows -}}
81+
{{- $rows := fromJSON .Response.Data.rows }}
82+
{{- range $i, $e := $rows }}
83+
{
84+
"id": {{ $e.id }},
85+
"detail": "{{ $e.detail }}",
86+
"deviceName": "{{ $e.deviceName }}"
87+
}{{ if lt (add $i 1) $len }},{{ end }}
88+
{{- end }}
89+
]
90+
}
91+
```
92+
93+
Dieses Beispiel zeigt:
94+
1. Verwendung der `fromJSON`-Funktion zum Konvertieren eines JSON-Strings in ein durchsuchbares Objekt
95+
2. Verwendung von `range` zum Durchlaufen des Arrays
96+
3. Verwendung der `len`-Funktion zum Abrufen der Array-Länge
97+
4. Verwendung der `add`-Funktion für mathematische Operationen
98+
5. Verwendung von bedingten Anweisungen zur Steuerung der Kommatrennung zwischen Array-Elementen
99+
100+
### 7. Parameter in URLs verwenden
101+
102+
```yaml
103+
endpoint: "http://localhost:5236/users/{{.Args.email}}/preferences"
104+
```
105+
106+
## Eingebaute Funktionen
107+
108+
Aktuell unterstützte eingebaute Funktionen:
109+
110+
1. `env`: Umgebungsvariablenwert abrufen
111+
```yaml
112+
Authorization: 'Bearer {{ env "AUTH_TOKEN" }}'
113+
```
114+
115+
2. `add`: Ganzzahladdition durchführen
116+
```yaml
117+
{{ if lt (add $i 1) $len }},{{ end }}
118+
```
119+
120+
3. `fromJSON`: JSON-String in durchsuchbares Objekt konvertieren
121+
```yaml
122+
{{- $rows := fromJSON .Response.Data.rows }}
123+
```
124+
125+
Um neue Template-Funktionen hinzuzufügen:
126+
1. Spezifischen Anwendungsfall beschreiben und ein Issue erstellen
127+
2. PR-Beiträge sind willkommen, aber derzeit werden nur allgemeine Funktionen akzeptiert
128+
129+
## Weitere Ressourcen
130+
131+
- [Offizielle Go Template Dokumentation](https://pkg.go.dev/text/template)

‎i18n/en/configuration/templates.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Go Template Usage Guide
2+
3+
This document introduces how to use Go Template in MCP Gateway to handle request and response data. Go Template provides powerful templating capabilities that help us flexibly process data transformation and formatting.
4+
5+
## Basic Syntax
6+
7+
Go Template uses `{{}}` as delimiters, within which various functions and variables can be used. In MCP Gateway, we mainly use the following variables:
8+
9+
- `.Config`: Service-level configuration
10+
- `.Args`: Request parameters
11+
- `.Request`: Original request information
12+
- `.Response`: Upstream service response information
13+
14+
## Common Use Cases
15+
16+
### 1. Getting Configuration from Environment Variables
17+
18+
```yaml
19+
config:
20+
Authorization: 'Bearer {{ env "AUTH_TOKEN" }}' # Get configuration from environment variable
21+
```
22+
23+
### 2. Extracting Values from Request Headers
24+
25+
```yaml
26+
headers:
27+
Authorization: "{{.Request.Headers.Authorization}}" # Forward client's Authorization header
28+
Cookie: "{{.Config.Cookie}}" # Use value from service configuration
29+
```
30+
31+
### 3. Building Request Body
32+
33+
```yaml
34+
requestBody: |-
35+
{
36+
"username": "{{.Args.username}}",
37+
"email": "{{.Args.email}}"
38+
}
39+
```
40+
41+
### 4. Processing Response Data
42+
43+
```yaml
44+
responseBody: |-
45+
{
46+
"id": "{{.Response.Data.id}}",
47+
"username": "{{.Response.Data.username}}",
48+
"email": "{{.Response.Data.email}}",
49+
"createdAt": "{{.Response.Data.createdAt}}"
50+
}
51+
```
52+
53+
### 5. Processing Nested Response Data
54+
55+
```yaml
56+
responseBody: |-
57+
{
58+
"id": "{{.Response.Data.id}}",
59+
"username": "{{.Response.Data.username}}",
60+
"email": "{{.Response.Data.email}}",
61+
"createdAt": "{{.Response.Data.createdAt}}",
62+
"preferences": {
63+
"isPublic": {{.Response.Data.preferences.isPublic}},
64+
"showEmail": {{.Response.Data.preferences.showEmail}},
65+
"theme": "{{.Response.Data.preferences.theme}}",
66+
"tags": {{.Response.Data.preferences.tags}}
67+
}
68+
}
69+
```
70+
71+
### 6. Processing Array Data
72+
73+
When processing array data in responses, you can use Go Template's range functionality:
74+
75+
```yaml
76+
responseBody: |-
77+
{
78+
"total": "{{.Response.Data.total}}",
79+
"rows": [
80+
{{- $len := len .Response.Data.rows -}}
81+
{{- $rows := fromJSON .Response.Data.rows }}
82+
{{- range $i, $e := $rows }}
83+
{
84+
"id": {{ $e.id }},
85+
"detail": "{{ $e.detail }}",
86+
"deviceName": "{{ $e.deviceName }}"
87+
}{{ if lt (add $i 1) $len }},{{ end }}
88+
{{- end }}
89+
]
90+
}
91+
```
92+
93+
This example demonstrates:
94+
1. Using `fromJSON` function to convert JSON string to traversable object
95+
2. Using `range` to iterate over array
96+
3. Using `len` function to get array length
97+
4. Using `add` function for mathematical operations
98+
5. Using conditional statements to control comma separation between array elements
99+
100+
### 7. Using Parameters in URLs
101+
102+
```yaml
103+
endpoint: "http://localhost:5236/users/{{.Args.email}}/preferences"
104+
```
105+
106+
## Built-in Functions
107+
108+
Currently supported built-in functions:
109+
110+
1. `env`: Get environment variable value
111+
```yaml
112+
Authorization: 'Bearer {{ env "AUTH_TOKEN" }}'
113+
```
114+
115+
2. `add`: Perform integer addition
116+
```yaml
117+
{{ if lt (add $i 1) $len }},{{ end }}
118+
```
119+
120+
3. `fromJSON`: Convert JSON string to traversable object
121+
```yaml
122+
{{- $rows := fromJSON .Response.Data.rows }}
123+
```
124+
125+
To add new template functions:
126+
1. Describe the specific use case and create an issue
127+
2. Welcome PR contributions, but currently only accepting general-purpose functions
128+
129+
## Additional Resources
130+
131+
- [Go Template Official Documentation](https://pkg.go.dev/text/template)

0 commit comments

Comments
 (0)