MySQL ST_PointAtDistance为何报距离越界

MySQL 的 ST_PointAtDistance 报距离越界，通常是第二个参数小于0，或超过这条折线的 ST_Length。参数表示从折线起点沿线累计的距离，不是百分比，也不是任意端点之间的直线距离。先核对同一份几何的总长度、SRID与输入单位，再决定拒绝输入还是按明确业务规则取端点。

官方地址：https://dev.mysql.com/doc/refman/8.4/en/spatial-operator-functions.html。本文按 MySQL 8.4 接口说明组织一个独立 SQL 小示例；代码未在本机执行，文中的点和长度为示例设计的预期值。

小项目目标：给一条折线按距离取点

假设应用有一条室内路线，用户输入沿路走过的距离，服务返回路线上的位置。我会先把这个功能缩小到“给定一条 LineString 和一个距离，返回一个 Point”，不把定位、地图匹配和导航路径规划混在一起。

问题的关键是沿线累计。折线拐弯时，取点距离要沿各线段累计；不能用起终点的直线距离代替总长度。示例路线先竖直移动6个坐标单位，再水平移动8个单位，合计14。距离9的位置应落在第二段上。

准备环境并确认几何类型和单位

准备可执行只读表达式和会话变量语句的 MySQL 8.4 会话即可，不需要建业务表。本文采用 SRID 0 的平面坐标例子，坐标单位由这组业务数据自行约定，不能自动称为米。实际数据使用其他空间参考系统时，应依据其定义及长度函数的单位约定处理。

ST_PointAtDistance 要求输入 LineString。输入其他几何类型可能产生 ER_UNEXPECTED_GEOMETRY_TYPE；几何本身损坏、引用不存在的空间参考系统也有各自错误。不要仅因为接口报错就全部归类为距离越界。

写出距离诊断与取点SQL

-- 独立示例：同一会话中使用自有变量，不创建或修改业务表。
SELECT VERSION() AS server_version;
SET @route = ST_GeomFromText('LINESTRING(2 1, 2 7, 10 7)', 0);
SET @distance = 9;
-- 先核对同一份几何的类型、SRID、长度与输入距离。
SELECT ST_GeometryType(@route) AS geometry_type,
       ST_SRID(@route) AS srid,
       ST_Length(@route) AS route_length,
       @distance AS requested_distance;
-- 在该示例中，9处于0到14之间，可以沿折线取点。
SELECT ST_AsText(ST_PointAtDistance(@route, @distance)) AS located_point;

按这组平面坐标推算，route_length 应为14，located_point 应为 POINT(5 7)：走完第一段6，再沿第二段走3。这里用容易手算的路线帮助理解范围，而不是以地图上看似合理的位置代替数值诊断。

把输入改为15时，应先得到越界状态；如果直接把15交给该路线的取点函数，按文档应报 ER_DATA_OUT_OF_RANGE，不是自动返回终点，也不是自动返回NULL。

-- 仅在上述示例有效几何基础上分类距离，不调用越界取点。
SET @distance = 15;
SELECT CASE
         WHEN @distance IS NULL THEN 'missing_distance'
         WHEN @distance  ST_Length(@route)
           THEN 'distance_out_of_range'
         ELSE 'distance_in_range'
       END AS distance_status;
-- 若要观察服务端原始错误，可单独执行下一句；预期为距离越界。
-- SELECT ST_PointAtDistance(@route, @distance);

这段 CASE 只对前面已明确构造的有效折线分类距离，不是通用几何修复器。应用仍要处理空几何、无效输入和数据库执行错误。实际驱动通常会返回错误码或错误对象，应保留其类型，避免把“查无记录”和“表达式失败”合并。

集成时显式处理越界输入

默认我会拒绝越界距离，并给调用方提供可接受范围。这样不会把上游单位不一致、路线更新或错误里程悄悄变成一个看似正常的终点。若产品明确规定超出路线就停在端点，可以选择截断，但必须把原始距离、采用的距离与是否发生截断作为业务状态区分。

集成时用参数绑定传递距离，先在应用中确认是允许范围内的有限数值。路线如果可能被更新，长度比较和取点应使用同一份路线值或同一版本，否则旧路线长度检查通过，新路线变短后仍可能失败。示例用同一会话变量固定几何，是为了让这一点直观。

不要为了消除错误随意修改 SRID 标签；更换标签不等于完成坐标转换。也不要默认所有输入的距离都以米计量，把平面坐标单位、业务公里数和参考系长度混用，正是越界或位置不符的常见来源。

对照预期与常见问题

在自己的环境里，可按有效折线、范围内距离、零距离、明确越界距离和缺失参数分别观察行为，并保留查询错误码。本文没有执行这些环境检查，也不提供伪造的客户端输出表格。上线前的核心是明确输入契约与错误分支，而不是捕获所有错误后返回一个默认坐标。

等于总长度也属于越界吗？

文档定义的范围包含两端，即0到ST_Length之间。接近端点时应考虑浮点表示与业务精度，不能随意扩大容差掩盖真正越界。业务如果直接需要最后顶点，可以使用LineString的端点语义，避免先将长度转成低精度文本再传回来。

距离0.5表示路线一半吗？

不表示，它是0.5个相应距离单位。比例位置属于另一类参数约定，不能因为函数名字相近就复用同一输入。

为什么有时候看到NULL而不是错误？

先检查参数是否为NULL以及应用是否自行吞掉错误。空参数与负值、超长距离不是同一种情况；本题的越界规则不能用NULL统一替代。

MultiLineString可以直接传入吗？

该函数要求LineString。多段独立路线应先明确业务如何选择或组合路线，不能只换一个几何类型名称就假设累计距离有唯一含义。