Skip to content

实战示例

这一页把前面的概念串起来,用本服务(https://stepmetric.ai/api/v2/graphql)动手走一遍。虽然例子来自本服务,但每一步都是调用任何 GraphQL API 的通用套路,换个服务只是端点、字段名不同。

  1. 拿到一个有效的 JWT:通过登录接口签发,见如何发起调用·认证;
  2. 知道一个你有权限访问的 storeId。

本服务的 Schema(节选)如下。注意字段名是 camelCase:

type Query {
dailyMetrics(storeId: Int!, startDate: String!, endDate: String!): [DailyMetric!]!
hourlyMetrics(storeId: Int!, startDate: String!, endDate: String!): [HourlyMetric!]!
poiMetrics(
storeId: Int!
poiTypes: [PoiType!]
startDate: String
endDate: String
startAt: String
endAt: String
): [PoiMetric!]!
peoplePaths(
storeId: Int!
startDate: String!
endDate: String!
roles: [PeopleRole!]
): [PeoplePath!]!
flowEvents(
storeId: Int!
startDate: String!
endDate: String!
roles: [PeopleRole!]
): [FlowEvent!]!
}
query {
dailyMetrics(storeId: 1, startDate: "2026-07-01", endDate: "2026-07-31") {
date
enteringPeople
}
}

对照前面学过的概念逐条看:

  • dailyMetrics 是 Query 根类型上的字段;
  • 三个参数都是必填(Int! / String!),少传一个校验直接报错;
  • 返回类型是 [DailyMetric!]!(非空数组,元素非空),元素是对象,所以必须继续选择子字段(date、enteringPeople);
  • 只选了 2 个字段 → 响应就只包含这 2 个字段。

同样的数据,REST 接口往往返回固定的一整坨字段,UI 只要 2 个也只能全收(over-fetching)。GraphQL 下只写需要的:

query {
dailyMetrics(storeId: 1, startDate: "2026-07-01", endDate: "2026-07-31") {
date
passByVisits
servedPeople
}
}

响应:

{
"data": {
"dailyMetrics": [
{ "date": "2026-07-01", "passByVisits": 520, "servedPeople": 87 },
{ "date": "2026-07-02", "passByVisits": 483, "servedPeople": 91 }
]
}
}

把参数抽到 variables,查询文本保持固定:

query GetDailyMetrics($storeId: Int!, $startDate: String!, $endDate: String!) {
dailyMetrics(storeId: $storeId, startDate: $startDate, endDate: $endDate) {
date
enteringPeople
dwellPeople
servedPeople
}
}
{
"variables": {
"storeId": 1,
"startDate": "2026-07-01",
"endDate": "2026-07-31"
}
}

好处:

  • 查询文本固定,可以提前写好、复用、缓存;
  • 避免字符串拼接带来的转义麻烦和注入风险;
  • 换门店、换日期区间,只需改 variables。

poiMetrics 返回的 PoiMetric 里嵌着一个 poi 对象。GraphQL 里一次搞定:

query {
poiMetrics(
storeId: 1
startAt: "2026-07-01T00:00:00+08:00"
endAt: "2026-08-01T00:00:00+08:00"
poiTypes: [COUNTER]
) {
poi {
id
poiType
name
}
dwellPeople
totalDwellSeconds
}
}

如果换成 poiTypes 不传、日期用旧参数 startDate/endDate 也能跑,但 startAt/endAt 是 ISO8601 格式、endAt 为排他边界(查 7 月就传 2026-08-01T00:00:00+08:00),是当前推荐用法。

如果漏选了 poi 的子字段,校验会直接报错——对象类型的字段必须一路选到标量(id 是 Int!、name 是 String!,都到底了,合法)。

示例 5:一次查询三类 POI(别名 + poiTypes)

Section titled “示例 5:一次查询三类 POI(别名 + poiTypes)”

poiMetrics 支持用 poiTypes 只取某一类 POI,再配合别名在同一个请求里把三类数据一次拿全:

query {
aisle: poiMetrics(
storeId: 6
startAt: "2026-08-25T00:00:00+08:00"
endAt: "2026-08-26T00:00:00+08:00"
poiTypes: [AISLE]
) {
poi {
id
name
detectionRange
}
passByVisits
hourly {
dateTime
passByVisits
}
}
entrance: poiMetrics(
storeId: 6
startAt: "2026-08-25T00:00:00+08:00"
endAt: "2026-08-26T00:00:00+08:00"
poiTypes: [ENTRANCE]
) {
poi {
id
name
detectionRange
}
enteringVisits
enteringPeople
}
counter: poiMetrics(
storeId: 6
startAt: "2026-08-25T00:00:00+08:00"
endAt: "2026-08-26T00:00:00+08:00"
poiTypes: [COUNTER]
) {
poi {
id
name
dwellThresholdSeconds
serviceThresholdSeconds
}
dwellPeople
servedPeople
lingerPeople
totalDwellSeconds
totalLingerSeconds
serviceDurationSeconds
}
}

要点:

  • 别名:同一层不能重复写同一个字段,三个 poiMetrics 调用靠 aisle: / entrance: / counter: 区分,响应的键就是别名;
  • 各类型只取自己的指标:通道取经过人次与小时明细,出入口取进店人次/人数,柜台取驻留/服务/贴柜——每种类型的其他指标恒为 0(见 PoiMetric);
  • 三处查询共享同一时间段(2026-08-25 一天),相当于一次往返拿齐一个门店当天的全部 POI 数据。

响应结构(节选):

{
"data": {
"aisle": [
{
"poi": { "id": 62, "name": "中岛通道", "detectionRange": 5 },
"passByVisits": 1280,
"hourly": [{ "dateTime": "2026-08-25T10:00:00+08:00", "passByVisits": 152 }]
}
],
"entrance": [
{
"poi": { "id": 3, "name": "正门", "detectionRange": 4 },
"enteringVisits": 312,
"enteringPeople": 287
}
],
"counter": [
{
"poi": {
"id": 1849,
"name": "护肤柜",
"dwellThresholdSeconds": 5,
"serviceThresholdSeconds": 720
},
"dwellPeople": 96,
"servedPeople": 41,
"lingerPeople": 120,
"totalDwellSeconds": 18432,
"totalLingerSeconds": 7020,
"serviceDurationSeconds": 11250
}
]
}
}

a) 字段拼写错误

