GraphQL 规范 (中文版)
1、概述
例子3{
user(id: 4) {
name
}
}
例子4{
"user": {
"name": "Mark Zuckerberg"
}
}
2、语言
:
表示,而词法规则的产生式用双冒号 ::
表示。2.1 源文本
2.1.1 统一码
2.1.2 空格
2.1.3 行终止符
2.1.4 评论
list,opt
CommentChar2.1.5 无关紧要的逗号
2.1.6 词汇标记
2.1.7 忽略的令牌
2.1.8 标点符号
2.1.9 名称
list,opt
NameContinueA | B | C | D | E | F | G | H | I | J | K | L | M |
---|---|---|---|---|---|---|---|---|---|---|---|---|
N | O | P | Q | R | S | T | U | V | W | X | Y | Z |
a | b | c | d | e | f | g | h | i | j | k | l | m |
n | o | p | q | r | s | t | u | v | w | x | y | z |
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
---|
name
,Name
和 NAME
都指代不同的名称。下划线很重要,它表示other_name
和othername
是两个不同的名称。2.2文档
list
2.3 运营
query | mutation | subscription |
---|
例子5mutation {
likeStory(storyID: 12345) {
story {
likeCount
}
}
}
例子6{
field
}
2.4 选择集
list
}Example № 7
Example № 7{
id
firstName
lastName
}
id
, firstName
和 lastName
字段构成了一个选择集。选择集还可以包含片段引用。2.5 领域
opt
NameArgumentsopt
Directivesopt
SelectionSetopt
示例#8{
me {
id
firstName
lastName
birthday {
month
day
}
friends {
name
}
}
}
例子9# `me` could represent the currently logged in viewer.
{
me {
name
}
}
# `user` represents one of many users in a graph of data, referred to by a
# unique identifier.
{
user(id: 4) {
name
}
}
2.6 论点
id
)及其特定的个人资料图片size
:示例 10{
user(id: 4) {
id
name
profilePic(size: 100)
}
}
例子11{
user(id: 4) {
id
name
profilePic(width: 100, height: 50)
}
}
示例 12{
picture(width: 200, height: 100)
}
例子13{
picture(height: 100, width: 200)
}
2.7 字段别名
示例 14{
user(id: 4) {
id
name
smallPic: profilePic(size: 64)
bigPic: profilePic(size: 1024)
}
}
示例 15{
"user": {
"id": 4,
"name": "Mark Zuckerberg",
"smallPic": "https://cdn.site.io/pic-4-64.jpg",
"bigPic": "https://cdn.site.io/pic-4-1024.jpg"
}
}
示例 16{
zuck: user(id: 4) {
id
name
}
}
示例 17{
"zuck": {
"id": 4,
"name": "Mark Zuckerberg"
}
}
2.8 片段
opt
示例 18query noFragments {
user(id: 4) {
friends(first: 10) {
id
name
profilePic(size: 50)
}
mutualFriends(first: 10) {
id
name
profilePic(size: 50)
}
}
}
示例 19query withFragments {
user(id: 4) {
friends(first: 10) {
...friendFields
}
mutualFriends(first: 10) {
...friendFields
}
}
}
fragment friendFields on User {
id
name
profilePic(size: 50)
}
...
),可以消耗片段。片段选择的所有字段将被添加到与片段调用相同级别的字段选择中。这是通过多个级别的片段扩展来实现的。示例 20query withNestedFragments {
user(id: 4) {
friends(first: 10) {
...friendFields
}
mutualFriends(first: 10) {
...friendFields
}
}
}
fragment friendFields on User {
id
name
...standardProfilePic
}
fragment standardProfilePic on User {
profilePic(size: 50)
}
noFragments
、withFragments
、 和withNestedFragments
都生成相同的响应对象。noFragments
、withFragments
、 和withNestedFragments
都生成相同的响应对象。2.8.1 类型条件
friendFields
可以在查询 的上下文中使用 User
。示例 21query FragmentTyping {
profiles(handles: ["zuck", "coca-cola"]) {
handle
...userFragment
...pageFragment
}
}
fragment userFragment on User {
friends {
count
}
}
fragment pageFragment on Page {
likers {
count
}
}
profiles
根字段返回一个列表,其中每个元素可以是 Page
或 User
。当 profiles
结果中的对象是 User
时,将存在 friends
而 likers
将不存在。相反,当结果是 Page
时,将存在 likers
而 friends
将不存在。示例 22{
"profiles": [
{
"handle": "zuck",
"friends": { "count": 1234 }
},
{
"handle": "coca-cola",
"likers": { "count": 90234512 }
}
]
}
2.8.2 内联片段
opt
Directivesopt
SelectionSetquery FragmentTyping
示例中得到了演示。我们可以使用内联片段完成同样的事情。示例 23query inlineFragmentTyping {
profiles(handles: ["zuck", "coca-cola"]) {
handle
... on User {
friends {
count
}
}
... on Page {
likers {
count
}
}
}
}
示例 24query inlineFragmentNoType($expandedInfo: Boolean) {
user(handle: "zuck") {
id
name
... @include(if: $expandedInfo) {
firstName
lastName
birthday
}
}
}
2.9 输入值
Const
:2.9.1 整数值
opt
0opt
NonZeroDigitDigit list,opt
0x123
和 123L
没有有效的词法表示。2.9.2 浮动值
list
opt
Digit list
e | E |
---|
+ | - |
---|
0x1.2p3
没有有效的词汇表示。2.9.3 布尔值
ture | false |
---|
true
andfalse
代表两个布尔值。2.9.4 字符串值
list
"/#BlockStringCharacter)
list,opt
"""" | \ | / | b | f | n | r | t |
---|
块字符串
"""
) 括起来的字符序列。空格、行终止符、引号和反斜杠字符都可以不转义地使用,以启用逐字文本。字符必须都是有效的 SourceCharacter。示例 25mutation {
sendEmail(message: """
Hello,
World!
Yours,
GraphQL.
""")
}
示例 26mutation {
sendEmail(message: "Hello,\n World!\n\nYours,\n GraphQL.")
}
示例 27"""
This starts with and ends with an empty line,
which makes it easier to read.
"""
反例#28"""This does not start with or end with any empty lines,
which makes it a little harder to read."""
语义学
list
"Escaped Character | Code Point | Character Name |
---|---|---|
" | U+0022 | double quote |
\ | U+005C | reverse solidus (back slash) |
/ | U+002F | solidus (forward slash) |
b | U+0008 | backspace |
f | U+000C | form feed |
n | U+000A | line feed (new line) |
r | U+000D | carriage return |
t | U+0009 | horizontal tab |
listopt
"""1.
2.
1.
1.
"""
。rawValue
)1.
lines
be the result of splitting rawValue
by LineTerminator.2.
commonIndent
be null.3.
line
in lines
:1.
2.
3.
4.
indent
is less than length
:1.
2.
4.
1.
5.
6.
7.
8.
1.
2.
2.9.5 空值
示例 29{
field(arg: null)
field
}
2.9.6 Enum Value
MOBILE_WEB
)。建议枚举值“全部大写”。枚举值仅在已知精确枚举类型的上下文中使用。因此,没有必要在文字中提供枚举类型名称。2.9.7 列表值
Const
ListValueConst:[ ]
。列表文字的值可以是任何值文字或变量(例如[1, 2, 3]
)。语义学
1.
2.9.8 输入对象值
Const
:Const
{ }
。对象文字的值可以是任何输入值文字或变量(例如{ name: "Hello world", score: 1.0 }
)。我们将输入对象的文字表示称为“对象文字”。输入对象字段无序
示例 30{
nearestThing(location: { lon: 12.43, lat: -53.211 })
}
示例#31{
nearestThing(location: { lat: -53.211, lon: 12.43 })
}
语义学
1.
1.
inputObject
为不带字段的新输入对象值。2.
字段
name
为 Name in field
。value为评估``field
中 Value 的结果。``向名为
name 的inputObject
添加一个包含值value
的字段。````3.
输入对象
2.10 变量
list
)opt
DirectivesConstoptConst
示例#32query getZuckProfile($devicePicSize: Int) {
user(id: 4) {
id
name
profilePic(size: $devicePicSize)
}
}
profilePic
of size 60
:示例#33{
"devicePicSize": 60
}