实战示例
这一页把前面的概念串起来,用本服务(https://stepmetric.ai/api/v2/graphql)动手走一遍。虽然例子来自本服务,但每一步都是调用任何 GraphQL API 的通用套路,换个服务只是端点、字段名不同。
- 拿到一个有效的 JWT:通过登录接口签发,见如何发起调用·认证;
- 知道一个你有权限访问的
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!]!}示例 1:最简单的查询
Section titled “示例 1:最简单的查询”query { dailyMetrics(storeId: 1, startDate: "2026-07-01", endDate: "2026-07-31") { date enteringPeople }}对照前面学过的概念逐条看:
dailyMetrics是Query根类型上的字段;- 三个参数都是必填(
Int!/String!),少传一个校验直接报错; - 返回类型是
[DailyMetric!]!(非空数组,元素非空),元素是对象,所以必须继续选择子字段(date、enteringPeople); - 只选了 2 个字段 → 响应就只包含这 2 个字段。
示例 2:按需取数(对比 REST)
Section titled “示例 2:按需取数(对比 REST)”同样的数据,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 } ] }}示例 3:用变量代替字符串拼接
Section titled “示例 3:用变量代替字符串拼接”把参数抽到 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。
示例 4:嵌套对象
Section titled “示例 4:嵌套对象”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 } ] }}示例 6:常见错误
Section titled “示例 6:常见错误”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 头直接调:
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。这两类“错误”的差异正是如何发起调用里那张表要说明的。
示例 7:内省(探索 Schema)
Section titled “示例 7:内省(探索 Schema)”不用翻文档,直接问 Schema:
{ __type(name: "DailyMetric") { name kind fields { name type { name kind ofType { name kind } } } }}你随时可以在 Playground 里跑这类查询;IDE 自动补全和 Docs 面板背后的原理就是它。
- 在 Playground 里查询
__schema,数一数当前服务暴露了哪些类型; - 用变量查询不同日期区间,观察只选 2 个字段和选全部字段时响应大小的差别;
- 故意写一个嵌套没选到标量的查询,看看校验错误长什么样;
- 把示例 4 用 curl、fetch 各写一遍,体会“同一个 GraphQL 查询,任何 HTTP 客户端都能调”;
- 给
peoplePaths传roles: [STAFF],对比不传时返回的role字段差异。