在Spring Boot项目里接入高德地图实现地理围栏，核心要解决两件事：一是如何把围栏数据存储下来并判断一个坐标点是否落在围栏内；二是如何周期性地获取目标对象的最新位置，触发进入或离开围栏的事件。高德地图提供了地理围栏相关的Web服务接口，但直接调用存在配额和调用频率限制，更合理的做法是把围栏定义保存在本地，用高德API完成坐标转换和逆地理编码辅助，真正包含判断由服务端算法完成。
高德地图地理围栏的基础思路与API选型
高德地图开放平台提供了地理围栏服务，但主要面向移动端SDK，服务端Web API里并没有一个可直接上传围栏并持续托管判断结果的一体化接口。服务端通常需要自己维护围栏的顶点集合，然后调用高德的坐标转换接口将GPS坐标统一为高德坐标系，再通过几何算法判断点是否在多边形内部。这样做的好处是围栏数据可以灵活存进MySQL或Redis，判断过程不依赖外部网络，适合高并发场景。
选型时要区分几个常见接口。地理编码接口用于把地址描述转成经纬度，逆地理编码则相反，适合把上报的坐标转成可读的位置信息。坐标转换接口可以把原始GPS坐标转换为高德坐标，避免因坐标系不一致导致偏差。还有搜索接口可以辅助创建围栏时查找POI边界。本文不直接依赖高德的地理围栏托管服务，而是利用这些基础接口配合本地围栏算法，这样即使高德接口偶发超时，核心判断也不受影响。
另外需要注意，高德Web服务API的key需要绑定服务类型，调用时会校验IP白名单和数字签名。在配置类里建议把key、私钥、接口域名都放在application.yml中，通过配置类读取，方便不同环境切换。高德的请求域名通常是restapi.amap.com，路径以/v3或/v5开头，参数里包含key和签名。签名算法是MD5，后面会给出具体封装。
Spring Boot工程配置与高德API客户端封装
先搭建一个基础的Spring Boot工程，引入Web、Scheduled和Lombok依赖。创建一个配置类AmapProperties，使用@ConfigurationProperties注解绑定amap前缀的配置项，包括key、secret和baseUrl。然后写一个AmapClient组件，内部用RestTemplate或WebClient发起HTTP请求，统一拼接公共参数并计算签名。高德的签名规则是：将请求参数按key排序，拼成key=value&key=value的字符串，末尾再拼上私钥，做MD5得到sign。例如坐标转换接口的参数包括key、locations、coordsys、output，加上私钥后计算签名。
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.util.UriComponentsBuilder;
import java.net.URI;
import java.security.MessageDigest;
import java.util.Map;
import java.util.TreeMap;
@Component
public class AmapClient {
private final RestTemplate restTemplate = new RestTemplate();
@Value("${amap.key}")
private String key;
@Value("${amap.secret}")
private String secret;
@Value("${amap.base-url}")
private String baseUrl;
public String convertCoord(String locations, String coordsys) throws Exception {
String path = "/v3/assistant/coordinate/convert";
Map<String, String> params = new TreeMap<>();
params.put("key", key);
params.put("locations", locations);
params.put("coordsys", coordsys);
params.put("output", "JSON");
String sign = sign(params, secret);
params.put("sig", sign);
URI uri = UriComponentsBuilder.fromHttpUrl(baseUrl + path)
.queryParams(toMultiValueMap(params))
.build(true)
.toUri();
return restTemplate.getForObject(uri, String.class);
}
private String sign(Map<String, String> params, String secret) throws Exception {
StringBuilder sb = new StringBuilder();
for (Map.Entry<String, String> entry : params.entrySet()) {
sb.append(entry.getKey()).append("=").append(entry.getValue()).append("&");
}
sb.append(secret);
MessageDigest md5 = MessageDigest.getInstance("MD5");
byte[] digest = md5.digest(sb.toString().getBytes("UTF-8"));
StringBuilder hex = new StringBuilder();
for (byte b : digest) {
String h = Integer.toHexString(0xff & b);
if (h.length() == 1) hex.append('0');
hex.append(h);
}
return hex.toString();
}
private org.springframework.util.MultiValueMap<String, String> toMultiValueMap(Map<String, String> map) {
org.springframework.util.LinkedMultiValueMap<String, String> result = new org.springframework.util.LinkedMultiValueMap<>();
result.setAll(map);
return result;
}
}
这里的AmapClient示例只展示了坐标转换接口的调用，实际项目中可以继续添加逆地理编码、天气查询等方法。需要强调的是，RestTemplate在Spring 6以后逐渐被RestClient替代，如果项目使用的是较新的Spring Boot版本，建议用RestClient或WebClient来写。签名计算时要保证参数顺序一致，使用TreeMap可以自动按字典序排列。另外不要把私钥硬编码在代码里，application.yml中的敏感信息建议用环境变量注入或配置中心管理。
接着定义围栏数据模型。一个多边形围栏由一组有序的经纬度点构成，可以设计成FenceEntity类，包含id、name、vertices字段，vertices用List<Point>存储。Point类包含lng和lat两个double字段。围栏数据可以存在内存Map中，也可以持久化到MySQL，通过Repository读取。示例为了方便，启动时初始化两个围栏，并提供一个FenceService负责判断。
地理围栏的核心判断逻辑：射线法解决点在多边形内
判断一个点是否在多边形内部，最常用的是射线法。从目标点向右引一条水平射线，统计这条射线与多边形各边的交点数，如果交点数为奇数，则点在多边形内部；偶数则在外部。这个算法对凸多边形和凹多边形都适用，时间复杂度为O(n)，n是顶点个数。处理边界情况时，要注意点恰好落在边上、射线经过顶点等特殊情况，可以通过约定取整规则来避免误判。
下面给出一个Java实现，输入目标点和围栏顶点列表，返回布尔值。算法思路是遍历每条边，判断边的两个端点是否在水平线的两侧，再计算交点x坐标是否大于目标点x。如果大于，计数器加一。最后根据计数器的奇偶性得出结论。代码中优先判断点是否在边上，如果点到线段的距离接近0，直接返回true，这样可以准确处理边界上的点。
import java.util.List;
public class GeoFenceUtils {
public static boolean isPointInPolygon(Point point, List<Point> vertices) {
if (vertices == null || vertices.size() < 3) {
return false;
}
boolean inside = false;
int n = vertices.size();
for (int i = 0, j = n - 1; i < n; j = i++) {
Point pi = vertices.get(i);
Point pj = vertices.get(j);
if (onSegment(pi, pj, point)) {
return true;
}
boolean intersect = ((pi.getLat() > point.getLat()) != (pj.getLat() > point.getLat()))
&& (point.getLng() < (pj.getLng() - pi.getLng()) * (point.getLat() - pi.getLat())
/ (pj.getLat() - pi.getLat()) + pi.getLng());
if (intersect) {
inside = !inside;
}
}
return inside;
}
private static boolean onSegment(Point a, Point b, Point p) {
double cross = (p.getLng() - a.getLng()) * (b.getLat() - a.getLat())
- (p.getLat() - a.getLat()) * (b.getLng() - a.getLng());
if (Math.abs(cross) > 1e-6) {
return false;
}
return p.getLng() >= Math.min(a.getLng(), b.getLng()) && p.getLng() <= Math.max(a.getLng(), b.getLng())
&& p.getLat() >= Math.min(a.getLat(), b.getLat()) && p.getLat() <= Math.max(a.getLat(), b.getLat());
}
}
如果需要支持圆形围栏，可以额外定义圆心和半径，判断距离是否小于半径。但在地理围栏实际业务中，多边形更符合园区、商圈、自定义区域的边界。高德地图的电子围栏也使用多边形表示，所以掌握射线法就足够。对于非常复杂的围栏，例如包含孔洞的多边形，需要扩展算法或使用JTS这类几何库，不过大部分业务场景用简单多边形即可。
另外，如果围栏数量很多，遍历所有围栏会有性能问题。可以通过先判断点是否在围栏的外接矩形内，再进入精确的射线法判断。外接矩形可以通过比较经纬度的最大最小值快速过滤，避免对每个围栏都做完整计算。当围栏数量达到数千级别，建议引入空间索引，比如Redis GEO或PostGIS的地理空间查询能力。
位置监控的定时任务与告警触发
围栏判断逻辑就绪后，位置监控可以通过定时任务实现。使用Spring的@Scheduled注解，每隔固定时间拉取一批设备的当前位置，调用围栏判断服务，对比设备上一次的围栏状态，如果从外部变为内部则触发进入事件，反之触发离开事件。设备位置来源可以是Redis缓存、数据库或者通过HTTP接口从车载终端、手机App上报。示例中以一个模拟的数据提供者来演示流程。
定义DeviceLocation类，包含设备ID、经度、纬度、上报时间。定义FenceStatus记录设备当前是否在围栏内以及所在围栏ID。定时任务里先获取所有在线设备的位置，再对每个设备判断是否在某个围栏内。状态变化时打印日志或发送消息到事件总线。这个逻辑要保证幂等，避免重复触发。可以维护一个ConcurrentHashMap保存上一次状态，判断后再更新。
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
@Service
public class LocationMonitorService {
private final FenceService fenceService;
private final Map<String, String> lastStatus = new ConcurrentHashMap<>();
public LocationMonitorService(FenceService fenceService) {
this.fenceService = fenceService;
}
@Scheduled(fixedDelay = 5000)
public void checkLocations() {
List<DeviceLocation> devices = fetchLatestLocations();
for (DeviceLocation device : devices) {
String fenceId = fenceService.findFenceContaining(device);
String newStatus = fenceId == null ? "OUTSIDE" : "INSIDE:" + fenceId;
String oldStatus = lastStatus.put(device.getDeviceId(), newStatus);
if (!newStatus.equals(oldStatus)) {
if (fenceId == null) {
System.out.println("设备 " + device.getDeviceId() + " 离开了围栏");
} else {
System.out.println("设备 " + device.getDeviceId() + " 进入围栏 " + fenceId);
}
}
}
}
private List<DeviceLocation> fetchLatestLocations() {
// 实际项目中从Redis或消息队列获取
return List.of(
new DeviceLocation("car-001", 116.397428, 39.90923, System.currentTimeMillis()),
new DeviceLocation("car-002", 116.481028, 39.989643, System.currentTimeMillis())
);
}
}
这里fixedDelay设为5秒只是演示，实际业务可能使用1分钟甚至更长时间。如果设备数量大，需要把拉取和判断改成批量并发处理，避免定时任务单线程阻塞。可以使用线程池或消息队列削峰。另外，当设备静止不动时，固定频率拉取会浪费资源，可以考虑设备侧主动上报位置变化，服务端只在收到上报时执行判断，这样比定时轮询更实时也更省资源。
告警触发后，可以对接短信、邮件、企业微信或WebSocket推送。示例中仅用System.out.println，生产环境应替换为事件发布。同时要记录每次状态变化的时间、围栏ID、设备ID和坐标，便于后续审计和轨迹回放。对于进入和离开事件，可以分别定义不同的处理策略，比如进入时提醒安保人员，离开时通知调度中心。
常见问题与优化建议
坐标系不一致是地理围栏落地时最容易踩的坑。高德地图使用GCJ-02坐标系，而很多GPS设备原始输出的是WGS-84坐标。如果直接把WGS-84坐标放进高德地图的围栏判断，可能出现几十到几百米的偏移。因此，在收到设备坐标后，务必调用高德的坐标转换接口或自己实现坐标偏移算法，统一转换到GCJ-02。高德API的坐标转换接口每次最多支持40个坐标，批量转换时要注意拆分。
围栏数据的更新和版本管理也很重要。围栏边界可能因为园区扩建、临时管制而变化，如果围栏数据是写死在代码里的，修改需要重新发布。建议将围栏数据放在数据库或配置中心，支持动态更新，并在FenceService中提供刷新缓存的方法。同时，在围栏变更时，需要对存量设备进行一次状态重算，避免漏报。如果围栏变更频繁，可以使用版本号机制，让每个判断请求携带版本号，渐变切换。
最后一个优化点是距离与几何判断的结合。对于圆形围栏或者需要接近提醒的场景，可以使用高德的距离测量接口或者本地Haversine公式计算两个坐标间的球面距离。当点在外围缓冲区时，提前触发预警，给业务留出反应时间。但要注意Haversine公式默认地球半径6371km，高德接口还会考虑路网影响，两者结果可能不同，需根据业务精度要求选择。
通过以上步骤，Spring Boot服务就能稳定地提供地理围栏与位置监控能力。代码结构清晰，围栏判断不依赖外部接口，仅在坐标转换时调用高德API，整体延迟可控。后续还可以扩展围栏的增删改查接口、围栏展示页面以及更复杂的事件处理逻辑。
Spring Boot高德地图地理围栏修改时间：2026-09-23 19:45:07