Go rtreego 空间对象维数不一致会怎样

我在把二维坐标接入 rtreego 时，最容易误判的一点是：空间对象“看起来像坐标”并不代表它已经满足 R-tree 的维数契约。当前包文档把 Rtree 定义为带固定空间维数的索引，Point 是任意维度的浮点切片，而 Rect 由每一维的起点和长度组成。只要这些长度没有统一，结果可能不是一个统一的错误，而是构造阶段返回 DimError，或者在距离查询内部直接触发 panic。

先记住结论：NewRect 和 NewRectFromPoints 会把维数不一致交给调用方处理；最近邻计算里的维数断言则可能 panic。把维度检查放到对象创建和查询入口，才不会让错误拖到索引内部。

• 树的约定：NewTree(2, ...) 表示索引按二维空间组织。
• 几何的约定：二维点应有两个坐标，矩形的起点和长度也都应有两个分量。
• 错误形态：几何构造 API 返回 *DimError；距离相关的内部检查使用 panic 表达断言失败。

树、对象与几何数据必须共享维数

rtreego 的空间对象通过 Bounds() Rect 提供边界矩形。这个接口本身不会替你把一维、二维和三维数据转换成同一种空间；树的 Dim、对象返回的 Rect、查询矩形和最近邻查询点，应该在业务层保持一致。

例如，二维树通常使用两个坐标的点和两个边长的矩形。这里的“二维”不是指坐标值必须是整数，也不是指矩形只能落在正数区域，而是指每个空间值都要有两个对应分量。把第三个业务字段混进坐标切片，或者把二维查询点传给三维数据，都会破坏这个约定。

构造 Rect 时为什么能拿到 DimError

构造几何对象时，库会比较点和长度切片的长度。如果它们不相等，NewRect 返回的错误就是维数错误；用两个角点构造矩形时，NewRectFromPoints 也会先比较两个点的维数。这个阶段应该正常处理错误，而不是继续把返回的零值矩形塞进树。

package main

import (
    "errors"
    "fmt"

    "github.com/dhconnelly/rtreego"
)

func makeRect() (rtreego.Rect, error) {
    point := rtreego.Point{10, 20}
    lengths := []float64{5} // 中文注释：故意少一个分量，演示二维契约被破坏

    rect, err := rtreego.NewRect(point, lengths)
    if err != nil {
        var dimErr *rtreego.DimError
        if errors.As(err, &dimErr) {
            // 中文注释：先识别维数错误，再把错误交给上层决定如何处理
            return rtreego.Rect{}, fmt.Errorf("空间维数不一致: %w", err)
        }
        return rtreego.Rect{}, err
    }
    return rect, nil
}

这里没有依赖错误字符串来判断类型，而是用 errors.As 识别 *rtreego.DimError。真实项目中可以把维度检查提前到 DTO 转换或领域对象构造处；如果错误已经被包装，仍然能保留类型判断。不要只记录“创建矩形失败”，否则排查时很难区分维数问题和长度为零等几何错误。

为什么最近邻查询有时会直接 panic

构造函数有明确的 error 返回值，但距离计算是另一条路径。包源码中的点到矩形距离函数会先比较点的长度与矩形坐标长度，不一致时触发 DimError 的 panic。NearestNeighbor 和 NearestNeighbors 会使用这类距离计算，因此不能把一个错误维度的查询点当作普通“查不到结果”来处理。

这也解释了一个常见误会：树中没有匹配对象，通常应该得到空结果；但查询点的维度不对，属于调用契约被破坏，可能在搜索过程中 panic。是否能捕获 panic 不是修复方案，正确做法是在进入查询前检查点长度，并让树的维度成为业务对象的固定配置。

把维度检查放在哪一层更稳妥

如果每个业务对象都有 Bounds()，可以让对象构造器只接受固定维度的坐标；如果查询来自 HTTP、消息队列或文件，则在解析层把数组长度校验完，再创建 Point。下面的入口示例只展示检查关系，不代表某次线上运行结果。

const spatialDim = 2

func checkPoint(p rtreego.Point) error {
    if len(p) != spatialDim {
        // 中文注释：在调用最近邻查询前拦截错误维度，避免把断言推迟到库内部
        return fmt.Errorf("point 维数=%d，期望=%d", len(p), spatialDim)
    }
    return nil
}

func nearest(tree *rtreego.Rtree, p rtreego.Point) ([]rtreego.Spatial, error) {
    if err := checkPoint(p); err != nil {
        return nil, err
    }
    // 中文注释：查询点通过入口检查后，再交给固定二维树做最近邻搜索
    return tree.NearestNeighbors(3, p), nil
}

对象入口也应该做同样的事情：Bounds() 返回的矩形长度必须等于 spatialDim，而不是等插入时才发现。若系统同时支持二维和三维索引，建议把维度放进索引实例或数据类型中，避免用一个裸的 []float64 在不同空间之间流动。

排查时怎样快速判断是哪类问题

实际排查时，先打印或记录“树维数、对象边界维数、查询参数维数”这三个结构化字段，再看错误发生在哪个 API。这样比只看一行 dimension mismatch 更容易找到数据从哪一层变形。

Go rtreego 维数不一致常见问题 FAQ

维数不一致一定会返回 error 吗？

不一定。NewRect 和 NewRectFromPoints 这类构造函数会返回 DimError；距离计算内部则可能通过 panic 表达不变量被破坏。

把查询点补一个 0 就可以了吗？

只有当业务模型确实是对应的三维空间，并且树、对象边界和查询语义都采用同一维度时才可以。为了消除 panic 临时补 0，可能把二维数据错误地解释成三维数据。

可以用 recover 统一处理吗？

可以把 recover 作为服务边界的最后一道保护，但不能替代输入校验。更可靠的做法是让空间类型携带固定维度，在构造对象和查询参数时尽早返回普通错误。

R-tree 插入时会自动检查对象维数吗？

不要假定它会为每一种路径主动返回同一个维数错误。应确保 Bounds() 与树的 Dim 一致，并在业务层校验后再插入；这样能避免错误进入索引内部才暴露。

因此，rtreego 的维数问题不是“查不到数据”的普通结果，而是空间模型契约没有统一。构造阶段及时处理 DimError，查询阶段提前检查点和矩形的长度，并让对象类型携带维度约束，才是长期稳定的修复方式。