Skip to content

如何发起调用

GraphQL 规范不绑定传输层,但绝大多数实现都基于 HTTP。调用方式与 REST 差别很大:

  • REST:不同资源 = 不同 URL + 不同方法;
  • GraphQL:一个 URL,几乎所有请求都用 POST。

以本服务(https://stepmetric.ai/api/v2/graphql)为例:

项 值
端点 https://stepmetric.ai/api/v2/graphql(别名 https://stepmetric.ai/graphql 亦可访问)
方法 POST
请求头 Content-Type: application/json;Authorization: Bearer <JWT>(本服务鉴权方式)
请求体 JSON,见下

请求体只有三个字段:

{
"query": "...",
"variables": {},
"operationName": "SomeOperation"
}
字段 说明
query 必填。GraphQL 查询/变更文本
variables 可选。传给 $变量 的 JSON 对象
operationName 可选。当 query 里写了多个操作时,指定执行哪一个
Terminal window
curl -X POST https://stepmetric.ai/api/v2/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
"query": "query { dailyMetrics(storeId: 1, startDate: \"2026-07-01\", endDate: \"2026-07-31\") { date enteringPeople } }"
}'

把参数写进查询文本虽然可行,但更推荐放进 variables——查询文本保持固定,参数单独传:

Terminal window
curl -X POST https://stepmetric.ai/api/v2/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
"query": "query GetMetrics($storeId: Int!, $startDate: String!, $endDate: String!) { dailyMetrics(storeId: $storeId, startDate: $startDate, endDate: $endDate) { date enteringPeople } }",
"variables": {
"storeId": 1,
"startDate": "2026-07-01",
"endDate": "2026-07-31"
}
}'

GraphQL 本身不定义认证方式,通常复用 HTTP 层的方案。本服务使用 JWT Bearer:

Terminal window
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

调用接口前,先通过登录接口换取 JWT(accessToken):

Terminal window
curl -s -X POST https://stepmetric.ai/api/auth/sign-in \
-H "Content-Type: application/json" \
-d '{"email":"<邮箱或用户名>","password":"<密码>"}' | jq -r .accessToken

把输出的令牌拼进 Authorization 头即可;也可以用命令替换一步到位:

Terminal window
curl -s -X POST https://stepmetric.ai/api/v2/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(curl -s -X POST https://stepmetric.ai/api/auth/sign-in \
-H "Content-Type: application/json" \
-d '{"email":"<邮箱或用户名>","password":"<密码>"}' | jq -r .accessToken)" \
-d '{ "query": "{ dailyMetrics(storeId: 1, startDate: \"2026-07-01\", endDate: \"2026-07-31\") { date } }" }'

令牌有有效期,过期后重新登录获取即可(见下方错误表)。

  • 未携带令牌、格式不对、令牌过期或签名错误时,服务返回 401 Unauthorized,响应体为 {"error": "<原因>"};
  • 认证通过后,查询里的门店权限校验由服务端按登录用户的身份完成,越权等业务错误会出现在 GraphQL 的 errors 里(见下文)。

常见认证错误信息:

HTTP 状态码 响应体 error 触发条件
401 未提供认证令牌 请求头没有 Authorization
401 认证格式错误,应为 'Bearer <token>' 不是 Bearer <token> 格式
401 令牌格式错误 JWT 无法解析
401 令牌已过期 令牌过期或未到生效时间
401 令牌验证失败: <detail> 签名错误、算法不符等其他情况

GraphQL 一个“反直觉”的点:业务错误不一定体现在 HTTP 状态码上。正确读法是以响应体里的 data 和 errors 为准。

成功的响应:

{
"data": {
"dailyMetrics": [{ "date": "2026-07-01", "enteringPeople": 42 }]
}
}

出错时响应带 errors 数组(部分失败时 data 仍可能有值):

{
"data": null,
"errors": [
{
"message": "无权访问该门店数据",
"locations": [{ "line": 3, "column": 5 }],
"path": ["dailyMetrics"]
}
]
}

常见情况的对照:

情况 HTTP 状态码 响应体
查询成功 200 data 有值,无 errors
Schema 校验失败(字段拼错、缺必填参数) 200(多数实现) data 为 null + errors
执行期业务错误(权限、数据不存在) 200 部分 data + errors
未认证 / 令牌无效 401 错误信息
请求体不是合法 JSON、缺少 query 字段 400 错误信息

不同服务对“校验失败”的 HTTP 状态码处理可能不同(有的返回 400)。判断结果请以 errors 字段为准,不要只依赖状态码。

规范允许通过 GET 请求做只读查询(query 放在 URL 的 query 参数里)。GitHub 官方就推荐用 GET 跑内省、用 jq 或 python -m json.tool 格式化输出:

Terminal window
curl "https://stepmetric.ai/api/v2/graphql?query=%7B__schema%7Btypes%7Bname%7D%7D%7D" | python -m json.tool

日常数据请求请一律使用 POST,GET 只在查看 Schema 这类只读场景使用。

本服务的 GET /graphql 直接提供了 GraphQL Playground:

  1. 浏览器打开 https://stepmetric.ai/graphql;
  2. 左侧写查询,点 ▶ 执行;
  3. 右侧看结果;左侧有自动补全,右侧“Docs”面板可以浏览整个 Schema——这些都是基于内省实现的。

如果你在自己的服务里用其他框架(如 Apollo Server),对应工具一般是 GraphiQL 或 Altair,用法类似。

const res = await fetch("https://stepmetric.ai/api/v2/graphql", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer " + token,
},
body: JSON.stringify({
```graphql
query GetMetrics($storeId: Int!, $startDate: String!, $endDate: String!) {
dailyMetrics(storeId: $storeId, startDate: $startDate, endDate: $endDate) {
date
enteringPeople
}
}`,
variables: {
storeId: 1,
startDate: "2026-07-01",
endDate: "2026-07-31",
},
}),
});
const json = await res.json();
if (json.errors) {
// 处理错误
}

生产环境通常还会引入 Apollo Client、urql 等客户端库处理缓存与状态管理,但底层仍然是上面这种 HTTP 请求,理解了这个,看任何客户端库的文档都不会陌生。

下一步:实战示例,用真实服务把这一切跑一遍。