📋 目录
一、工具类功能
算两个经纬度点之间的球面距离(千米或米)、判断目标点落不落在给定半径的圆内、从起点沿方位角推出新坐标,按 Haversine 与地球平均半径算,不含高程也不做椭球修正。
二、所需环境
JDK 17或以上
三、方法与调用示例(按需调用)
🔢 方法序号:1
🎯 方法用途:
- 算两个经纬度点之间的球面距离,单位千米
- 门店与用户的远近、仓配距离展示这类场景用
🧩 方法定义:public static double distanceKm(double lng1, double lat1, double lng2, double lat2)
🗣️ 入参解释:public static double distanceKm(点1经度, 点1纬度, 点2经度, 点2纬度)
📤 返回值解释:double,两点间的球面大圆距离,单位千米
💡 边界口径:
- Haversine 公式,地球按平均半径 6371.0088 千米的正球体处理,不含高程、不做椭球修正
- 参数顺序统一经度在前、纬度在后,单位是度
- 坐标非法抛
IllegalArgumentException,消息里带上是哪一个点和原值 - 对映点的中间量已夹逼到 0 到 1,不会因浮点误差算出 NaN
🧪 方法示例:
- 门店到用户
distanceKm(storeLng, storeLat, userLng, userLat)拿到1.9 千米 - 门店到上海仓拿到
1067.3 千米 - 点1纬度给 91 度抛
点1经纬度非法: lng=0.0, lat=91.0 - 点2经度给 181 度抛
点2经纬度非法: lng=181.0, lat=1.0
🔢 方法序号:2
🎯 方法用途:
- 同两点距离但以米为单位,省掉调用方再乘 1000
- 配送半径、步行范围这类米级判断用它
🧩 方法定义:public static double distanceMeter(double lng1, double lat1, double lng2, double lat2)
🗣️ 入参解释:public static double distanceMeter(点1经度, 点1纬度, 点2经度, 点2纬度)
📤 返回值解释:double,两点间距离,单位米
💡 边界口径:
- 与
distanceKm同一套算法与校验,只是单位换算 - 不做四舍五入,展示位数由调用方控制
- 坐标非法同样抛
IllegalArgumentException
🧪 方法示例:
- 同一对点换算成米
distanceMeter(...)拿到1871.7 米,与 1.9 千米同源
🔢 方法序号:3
🎯 方法用途:
- 判断目标点是否落在以中心点为圆心的半径圆内
- 「附近 3 公里」「是否在配送范围」这类判断直接用它
🧩 方法定义:public static boolean withinRadius(double centerLng, double centerLat, double targetLng, double targetLat, double radiusM)
🗣️ 入参解释:public static boolean withinRadius(中心点经度, 中心点纬度, 目标点经度, 目标点纬度, 半径米)
📤 返回值解释:boolean,目标点在半径内返回 true
💡 边界口径:
- 边界算在圈内,半径恰好等于两点距离时返回
true - 半径必须大于 0,给 0 或负数抛
IllegalArgumentException - 半径给 NaN 不抛异常,一律判不在范围内,这是与坐标校验不同的口径
- 中心点或目标点坐标非法抛异常,消息点名是哪一个点
🧪 方法示例:
- 半径 3000 米时用户在圈内拿到
true - 同样半径下上海用户拿到
false,超出范围 - 半径恰好等于两点距离时拿到
true,边界算在圈内 - 半径比距离小 1 米拿到
false - 半径给 NaN 时拿到
false,不抛异常 - 半径给 0 抛
半径必须大于0,当前为0.0
🔢 方法序号:4
🎯 方法用途:
- 从起点按方位角走一段距离,推出终点坐标
- 画包围盒、生成航线中间点、按方向偏移查询中心时用
🧩 方法定义:public static LatLng destination(double lng, double lat, double distanceM, double azimuth)
🗣️ 入参解释:public static LatLng destination(起点经度, 起点纬度, 移动距离米, 方位角)
📤 返回值解释:LatLng,终点坐标的具名记录
💡 边界口径:
- 方位角以度计,正北为 0,超出 0 到 360 时按三角函数周期性自动等效
- 结果经度统一归一化到 -180 到 180,跨过 180 度经线不会给出越界值
- 距离为负、方位角为无穷大都抛
IllegalArgumentException - 起点坐标非法抛异常,消息里点明是起点
🧪 方法示例:
- 从门店向正北走 100 公里拿到
经度 116.4074 纬度 40.8035,再反算距离正好是100000.0 米 - 从东经 179 度向正东走 1000 公里,跨过 180 度经线后拿到
-172.0068 纬度 0.0,经度已归一化 - 配送圈 5 公里的北方向包围点拿到
经度 116.4074 纬度 39.94917 - 同一个圈的东、南、西三个包围点分别是
经度 116.46602 纬度 39.90419、经度 116.4074 纬度 39.85923、经度 116.34878 纬度 39.90419 - 距离给负数抛
移动距离不能为负,方位角给无穷大抛方位角必须为有限值,当前为Infinity - 起点经度给 NaN 抛
起点经纬度非法: lng=NaN, lat=0.0
🔢 方法序号:5
🎯 方法用途:
- 判断一组经纬度是否在合法区间内
- 入库前校验、接口入参体检用,避免把非法坐标喂进距离计算
🧩 方法定义:public static boolean isValid(double longitude, double latitude)
🗣️ 入参解释:public static boolean isValid(经度, 纬度)
📤 返回值解释:boolean,经度在 -180 到 180 且纬度在 -90 到 90 返回 true
💡 边界口径:
- 明确拒绝 NaN,无穷大因区间比较恒不成立同样被拒
- 只判区间,不判这个坐标是否真的存在地面上的某处
- 参数是基本类型,本方法不抛异常
🧪 方法示例:
- 正常坐标
isValid(116.4074, 39.9042)拿到true - 纬度 91 度拿到
false - 经度给 NaN 拿到
false
🔢 方法序号:6
🎯 方法用途:
- 手工装配一个经纬度点,作为具名记录在方法间传递
- 存包围盒、把
destination的结果与自造点混用时用它
🧩 方法定义:public record LatLng(double longitude, double latitude)
🗣️ 入参解释:public record LatLng(经度, 纬度)
📤 返回值解释:LatLng,不可变的坐标记录
💡 边界口径:
- 用字段名取代
double[]的下标,避免经度纬度顺序写反 - 是 record,同坐标的两份对象判等成立
- 构造时不做区间校验,要判合法请显式调
isValid - 距离与方位角方法返回的就是它
🧪 方法示例:
new LatLng(116.4, 39.9)拿到LatLng[longitude=116.4, latitude=39.9]- 取分量分别是
经度 116.4、纬度 39.9
四、工具类源码(可直接复制)
📦 源码文件