Spring Boot 集成高德地图电子围栏

摘要：本文手把手教你通过 Spring Boot 调用高德地图 API 实现电子围栏功能，涵盖云端围栏创建、设备位置监控与本地算法校验，附带完整代码和避坑经验！

---

一、电子围栏核心原理

1.1 什么是电子围栏？

• 虚拟地理边界：在地图上划定区域（圆形/多边形），触发进出事件
• 应用场景：员工考勤、物流围栏、儿童安全区域监控
• 技术核心：基于 GPS/北斗坐标的位置判断（射线法或API调用）

1.2 高德地图API能力

• 云端围栏管理：创建、删除、查询围栏
• 实时状态检测：设备进入/离开围栏时触发回调
• 坐标系支持：GCJ-02（火星坐标系）

---

二、Spring Boot 集成高德API实战

2.1 环境准备

（1）添加 Maven 依赖

<dependency>
    <groupId>org.springframework.bootgroupId>
    <artifactId>spring-boot-starter-webartifactId>
dependency>

<dependency>
    <groupId>org.apache.httpcomponentsgroupId>
    <artifactId>httpclientartifactId>
    <version>4.5.13version>
dependency>

（2）配置高德 Key

application.yml 中配置：

amap:
  key: your_amap_key  # 前往高德开放平台申请
  geo-fence-url: https://restapi.amap.com/v4/geofence/meta

---

2.2 核心代码实现

（1）高德API服务封装

@Service
public class AmapGeoFenceService {
    @Value("${amap.key}")
    private String amapKey;

    /**
     * 创建电子围栏（支持多边形）
     * @param name 围栏名称
     * @param points 坐标点（格式：lng1_lat1,lng2_lat2,...）
     * @return 围栏ID
     */
    public String createGeoFence(String name, String points) {
        RestTemplate restTemplate = new RestTemplate();
        String url = String.format("%s?key=%s&name=%s&points=%s", 
                geoFenceUrl, amapKey, URLEncoder.encode(name), points);
        
        ResponseEntity<String> response = restTemplate.postForEntity(url, null, String.class);
        // 解析返回结果获取 fence_id
        JsonNode root = JsonUtils.parse(response.getBody());
        return root.get("data").get("fence_id").asText();
    }
}

（2）业务逻辑层

@Service
@RequiredArgsConstructor
public class GeoFenceService {
    private final AmapGeoFenceService amapService;
    private final GeoFenceRepository fenceRepository;

    /**
     * 创建围栏并保存到数据库
     */
    @Transactional
    public String createFence(GeoFenceDTO dto) {
        // 坐标点格式转换
        String pointsStr = dto.getPoints().stream()
                .map(p -> p.getLng() + "_" + p.getLat())
                .collect(Collectors.joining(","));
        
        // 调用高德API
        String fenceId = amapService.createGeoFence(dto.getName(), pointsStr);
        
        // 保存到数据库
        GeoFence fence = new GeoFence();
        fence.setFenceId(fenceId);
        fence.setName(dto.getName());
        fenceRepository.save(fence);
        return fenceId;
    }
}

---

2.3 实现效果演示

（1）创建围栏 API 请求

POST /api/fences
Content-Type: application/json

{
  "name": "公司安全区",
  "points": [
    {"lng": 116.397504, "lat": 39.89619},
    {"lng": 116.407504, "lat": 39.89619},
    {"lng": 116.397504, "lat": 39.90619}
  ]
}

（2）返回结果

{
  "fenceId": "1234567890"
}

---

三、避坑指南

3.1 常见问题排查

问题现象	原因分析	解决方案
API返回INVALID_USER_KEY	高德Key未配置或错误	检查application.yml
围栏未触发通知	设备未开启定位权限	引导用户授权定位
坐标偏移严重	坐标系不一致（如WGS-84）	调用高德坐标转换API

3.2 性能优化建议

• 本地缓存：使用 Redis 缓存围栏坐标数据，减少数据库查询
• 批量校验：多个设备位置通过高德 batch/status 接口批量查询
• 围栏简化：对多边形顶点做道格拉斯-普克抽稀算法处理