1. 为什么我坚持用 REST 方式对接超图服务第一次接触超图 iServer 的时候我本能地想用前端地图库把图层直接叠到地图上省事又直观。但项目真实需求很快就打了脸图层加载只是表面功夫业务方要的是从海量要素里按条件筛出目标、分页展示、再做聚合统计。地图渲染解决不了这个问题因为它没有把服务端的查询能力释放出来。真正扛事的是超图对外暴露的那套 REST 接口。超图 REST 服务本质上是一组 HTTP 资源把地图、数据、空间分析这些能力都包装成了可以用 URL 访问、用 JSON 传参的接口。这意味着你不需要懂它底层的 COM 组件、也不用装任何桌面客户端只要能发 HTTP 请求任意语言都能接进来。我做过 Java 后端的批处理脚本、也写过纯浏览器里的前端看板用的都是同一套接口。这种语言无关的特性是我后来在多个项目里坚持选 REST 而不是专用 SDK 的最大原因。这套接口能做的事大致归为四类第一类是服务加载即通过 REST 地址拿到地图服务、数据服务的能力清单和元数据第二类是分页查询通过startRecord和expectCount把大结果集切成可控的批次第三类是统计通过statisticMode对字段做求和、均值、方差、计数这一系列聚合第四类是空间条件过滤用点、线、面对要素做相交、包含、相邻这类几何关系筛选。这四件事组合起来基本能覆盖 80% 以上的 GIS 业务场景比如门店选址分析、客流热力统计、地块权属查询、路口车流量的时空筛选等等。这篇文章写给谁如果你已经会发 HTTP 请求、看得懂 JSON但对超图 REST 的具体参数、分页逻辑、统计返回结构还比较模糊那这篇就是给你准备的。我会把每个环节的参数含义、取值规律、踩过的坑都摊开讲尽量让你能直接抄作业。至于完全没接触过 GIS 的朋友我也会用生活化的类比把概念先讲通保证你能顺着读下去。2. 服务加载先把服务地址这件事捋清楚2.1 一个 REST 地址背后的信息量超图 iServer 的 REST 地址有固定套路典型形式是http://{host}:{port}/iserver/services/{serviceName}/rest/{resource}。比如地图服务的根资源是/rest/maps数据服务的根资源是/rest/data。我见过不少新手拿到一个完整地址却不知道哪个部分是变量结果换个环境就报 404。建议第一次对接时先用浏览器直接访问这个根资源比如http://192.168.1.10:8090/iserver/services/map-world/rest/maps你会返回一个 JSON里面列出了这个服务下所有可用的地图。这一步相当于探测能力清单能快速验证服务是不是活着、名字有没有写错。判断服务是否正常除了看 HTTP 状态码是不是 200我还会额外看返回体的结构。iServer 出错时会返回包含error字段的 JSON里面code和errorMsg会告诉你具体哪里错了。很多初级排查就卡在这一步只看了状态码没看返回体结果明明返回 200 但业务数据是空的误以为是代码问题。养成打印完整返回体的习惯能省掉大量无谓的沟通成本。2.2 数据服务和地图服务不能混用这里有一个非常关键的区分很多项目因此翻过车地图服务maps用于出图数据服务data用于查询。你想拿要素属性、做分页、做统计走的是数据服务的featureResults或数据集资源而不是地图服务的图层资源。早期我用地图服务去查要素属性能拿到东西但分页参数死活不生效折腾了半天才发现是资源入口选错了。数据服务里最核心的两个入口是datasets/{datasetName}/features用于直接读取数据集要素featureResults用于执行带条件的查询。前者适合翻页浏览后者适合带 SQL/空间条件的高阶查询。记住这个分工后面所有操作都会顺很多。2.3 跨域与鉴权绕不开的两个现实问题从浏览器前端直接调 iServer REST你大概率会撞上跨域CORS。这不是超图特有的问题而是 iServer 默认没有对任意来源开放Access-Control-Allow-Origin。我的做法有两种生产环境在 iServer 里配置允许的来源域或者在 Nginx 里做一层反向代理把/iserver路径统一转发到后端顺带把 CORS 头补齐。开发阶段如果懒得配临时用后端做代理透传是最稳的也能顺手做鉴权。鉴权方面iServer 支持 Token 和 Basic 两种方式。Token 是在 URL 后面拼?tokenxxx或者放在请求头里Basic 则用用户名密码做 Base64。我的习惯是统一用 Token因为可以在服务端控制有效期和权限范围。Token 的获取一般走/iserver/services/security/tokens用 POST 提交用户名、密码、有效期。拿到 Token 后建议做一层缓存别每次请求都重新申请否则并发一高就容易触发限流。提示Token 有有效期过期后所有请求都会返回鉴权错误。建议在封装层里做自动刷新逻辑而不是等到请求失败了才手动换。3. 分页查询把大结果集切成可控的批次3.1 分页的两个核心参数到底怎么算超图 REST 的分页靠两个参数配合startRecord和expectCount。前者是从第几条开始取后者是这次取多少条。听起来简单但坑在于这两个参数都是基于 0 的偏移量不是页码。也就是说第 1 页对应startRecord0第 2 页每页 20 条对应startRecord20。公式是startRecord (pageIndex - 1) * pageSize。这个公式我当年在纸上推了三遍才记住因为它和很多后端框架的offset/limit完全是同一套逻辑唯独容易和页码从 1 开始混淆。expectCount这个参数要特别注意它的边界如果设成-1表示要返回全部要素。这个便利是毒药在城市级数据量上直接拖垮服务。我的建议是给它设一个硬上限比如 500 或者 1000前端不能随便改。很多线上事故就是因为某个新人不小心传了-1结果一次请求拉了十几万条要素直接把 iServer 拖到假死。参数含义单位常见取值startRecord起始记录位置从 0 开始条0、20、40……expectCount本次期望返回的条数条201000-1 表示全部慎用returnCountOnly是否只返回总数布尔true / falsereturnIdsOnly是否只返回 ID 列表布尔true / false3.2 总数预检先问有多少再决定怎么翻分页真正麻烦的地方不在翻页本身而在到底有多少条、需要多少页。如果直接一页一页翻前端算不出总页数用户体验会非常差。超图提供了returnCountOnly参数把它设为true时接口只返回一个总数不返回任何要素。这个轻量探测非常有价值一次请求就能拿到totalCount前端立刻可以算出总页数、显示进度。我的实际做法是首次进入列表页时先发一次returnCountOnlytrue的请求拿总数缓存下来之后每次翻页只请求当前页的要素。这样既省流量也避免每次翻页都重复数总数。如果数据实时性要求高可以给总数缓存设一个短 TTL比如 60 秒过期后重新探测。3.3 排序与分页必须绑定否则翻页会漏数据这是一个几乎所有人都踩过的坑。分页如果没配排序服务端返回的顺序是不确定的可能是物理存储顺序也可能随并发变化于是出现第 1 页有 A、第 2 页又冒出 A、某条 B 从头到尾没出现过的诡异现象。解决办法是强制加排序字段通常用orderBy指定一个唯一性强的字段比如SMID ASC。这样每次请求的排序一致分页边界才稳定。orderBy的写法遵循字段名 ASC/DESC多个字段用逗号分隔。我一般会用一个主键类字段排前面再用一个业务字段排后面比如orderBy: SMID ASC, NAME DESC。至于为什么不用业务字段单独排序因为业务字段可能有重复值重复值之间的顺序依然不确定必须靠主键来兜底。3.4 写一段可直接复用的分页请求下面这段是我常用的一段查询请求体走的是featureResults资源SQL 查询模式下带分页、带排序、带字段裁剪{ queryMode: SqlQuery, queryParameters: { name: World:Countries, attributeFilter: POP 1000000, fields: [SMID, NAME, POP], orderBy: SMID ASC }, startRecord: 20, expectCount: 20, returnCountOnly: false, returnIdsOnly: false }把这段 POST 到/iserver/services/data-{service}/rest/data/featureResults.rjson返回体里会带totalCount和recordsets。recordsets是一个数组每个元素对应一个数据集的结果里面有fieldNames和features。注意features里的字段值和fieldNames是按位置一一对应的不是键值对解析时不能想当然地按名字取得先读fieldNames建索引。注意fields参数建议显式列出需要的字段不要图省事不写。全字段返回在宽表上会明显增加传输量尤其是带有大文本或几何字段的时候。4. 统计让服务端帮你算而不是把数据拉下来自己算4.1 为什么统计要放在服务端很多人的第一反应是我把要素全查出来在前端循环求和。这在数据量小的时候没问题一旦上到几十万条就彻底崩了。超图提供的统计能力本质是把聚合运算推到服务端完成只把结果返回给你。这不只是性能问题也是正确性问题——前端浮点累加在数据量大时会有精度损失而服务端的统计是数据库级运算稳定性高得多。超图的统计主要围绕statisticMode展开支持的聚合类型包括求和Sum、平均Average、最大Max、最小Min、计数Count、方差Variance、标准差StdDev、中位数Median、众数Mode等。名字基本一看就懂但有几个细节值得提醒Count 统计的是满足条件的要素条数不是某个字段非空的个数Median 和 Mode 在大数据量上开销更高因为需要排序或频次统计。4.2 分组统计才是真正好用的那一档只求一个总数、一个总和价值有限。业务上更常见的是按类别分组再各自聚合比如按省份统计销售额、按商圈统计客流。超图的统计接口支持配合groupBy做分组然后对分组后的每个子集分别聚合。这一点在做报表看板时特别关键能一次性把整张分组汇总表拿到手不用前端发 N 次请求。我这里整理了一份常用统计模式的对照方便你直接对照选统计模式语义典型场景Sum求和区域内总销售额Average平均值平均客流强度Max / Min最大 / 最小极值时段识别Count计数满足条件的要素数量StdDev标准差数据波动程度评估Median中位数抗极值干扰的中心值Mode众数出现频率最高的取值4.3 统计请求的实操写法与返回解析统计查询同样走featureResults核心区别是在queryParameters里加入statisticMode并指定要统计的字段。下面是一个分组统计的示意请求{ queryMode: SqlQuery, queryParameters: { name: World:Countries, groupBy: CONTINENT, statisticMode: Sum, fields: [POP] } }返回体里会给出一组统计结果通常是分组值 统计值的配对。这里有个容易翻车的点统计结果的字段命名和普通查询不一样你不能拿普通查询的解析逻辑直接套上去。我一般会先打印一次原始返回体把实际字段名抄下来再写解析代码避免猜错字段名导致统计值取到 null。另外统计和分页一般不叠加使用。分页是对要素的截取统计是对整体的聚合两者语义上互相冲突。如果你发现统计结果和分页参数一起传时结果不对八成就是把这两件事混在一起了。正确的做法是统计独立发一次请求拿到聚合结果后再单独去查明细。5. 空间条件过滤让几何关系成为查询条件5.1 点线面和要素之间的几种关系空间过滤是 GIS 查询相比普通数据库查询最有价值的差异点。普通 SQL 只能按属性筛比如人口大于一百万空间过滤允许你按几何关系筛比如落在某个多边形范围内的所有门店。这背后的核心概念是空间谓词超图里通过spatialQueryMode参数表达。常用的取值和含义如下spatialQueryMode含义直观理解CONTAIN查询对象包含要素大区域包住了小地块INTERSECT相交只要沾边就算WITHIN要素在查询对象内小点在面里TOUCH边界接触但内部不相交相邻地块的贴合边CROSS穿越线穿过多边形内部OVERLAP部分重叠两个面有交叠区DISJOINT完全不相交毫无关系选哪个谓词直接决定结果的多少和口径。我见过最常见的误用是把INTERSECT当WITHIN用结果把边界上擦边的要素也带进来了。做严格落在区域内这种需求时要用WITHIN而不是INTERSECT因为后者只要几何有任何交叠就命中。5.2 过滤用的几何对象从哪来spatialQueryObject是空间过滤的核心参数用来指定参与比较的几何。它有三种常见的来源方式我按使用频率排序第一种是直接用要素 ID 引用指定某个数据集里的某个要素作为查询几何。这种方式最省事适合以一个已存在的地块作为查询范围的场景比如选中一个行政区查它下面的所有学校。第二种是内联几何坐标把点、线、面的坐标直接写在请求体里。这种方式灵活适合前端用户在屏幕上手绘一个多边形然后把坐标传回来查询。面类型一般是REGION里面的points按顺序给出顶点坐标注意要首尾闭合。第三种是服务端已有的分析结果比如缓冲区分析的结果对象。这种适合先做缓冲再筛选的两步流程属于稍微高阶的用法。下面是一个用内联多边形做相交查询的示意体{ queryMode: SpatialQuery, queryParameters: { name: World:Countries, spatialQueryMode: INTERSECT, spatialQueryObject: { geometry: { type: REGION, points: [ {x: 100.0, y: 30.0}, {x: 120.0, y: 30.0}, {x: 120.0, y: 40.0}, {x: 100.0, y: 40.0}, {x: 100.0, y: 30.0} ] } } } }5.3 空间过滤叠加属性过滤与分页单用空间过滤只是一个起点。真实项目里空间条件往往是和属性条件、分页一起出现的。比如在某个商圈范围内查询销售额大于 50 万的连锁门店按销售额降序每页 20 条。这种复合查询要在同一个请求体里同时提供attributeFilter、spatialQueryMode、spatialQueryObject、orderBy、startRecord、expectCount。这里有一个关键的坐标问题必须提醒空间过滤涉及的所有几何坐标必须和数据集本身的坐标系一致。iServer 不会自动帮你做投影转换。如果数据集是经纬度而你的多边形来自 Web 墨卡托的地图点击那两边坐标差着几百万的量级结果会是空集而且不报错。我第一次遇到这个坑时排查了整整一个下午最后发现是坐标系不匹配。解决方式有两种一是请求前把坐标转换到数据集坐标系iServer 本身也提供了坐标转换的相关服务二是让数据集和前端使用同一坐标系。我个人更倾向后者因为它从源头避免了转换误差。6. 实操中真正卡人的那些坑6.1 常见报错与排查速查光讲原理不够我把这几年遇到的典型案例整理成速查表你在对接时大概率会撞上其中几条现象可能原因排查方向请求 404服务名、资源路径拼错浏览器直接访问根资源验证返回 200 但数据为空空间过滤坐标系不一致比对数据集坐标系与查询几何坐标系分页出现重复/遗漏未加 orderBy补上唯一性排序字段统计值全为 null统计字段名写错打印返回体确认实际字段请求超时expectCount 设成 -1 或过大加上限保护前端报 CORSiServer 未放开来源配置 CORS 或走反向代理鉴权失败Token 过期检查有效期并加自动刷新6.2 性能上的几个实战心得第一条心得是字段裁剪。fields参数别偷懒不写只取业务需要的字段。一个宽表里可能有几十个字段其中还夹杂着大文本和几何全字段返回在列表接口上会显著拖慢响应。我做过一次优化光是加上字段裁剪列表接口的响应时间就降了一半多。第二条心得是分批拉取与异步并行。当总数很大、需要导出全量数据时不要单线程一页一页翻那样耗时随数据量线性增长。可以先用returnCountOnly拿到总数算出总页数然后用线程池并行请求多个页最后按 startRecord 归并。需要注意并发数不要太高iServer 也有承载上限我一般控制在 4 到 8 个并发之间。第三条心得是给统计和明细分开接口。看板上统计卡片和明细表格是两个需求别用一个接口硬撑。统计走statisticMode明细走分页查询各自独立缓存。这样两者的刷新节奏可以解耦统计缓存 60 秒、明细按需刷新用户体验和资源占用都更优。第四条心得是空间过滤尽量用引用而非内联。如果同一个几何要反复用于多次查询用要素 ID 引用比内联坐标高效因为服务端可以复用几何省去每次解析坐标的开销。6.3 关于坐标精度的一个小经验内联几何的坐标精度建议保留到数据集坐标系对应的合理位数。经纬度一般保留 6 位小数就足够多了反而增加传输量投影坐标则按米制精度保留 2 位。曾经有前端把经纬度硬生生拼成 15 位小数的字符串结果请求体比必要大了好几倍网络慢的时候特别明显。这种细节看起来不起眼实际做批量查询时影响不小。7. 把四件事串成一条完整的业务链路回到最初那套业务需求——加载服务、分页、统计、空间过滤它们在实际项目里通常不是孤立的而是串成一条链路。我以门店选点分析为例把这条链路走一遍你会发现每个环节都能用上前面讲的东西。第一步加载服务。通过 iServer 的 REST 根资源确认数据服务可用拿到目标数据集名称比如retail:stores。第二步用returnCountOnly探测满足条件的门店总数比如某城市所有连锁门店。第三步用户在地图上画一个多边形把这个几何内联到spatialQueryObject里用INTERSECT做空间过滤得到落在多边形内的门店。第四步对这些门店按品牌分组用statisticMode: Sum统计各家门店的月销售额形成一张分组汇总表。第五步明细列表用分页拉取配合orderBy保证翻页稳定。这条链路里每一步都对应前面的一个章节组合起来就能支撑一个完整的看板。我个人在实际项目里最大的体会是别把接口当成一次性调用来理解而要当成可组合的查询原语来理解。attributeFilter是一个原语spatialQueryObject是另一个statisticMode是第三个startRecord/expectCount是第四个。把这四个原语拼接调度好绝大多数看似复杂的业务查询都能拆解成它们的组合。最后再分享一个排查时的小技巧当你对某个请求体不确定时先把请求体简化到只保留queryParameters.name和queryMode这两个最基础的元素确认能返回数据后再一个参数一个参数地往上加。这样出问题时你能立刻定位到是新加的那个参数引发的比拿着一个复杂请求体反复猜要高效得多。这套最小化 逐步加参的调试方式我从第一次对接 iServer 一直用到现在几乎没有失手过。