mirror of
https://github.com/alibaba/higress.git
synced 2026-02-25 05:01:19 +08:00
196 lines
4.5 KiB
Markdown
196 lines
4.5 KiB
Markdown
# DeGraphQL
|
||
|
||
## GraphQL
|
||
|
||
### GraphQL 端点
|
||
|
||
REST API 有多个端点，GraphQL API 只有一个端点。
|
||
|
||
```shell
|
||
https://api.github.com/graphql
|
||
```
|
||
### 与 GraphQL 通信
|
||
|
||
由于 GraphQL 操作由多行 JSON 组成，可以使用 curl 或任何其他采用 HTTP 的库。
|
||
|
||
在 REST 中，HTTP 谓词确定执行的操作。 在 GraphQL 中，执行查询要提供 JSON 请求体，因此 HTTP 谓词为 POST。 唯一的例外是内省查询，它是一种简单的 GET 到终结点查询。
|
||
|
||
### GraphQL POST 请求参数
|
||
|
||
标准的 GraphQL POST 请求情况如下：
|
||
|
||
- 添加 HTTP 请求头： Content-Type: application/json
|
||
- 使用 JSON 格式的请求体
|
||
- JSON 请求体包含三个字段
|
||
- query：查询文档，必填
|
||
- variables：变量，选填
|
||
- operationName：操作名称，选填，查询文档有多个操作时必填
|
||
|
||
```json
|
||
{
|
||
"query": "{viewer{name}}",
|
||
"operationName": "",
|
||
"variables": {
|
||
"name": "value"
|
||
}
|
||
}
|
||
```
|
||
|
||
### GraphQL 基本参数类型
|
||
|
||
- 基本参数类型包含： String, Int, Float, Boolean
|
||
- [类型]代表数组，例如：[Int]代表整型数组
|
||
- GraphQL 基本参数传递
|
||
- 小括号内定义形参，注意：参数需要定义类型
|
||
- !（叹号）代表参数不能为空
|
||
|
||
```shell
|
||
query ($owner : String!, $name : String!) {
|
||
repository(owner: $owner, name: $name) {
|
||
name
|
||
forkCount
|
||
description
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
### GitHub GraphQL 测试
|
||
|
||
使用 curl 命令查询 GraphQL， 用有效 JSON 请求体发出 POST 请求。 有效请求体必须包含一个名为 query 的字符串。
|
||
|
||
```shell
|
||
|
||
curl https://api.github.com/graphql -X POST \
|
||
-H "Authorization: bearer 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" \
|
||
-d "{\"query\": \"query { viewer { login }}\"}"
|
||
|
||
{
|
||
"data": {
|
||
"viewer": {
|
||
"login": "2456868764"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
```shell
|
||
curl 'https://api.github.com/graphql' -X POST \
|
||
-H 'Authorization: bearer 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' \
|
||
-d '{"query":"query ($owner: String!, $name: String!) {\n repository(owner: $owner, name: $name) {\n name\n forkCount\n description\n }\n}\n","variables":{"owner":"2456868764","name":"higress"}}'
|
||
|
||
{
|
||
"data": {
|
||
"repository": {
|
||
"name": "higress",
|
||
"forkCount": 149,
|
||
"description": "Next-generation Cloud Native Gateway | 下一代云原生网关"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
## DeGraphQL 插件
|
||
|
||
### 参数配置
|
||
|
||
| 参数 | 描述 | 默认 |
|
||
|:----------------|:------------------------|:-----------|
|
||
| `gql` | graphql 查询 | 不能为空 |
|
||
| `endpoint` | graphql 查询端点 | `/graphql` |
|
||
| `timeout` | 查询连接超时，单位毫秒 | `5000` |
|
||
| `domain` | 服务域名，当服务来源是dns配置 | |
|
||
|
||
### 插件使用
|
||
|
||
https://github.com/alibaba/higress/issues/268
|
||
|
||
- 测试配置
|
||
```yaml
|
||
apiVersion: networking.higress.io/v1
|
||
kind: McpBridge
|
||
metadata:
|
||
name: default
|
||
namespace: higress-system
|
||
spec:
|
||
registries:
|
||
- domain: api.github.com
|
||
name: github
|
||
port: 443
|
||
type: dns
|
||
---
|
||
apiVersion: networking.k8s.io/v1
|
||
kind: Ingress
|
||
metadata:
|
||
annotations:
|
||
higress.io/destination: github.dns
|
||
higress.io/upstream-vhost: "api.github.com"
|
||
higress.io/backend-protocol: HTTPS
|
||
name: github-api
|
||
namespace: higress-system
|
||
spec:
|
||
ingressClassName: higress
|
||
rules:
|
||
- http:
|
||
paths:
|
||
- backend:
|
||
resource:
|
||
apiGroup: networking.higress.io
|
||
kind: McpBridge
|
||
name: default
|
||
path: /api
|
||
pathType: Prefix
|
||
---
|
||
apiVersion: extensions.higress.io/v1alpha1
|
||
kind: WasmPlugin
|
||
metadata:
|
||
name: de-graphql-github-api
|
||
namespace: higress-system
|
||
spec:
|
||
matchRules:
|
||
- ingress:
|
||
- github-api
|
||
config:
|
||
timeout: 5000
|
||
endpoint: /graphql
|
||
domain: api.github.com
|
||
gql: |
|
||
query ($owner:String! $name:String!){
|
||
repository(owner:$owner, name:$name) {
|
||
name
|
||
forkCount
|
||
description
|
||
}
|
||
}
|
||
url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/de-graphql:1.0.0
|
||
```
|
||
|
||
- 测试结果
|
||
|
||
```shell
|
||
curl "http://localhost/api?owner=alibaba&name=higress" -H "Authorization: Bearer some-token"
|
||
|
||
{
|
||
"data": {
|
||
"repository": {
|
||
"description": "Next-generation Cloud Native Gateway",
|
||
"forkCount": 149,
|
||
"name": "higress"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 参考文档
|
||
|
||
- https://github.com/graphql/graphql-spec
|
||
- https://docs.github.com/zh/graphql/guides/forming-calls-with-graphql
|
||
- https://github.com/altair-graphql/altair
|
||
|
||
|
||
|
||
|
||
|
||
|