dynamic, schema-less, directive-driven Graphql
npm install graphql-dynamicshell
npm install graphql-dynamic
`
`javascript
import createLoader from 'graphql-dynamic'
const loader = createLoader()
const query =
const result = await loader.load(query) // output: { errors: [], infos: [], data: { test: 1 } }
`
Directives
- graphql 的指令以 @ 符号开头
- 指令按出现顺序执行
- 每个指令都有一个特殊参数 use，用于动态计算指令参数。
`graphql
{
# @create 的最终参数来自 use 返回的结果，use 里可以通过 b 访问到其它参数
a @create(b: 1, use: "{ value: b }")
}
`
$3
`graphql
{
testUrlString @post(url: "http://example.com/api/name?a=1&b=2")
testUrlObject
@post(
url: { host: "example.com", pathanme: "/api/name", query: { a: 1, b: 2 } }
)
}
`
$3
headers 必须是数组[[key, value]] 格式，而不是 { [key]: value }。
（graphql 的 key 不允许出现横杠，也不像 json 那样可以用双引号包裹）
`graphql
{
test
@post(
options: {
headers: [
["Content-Type", "application/json"]
["Accept", "application/json"]
]
}
)
}
`
$3
发送 post 请求
- url，可以是 url string，也可以是 url object
- body，post 请求发送的数据
- options, 跟 fetch(url, options) 的 options 结构一致，（除了 headers 要求特殊形式，见“fetch|get|post 指令里的 headers 参数”一节）
- bodyType，发送 post 请求时 body 的编码类型，默认为 json，可以设置为 text 文本格式。
- responseType，获取 post 请求的响应数据的编码类型，默认为 json，可以设置为 text 文本格式。
`graphql
{
test
@post(
url: "/my/api"
data: { a: 1, b: 2 }
options: {
headers: [
["Content-Type", "application/json"]
["Accept", "application/json"]
]
}
bodyType: "json"
responseType: "json"
)
}
`
$3
发送一系列 post 请求，它内部会以 Promise.all 的形式，等待所有接口响应完成。
- url，可以是 url string，也可以是 url object
- bodys，数组类型，其中的每一个元素都将作为 post 请求发送的 body 数据
- options, 跟 fetch(url, options) 的 options 结构一致，（除了 headers 要求特殊形式，见“fetch|get|post 指令里的 headers 参数”一节）
- bodyType，发送 post 请求时 body 的编码类型，默认为 json，可以设置为 text 文本格式。
- responseType，获取 post 请求的响应数据的编码类型，默认为 json，可以设置为 text 文本格式。
$3
发送 get 请求
- url，可以是 url string，也可以是 url object
- query，get 请求发送的数据，会作为 querystring 拼接在 url 的 ? 号后面
- options, 跟 fetch(url, options) 的 options 结构一致，（除了 headers 要求特殊形式，见“fetch|get|post 指令里的 headers 参数”一节）
- responseType，获取 post 请求的响应数据的编码类型，默认为 json，可以设置为 text 文本格式。
`graphql
{
test
@get(
url: "/my/api"
query: { a: 1, b: 2 }
options: {
headers: [
["Content-Type", "application/json"]
["Accept", "application/json"]
]
}
bodyType: "json"
responseType: "json"
)
}
`
$3
发送一系列 get 请求，内部会用 Promise.all 等待所有接口响应完成
- url，可以是 url string，也可以是 url object
- querys，数组类型，其中的每一个元素都将作为 get 请求发送的数据，会作为 querystring 拼接在 url 的 ? 号后面
- options, 跟 fetch(url, options) 的 options 结构一致，（除了 headers 要求特殊形式，见“fetch|get|post 指令里的 headers 参数”一节）
- responseType，获取 post 请求的响应数据的编码类型，默认为 json，可以设置为 text 文本格式。
$3
发送 fetch 请求
- url，可以是 url string，也可以是 url object
- options, 跟 fetch(url, options) 的 options 结构一致，（除了 headers 要求特殊形式，见“fetch|get|post 指令里的 headers 参数”一节）
- bodyType，发送 post 请求时 body 的编码类型，默认为 json，可以设置为 text 文本格式。
- responseType，获取 post 请求的响应数据的编码类型，默认为 json，可以设置为 text 文本格式。
`graphql
{
test
@fetch(
url: "/my/api"
options: {
method: "POST"
body: { a: 1, b: 2 }
headers: [
["Content-Type", "application/json"]
["Accept", "application/json"]
]
}
bodyType: "json"
responseType: "json"
)
}
`
$3
用 value 参数的值作为当前字段的值
`graphql
{
number @create(value: 1)
string @create(value: "1")
object @create(value: { a: 1, b: 2 })
array @create(value: [{ a: 1 }, { b: 2 }])
}
`
返回
`javascript
{
number: 1,
string: '1',
object: { a: 1, b: 2 }
array: [{ a: 1 }, {b: 2}]
}
`
$3
将当前字段的值定义为 graphql 变量
如果 name 参数没有指定，默认为当前字段的名称（fieldName）。
变量的使用，不依赖定义顺序。可以先使用，后定义。子字段可以使用父字段定义的变量，但父字段不能使用子字段的定义的变量。
`graphql
{
a @create(value: 1) @variable # 将 a 定义为变量
b @create(value: $a) @variable(name: "c") # 使用变量 a，并将 b 定义为变量，变量名为 c
c @create(value: $c) # 使用来自字段 b 定义的变量 c
}
`
$3
将当前字段的值映射成另一个，to 参数为一个 js 表达式，在表达式里可以使用 context 里的参数
- to 参数里可以用当前字段的名字访问它的值。
- 如果当前字段的值是对象，则 to 参数里可以用对象里的 key 去访问对应的 value 值
- 如果当前字段的值是数组，则循环这个数组，按上面的规则读取值
- 如果数组的元素也是数组，则继续循环这个数组，按照上面的规则取值
`graphql
{
a @create(value: 1) @map(to: "a + b", b: 1) # a 最终为 2
objcet @create(value: { a: 1, b: 2 }) @map(to: "{ a: a + 1, b: b + n }", n: 1) # object 最终为 { a: 2, b: 3 }
array @create(value: [{ a: 1 }, { a: 2 }]) @map(to: "{ a: a + 1 }") # array 最终为 [{ a: 2 }, { a: 3 }]
}
`
$3
过滤当前字段的值，if 参数为一个 js 表达式，在表达式里可以使用 context 里的参数
- if 参数里可以用当前字段的名字访问它的值。
- 如果当前字段的值是对象，则 if 参数里可以用对象里的 key 去访问对应的 value 值
- 如果当前字段的值是数组，则循环这个数组，按上面的规则读取值。
- 如果数组的元素也是数组，则继续循环这个数组，按照上面的规则取值
`graphql
{
a @create(value: 1) @filter(if: "a > 1") # a 不会被输出
b @create(value: 1) @filter(if: "b === 1") # b 输出为 1
objcet @create(value: { a: 1, b: 2 }) @filter(if: "b <= n", n: 2) # object 最终为 { a: 1, b: 2 }
array @create(value: [{ a: 1 }, { a: 2 }]) @filter(if: "a < 2") # array 最终为 [{ a: 1 }]
}
`
$3
向下遍历查找存在 key 参数指定的字段名的对象，如果存在多个这种对象，收集成数组
当 key 参数不存在时，指令所在的当前字段名为查找的目标 key 值
`graphql
{
a @create(value: { b: { c: { d: 1 } } }) @select(key: "d")
}
输出如下
{
a: {
d: 1
}
}
`
$3
查找当前字段的值，if 参数为一个 js 表达式，在表达式里可以使用 context 里的参数。
- if 参数里可以用当前字段的名字访问它的值。
- 如果当前字段的值是对象，则 if 参数里可以用对象里的 key 去访问对应的 value 值
- 如果当前字段的值是数组，则循环这个数组，按上面的规则读取值。
- 如果数组的元素也是数组，则继续循环这个数组，按照上面的规则取值
和 filter 的差别是，find 指令返回的不是数组，而是第一个匹配的元素。
`graphql
{
a @create(value: 1) @find(if: "a > 1") # a 不会被输出
b @create(value: 1) @find(if: "b === 1") # b 输出为 1
objcet @create(value: { a: 1, b: 2 }) @find(if: "b <= n", n: 2) # object 最终为 { a: 1, b: 2 }
array @create(value: [{ a: 1 }, { a: 2 }]) @find(if: "a < 2") # array 最终为 { a: 1 }
}
`
$3
用 object 拓展当前的字段值
- 如果当前的字段值不是对象，用 object 替换当前字段的值
- 如果当前字段值为对象，用 object 里的 key 覆盖当前对象的值
- 如果当前对象值为数组，对数组每一项执行 extend 操作
`graphql
{
a @extend(b: 1, c: 2) # a 输出为 { b: 1, c: 2 }
b @create(value: { b: 0, d: 3 }) @extend(b: 1, c: 2) # b 输出为 { b: 1, c: 2, d: 3 }
c @create(value: [{ b: 0, d: 3 }, { b: -1, d: 4 }]) @extend(b: 1, c: 2) # c 输出为 [{ b: 1, c: 2, d: 3 }, { b: 1, c: 2, d: 4 }]
}
`
$3
从当前字段的数组首位拼接 value 值
`graphql
{
a @prepend(value: 1)
b @prepend(value: "1")
c @prepend(value: [1, 2])
d @prepend(value: { value: 1 })
}
输出
{
a: [1],
b: ['1'],
c: [1, 2],
d: [{ value: 1 }]
}
{
a @create(value: 0) @prepend(value: 1)
b @create(value: "0") @prepend(value: "1")
c @create(value: 0) @prepend(value: [1, 2])
d @create(value: { value: 0 }) @prepend(value: { value: 1 })
e @create(value: [0, 1, 2]) @prepend(value: [3, 4, 5])
}
输出
{
a: [1, 0],
b: ['1', '0'],
c: [1, 2, 0],
d: [{ value: 1 }, { value: 0 }],
e: [3, 4, 5, 0, 1, 2]
}
`
$3
从当前字段的数组末尾拼接 value 值，用法见 @prepend
Api
graphql-dynamic 基于 graphql-anywhere 实现，部分 api 及概念需参考 graphql-anywhere 文档帮助理解。
$3
createLoader 创建查询 graphql 的 loader 对象。
config 参数类型为对象
- variableTimeout 字段表示等待动态的 graphql 变量的超时时间，默认为 3000
- fetchTimeout 字段表示等待 fetch 请求的超时时间，默认为 3000
loader 字段拥有两个方法：
- load(query, variables?, context?, rootValue?)
- query 为 graphql 查询语句(字符串)或者 graphql document，必传
- variables 为传入 graphql 语句的变量对象
- context 为传入 resolver 的 context
- rootValue 为 resolver 开始的根节点的值
- load 方法返回数据格式为 { errors, logs, data } 的 promise 对象
- errors 为数组，包含此次 graphql 查询包含的错误信息
- logs 为数组，包含此次 graphql 查询包含的日志信息（内置的日志为 fetch 的耗时）
- data 为对象，包含我们查询的结果
- use(...middlewares)
- middlewares 为 koa style 的中间件的数组: (ctx, next) -> promise
- ctx 里合并了上述 config 和 context 对象，此外还包含
- fieldName，当前字段名
- rootValue，当前字段的父节点的值
- args 当前字段的参数对象
- context 当前对象
- info 当前字段的附加信息（比如指令，或者 isLeaf 是否枝叶节点）
- result 当前字段的值，默认为 rootValue[fieldName]，可能被前置中间件（如 @create, @map）进行过更新
- directive(directiveName, directiveHandler) 方法，注册指令，directiveHandler 函数可以获取到指令的 params 参数
- fetch(url, options)，同构的 fetch 方法
- error(error) 添加错误信息到响应结果的 errors 数组里
- log(info) 添加信息到响应结果的 logs 数组里
在第一次执行 loader.load 方法之前，可以使用 loader.use 添加自定义中间件。在执行过 loader.load 之后，loader.use 传入的参数会被忽略。
`javascript
import createLoader from 'graphql-dynamic'
const loader = createLoader({
variableTimeout: 3000,
fetchTimeout: 3000
})
loader.use(async (ctx, next) => {
let start = Date.now()
await next()
console.log('time', Date.now() - start)
})
const result = await loader.load({ test @create(value: 1) })
// { errors: [], logs: [], data: { test: 1 }}
`
#### 自定义指令
ctx.directive 方法可以注册一个可用指令，比如 @date 指令实现：
`javascript
const moment = require('moment')
// @date(format, i18n) 将字段值通过 moment 转换成日期
loader.use((ctx, next) => {
// 注册 @date 指令
ctx.directive('date', params => {
if (!/number|string/.test(typeof ctx.result)) {
return
}
let { format = 'YYYY/MM/DD', i18n = 'zh-cn' } = params
let local = moment(ctx.result)
if (i18n) local.locale(i18n)
ctx.result = local.format(format)
})
return next()
})
`
$3
createGraphql(config) 可用于创建 expressjs 的中间件
config 参数除了包含 createLoader 里的 config 以外，还有 graphql-playground 的设置部分。
- config.endpoint，graphql-playground 里请求的 graphql server 接口地址，默认为 /graphql
`javascript
import createGraphql from 'graphql-dynamic/express'
const express = require('express')
const app = express()
const playground = {
'general.betaUpdates': false,
'editor.cursorShape': 'line', // possible values: 'line', 'block', 'underline'
'editor.fontSize': 14,
'editor.fontFamily': 'Source Code Pro', 'Consolas', 'Inconsolata', 'Droid Sans Mono', 'Monaco', monospace,
'editor.theme': 'light', // possible values: 'dark', 'light'
'editor.reuseHeaders': true, // new tab reuses headers from last tab
'request.credentials': 'omit', // possible values: 'omit', 'include', 'same-origin'
'tracing.hideTracingResponse': true
}
const endpoint = '/graphql'
const router = createGraphql({ endpoint, playground })
app.use(endpoint, router)
// router.loader 可以获取到 loader 对象
``