degraphql
degraphql 插件将 HTTP 路由映射到预定义的 GraphQL 查询。客户端无需构造 GraphQL 文档即可调用该路由；插件会将已配置的查询和选定的请求值发送到上游 GraphQL 服务。
对于 POST 请求，已配置变量的值来自 JSON 请求体；对于 GET 请求，其值来自 URL 查询参数。
示例
以下示例使用维护中的 Pokémon GraphQL API（地址为 https://graphqlpokemon.favware.tech/v8）。第一个示例发送固定查询，第二个示例更新同一路由以接收变量。
发送固定查询
路由每次收到 POST 请求时都会发送以下查询：
{
getPokemon(pokemon: pikachu) {
key
color
species
}
}
创建路由：
- Admin API
- ADC
- Ingress Controller
curl "http://127.0.0.1:9180/apisix/admin/routes/degraphql-pokemon" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/v8",
"methods": ["POST"],
"plugins": {
"degraphql": {
"query": "{\n getPokemon(pokemon: pikachu) {\n key\n color\n species\n }\n}"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"graphqlpokemon.favware.tech:443": 1
},
"scheme": "https",
"pass_host": "node"
}
}'
adc.yaml
services:
- name: degraphql-pokemon
labels:
docs-example: degraphql
routes:
- name: degraphql-pokemon
uris:
- /v8
methods:
- POST
plugins:
degraphql:
query: |
{
getPokemon(pokemon: pikachu) {
key
color
species
}
}
upstream:
type: roundrobin
nodes:
- host: graphqlpokemon.favware.tech
port: 443
weight: 1
scheme: https
pass_host: node
预览此示例所拥有资源的变更，并确认差异中没有意外更新或删除：
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=degraphql
同步已检查的服务配置：
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=degraphql
- Gateway API
- APISIX CRD
degraphql-ic.yaml
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: graphql-pokemon
spec:
type: ExternalName
externalName: graphqlpokemon.favware.tech
ports:
- name: https
port: 443
targetPort: 443
---
apiVersion: apisix.apache.org/v1alpha1
kind: BackendTrafficPolicy
metadata:
namespace: aic
name: graphql-pokemon-https
spec:
targetRefs:
- name: graphql-pokemon
kind: Service
group: ""
sectionName: https
passHost: node
scheme: https
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: degraphql-pokemon
spec:
plugins:
- name: degraphql
config:
query: |
{
getPokemon(pokemon: pikachu) {
key
color
species
}
}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: degraphql-pokemon
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /v8
method: POST
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: degraphql-pokemon
backendRefs:
- name: graphql-pokemon
port: 443
degraphql-ic.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: graphql-pokemon
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: graphqlpokemon.favware.tech
port: 443
scheme: https
passHost: node
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: degraphql-pokemon
spec:
ingressClassName: apisix
http:
- name: degraphql-pokemon
match:
paths:
- /v8
methods:
- POST
upstreams:
- name: graphql-pokemon
plugins:
- name: degraphql
enable: true
config:
query: |
{
getPokemon(pokemon: pikachu) {
key
color
species
}
}
应用配置：
kubectl apply -f degraphql-ic.yaml
发送不含 GraphQL 请求体的 POST 请求：
curl "http://127.0.0.1:9080/v8" -X POST
响应应包含所选的 Pokémon 字段：
{
"data": {
"getPokemon": {
"key": "pikachu",
"color": "Yellow",
"species": "pikachu"
}
}
}
传递变量
更新路由，使其使用名为 pokemon 的 GraphQL 变量：
query ($pokemon: PokemonEnum!) {
getPokemon(pokemon: $pokemon) {
key
color
species
}
}
- Admin API
- ADC
- Ingress Controller
curl "http://127.0.0.1:9180/apisix/admin/routes/degraphql-pokemon" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/v8",
"methods": ["GET", "POST"],
"plugins": {
"degraphql": {
"query": "query ($pokemon: PokemonEnum!) {\n getPokemon(pokemon: $pokemon) {\n key\n color\n species\n }\n}",
"variables": ["pokemon"]
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"graphqlpokemon.favware.tech:443": 1
},
"scheme": "https",
"pass_host": "node"
}
}'
adc.yaml
services:
- name: degraphql-pokemon
labels:
docs-example: degraphql
routes:
- name: degraphql-pokemon
uris:
- /v8
methods:
- GET
- POST
plugins:
degraphql:
query: |
query ($pokemon: PokemonEnum!) {
getPokemon(pokemon: $pokemon) {
key
color
species
}
}
variables:
- pokemon
upstream:
type: roundrobin
nodes:
- host: graphqlpokemon.favware.tech
port: 443
weight: 1
scheme: https
pass_host: node
预览更新：
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=degraphql
同步已检查的服务配置：
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=degraphql
- Gateway API
- APISIX CRD
degraphql-ic.yaml
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: graphql-pokemon
spec:
type: ExternalName
externalName: graphqlpokemon.favware.tech
ports:
- name: https
port: 443
targetPort: 443
---
apiVersion: apisix.apache.org/v1alpha1
kind: BackendTrafficPolicy
metadata:
namespace: aic
name: graphql-pokemon-https
spec:
targetRefs:
- name: graphql-pokemon
kind: Service
group: ""
sectionName: https
passHost: node
scheme: https
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: degraphql-pokemon
spec:
plugins:
- name: degraphql
config:
query: |
query ($pokemon: PokemonEnum!) {
getPokemon(pokemon: $pokemon) {
key
color
species
}
}
variables:
- pokemon
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: degraphql-pokemon
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /v8
method: GET
- path:
type: Exact
value: /v8
method: POST
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: degraphql-pokemon
backendRefs:
- name: graphql-pokemon
port: 443
degraphql-ic.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: graphql-pokemon
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: graphqlpokemon.favware.tech
port: 443
scheme: https
passHost: node
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: degraphql-pokemon
spec:
ingressClassName: apisix
http:
- name: degraphql-pokemon
match:
paths:
- /v8
methods:
- GET
- POST
upstreams:
- name: graphql-pokemon
plugins:
- name: degraphql
enable: true
config:
query: |
query ($pokemon: PokemonEnum!) {
getPokemon(pokemon: $pokemon) {
key
color
species
}
}
variables:
- pokemon
应用更新后的配置：
kubectl apply -f degraphql-ic.yaml
对于 POST 请求，在 JSON 请求体中提供已配置的变量：
curl "http://127.0.0.1:9080/v8" -X POST \
-H "Content-Type: application/json" \
-d '{
"pokemon": "pikachu"
}'
响应应包含请求的 Pokémon：
{
"data": {
"getPokemon": {
"key": "pikachu",
"color": "Yellow",
"species": "pikachu"
}
}
}
对于 GET 请求，将变量作为 URL 查询参数提供：
curl "http://127.0.0.1:9080/v8?pokemon=pikachu" \
-H "x-apollo-operation-name: GET"
Pokémon API 使用 Apollo Server 的 CSRF 防护，因此 GET 请求必须包含 x-apollo-operation-name 请求头。此要求来自上游 API，而不是 degraphql。响应应与 POST 请求的结果一致。