GORM不支持GIS空间函数原生分页，须手动组合ST_Within/ST_Intersects与Limit/Offset；必须建空间索引（SPATIAL/GIST）、显式ORDER BY（如ST_Distance+id）、校验空间参数有效性，并避免OFFSET性能陷阱，推荐游标分页。
GORM 本身不支持 GIS 空间函数的原生分页封装，必须手动组合 ST_Within、ST_Intersects 等空间谓词与 Limit/Offset，且顺序、索引、排序稳定性比普通分页更敏感——稍有不慎就会漏掉边界点或重复返回。
GIS 范围查询必须显式加空间索引和 ORDER BY
MySQL/PostgreSQL 的空间函数（如 ST_Within）若未命中空间索引（如 SPATIAL INDEX 或 GIST），分页会全表扫描，OFFSET 越大越慢；更危险的是，无 ORDER BY 时空间查询结果顺序完全不可控——同一矩形范围两次请求可能返回不同子集。
- MySQL 中确保字段类型是
POINT，并建SPATIAL INDEX idx_location ON table_name(location) - PostgreSQL + PostGIS 必须用
GIST索引：CREATE INDEX idx_geom ON table_name USING GIST (geom) -
ORDER BY不能只写ORDER BY ST_X(location), ST_Y(location)—— 这不保证跨页连续性；应绑定主键：ORDER BY ST_Distance(location, POINT(116.4,39.9)), id ASC - 别用
ST_Centroid或ST_Envelope做排序依据，计算开销大且不唯一
分页参数校验要额外检查地理精度
普通分页只校验 page 和 size，GIS 分页还需拦截非法空间参数：空 bounds、无效 WKT、坐标越界（如纬度 >90）、极小范围（导致查不到数据但 OFFSET 仍执行）。
- 前端传的矩形范围通常为
minx,miny,maxx,maxy字符串，用strings.Split(c.Query("bounds"), ",")解析后，必须用strconv.ParseFloat并校验数值范围 - MySQL 中
ST_MakeEnvelope(minx, miny, maxx, maxy, 4326)若坐标反序（minx > maxx）会静默返回空几何，导致Count为 0 但分页查询无报错 - PostGIS 推荐用
ST_MakeBox2D+ST_SetSRID组合，并在WHERE中先用ST_IsValid过滤 - 若
bounds为空或解析失败，应直接返回400 Bad Request，而不是 fallback 到全量查询
Count 查询必须绕过空间谓词的性能陷阱
GIS 查询的 COUNT(*) 极易因空间索引未生效而变慢。更麻烦的是，db.Model(&Place{}).Where("ST_Within(location, ?)", env).Count(&total) 在 GORM 中会复用前面链上的空间条件，但若之前调用了 Limit/Offset，Count 就失效了——这是最常被忽略的坑。
- 必须用独立会话：
db.Session(&gorm.Session{NewDB: true}).Model(&Place{}).Where("ST_Within(location, ?)", env).Count(&total) - 对超大范围（如全球尺度），避免直接
COUNT，改用估算：db.Raw("SELECT reltuples::BIGINT FROM pg_class WHERE relname = 'places'").Scan(&approx)（PostgreSQL） - MySQL 可考虑用
EXPLAIN检查key_len是否命中空间索引，未命中则拒掉请求并告警 - 不要在事务里同时跑
Count和Find，空间函数在事务中可能因 MVCC 导致两次结果不一致
大数据量下必须放弃 OFFSET，改用游标+空间排序
当 POI 表超过 50 万条，且用户拖动地图频繁触发「视图内分页」时，OFFSET 会导致 MySQL 扫描并丢弃大量空间匹配行。此时唯一可靠方案是游标分页，但 GIS 游标不能只依赖 id——需结合空间距离和主键。
- 首次请求：用
ORDER BY ST_Distance(location, ?) ASC, id ASC LIMIT 20，取回第 20 条的id和ST_Distance值 - 下一页：WHERE 条件改为
ST_Distance(location, ?) > last_dist OR (ST_Distance(location, ?) = last_dist AND id > last_id) - PostGIS 可用
ORDER BY location ST_Point(116.4, 39.9)::geometry（KNN 操作符），性能远优于ST_Distance - 切记：游标分页不能用
Preload关联加载，空间查询的IN子句无法利用空间索引，应先查 ID 列表再批量加载关联数据
GIS 分页真正的难点不在 GORM 写法，而在空间索引是否生效、排序是否可穿透、游标是否能覆盖所有拓扑情况——这些没法靠封装函数掩盖，必须每一步都用 EXPLAIN 或 ST_Validate 验证。