query {
dailyMetrics(storeId: 1, startDate: "2026-07-01", endDate: "2026-07-31") {
data
}
}
{
"errors": [
{
"message": "Cannot query field \"data\" on type \"DailyMetric\". Did you mean \"date\"?",
"locations": [{ "line": 4, "column": 5 }]
}
]
}

注意:这个错误在执行查询之前就被 Schema 校验拦截了,服务端根本没碰数据库;而且提示里往往还带“你是不是想写 xxx”。这是强类型 Schema 带来的开发体验。

b) 缺少必填参数

query {
dailyMetrics(storeId: 1) {
date
}
}

校验错误类似:Field "dailyMetrics" argument "startDate" of type "String!" is required...

c) 未认证

不带 Authorization 头直接调:

Terminal window
curl -X POST https://stepmetric.ai/api/v2/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "{ dailyMetrics(storeId: 1, startDate: \"2026-07-01\", endDate: \"2026-07-31\") { date } }"
}'
{ "error": "未提供认证令牌" }

HTTP 状态码为 401。

d) 越权访问

用 A 品牌的账号查 B 品牌的门店数据:

{
"errors": [
{
"message": "无权访问该门店数据",
"path": ["dailyMetrics"]
}
]
}

权限校验发生在 GraphQL 执行器内部(resolver 阶段),所以体现在 errors 里,而不是 HTTP 401。这两类“错误”的差异正是如何发起调用里那张表要说明的。

不用翻文档,直接问 Schema:

{
__type(name: "DailyMetric") {
name
kind
fields {
name
type {
name
kind
ofType {
name
kind
}
}
}
}
}

你随时可以在 Playground 里跑这类查询;IDE 自动补全和 Docs 面板背后的原理就是它。

  1. 在 Playground 里查询 __schema,数一数当前服务暴露了哪些类型;
  2. 用变量查询不同日期区间,观察只选 2 个字段和选全部字段时响应大小的差别;
  3. 故意写一个嵌套没选到标量的查询,看看校验错误长什么样;
  4. 把示例 4 用 curl、fetch 各写一遍,体会“同一个 GraphQL 查询,任何 HTTP 客户端都能调”;
  5. 给 peoplePaths 传 roles: [STAFF],对比不传时返回的 role 字段差异。