如何发起调用
如何发起调用
Section titled “如何发起调用”GraphQL 规范不绑定传输层,但绝大多数实现都基于 HTTP。调用方式与 REST 差别很大:
- REST:不同资源 = 不同 URL + 不同方法;
- GraphQL:一个 URL,几乎所有请求都用 POST。
请求的基本结构
Section titled “请求的基本结构”以本服务(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 里写了多个操作时,指定执行哪一个 |
用 curl 调用
Section titled “用 curl 调用”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——查询文本保持固定,参数单独传:
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:
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."获取令牌(登录)
Section titled “获取令牌(登录)”调用接口前,先通过登录接口换取 JWT(accessToken):
curl -s -X POST https://stepmetric.ai/api/auth/sign-in \ -H "Content-Type: application/json" \ -d '{"email":"<邮箱或用户名>","password":"<密码>"}' | jq -r .accessToken把输出的令牌拼进 Authorization 头即可;也可以用命令替换一步到位:
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)
Section titled “内省查询(GET)”规范允许通过 GET 请求做只读查询(query 放在 URL 的 query 参数里)。GitHub 官方就推荐用 GET 跑内省、用 jq 或 python -m json.tool 格式化输出:
curl "https://stepmetric.ai/api/v2/graphql?query=%7B__schema%7Btypes%7Bname%7D%7D%7D" | python -m json.tool日常数据请求请一律使用 POST,GET 只在查看 Schema 这类只读场景使用。
图形化工具:GraphQL Playground
Section titled “图形化工具:GraphQL Playground”本服务的 GET /graphql 直接提供了 GraphQL Playground:
- 浏览器打开
https://stepmetric.ai/graphql; - 左侧写查询,点 ▶ 执行;
- 右侧看结果;左侧有自动补全,右侧“Docs”面板可以浏览整个 Schema——这些都是基于内省实现的。
如果你在自己的服务里用其他框架(如 Apollo Server),对应工具一般是 GraphiQL 或 Altair,用法类似。
在代码中调用(fetch 示例)
Section titled “在代码中调用(fetch 示例)”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 请求,理解了这个,看任何客户端库的文档都不会陌生。
下一步:实战示例,用真实服务把这一切跑一遍。