SpringBoot 联合 PostGIS 实现在线地图行政区划离线存储

需要注意的是，这里没有增加空间索引和其他的物理索引。在实际业务中，我们会经常进行行政区划内的数据检索，因此建议大家在使用时，对行政区边界坐标点字段设计一个空间索引。

二、行政区划在线 API

本节将重点介绍高德地图的行政区划检索在线 API，主要包括请求参数和响应参数。这是后续我们使用在线地图的基础知识。行政区域查询是一类简单的 HTTP 接口，根据用户输入的搜索条件可以帮助用户快速的查找特定的行政区域信息。例如：中国>山东省>济南市>历下区>舜华路街道（国>省>市>区>街道）。

parameters 代表的参数包括必填参数和可选参数。所有参数均使用和号字符 (&) 进行分隔。下面的列表枚举了这些参数及其使用规则。

1、请求参数简介

2、响应参数简介

行政区域查询的响应结果的格式由请求参数 output 指定。

三、Java 后台数据获取及空间存储

SpringBoot 是一个开源的 Java 基于 Spring 框架的快速开发平台，它简化了基于 Spring 框架的应用开发，通过一系列的默认配置和约定，让开发者能够快速搭建出稳定、高效的系统。PostGIS 是一个开源对象关系型空间数据库扩展，它允许用户在 PostgreSQL 数据库中存储和操作地理空间数据，提供了强大的空间数据类型和几何函数。通过将 SpringBoot 与 PostGIS 结合，我们可以充分利用 SpringBoot 的开发优势和 PostGIS 的地理空间处理能力，构建出一个高效、稳定的在线地图行政区划离线存储系统。在实践过程中，我们将面临数据格式转换、性能优化以及数据更新与同步等挑战，但这些挑战也将为我们提供宝贵的经验和学习机会。

1、API 服务调用

为了简化调用，我们使用 UniHttp 进行在线服务的集成，接口定义如下：

package org.yelang.pcwater.amap.service;
import com.burukeyou.uniapi.http.annotation.HttpApi;
import com.burukeyou.uniapi.http.annotation.param.QueryPar;
import com.burukeyou.uniapi.http.annotation.request.GetHttpInterface;
import com.burukeyou.uniapi.http.core.response.HttpResponse;

/**
 * - 高德地图开放平台 API 接口，负责与高德交互
 */
@HttpApi(url = "https://restapi.amap.com")
public interface AmapService {
    /**
     * - 行政区域查询 API 服务
     *
     * @param key 请求服务权限标识，必填
     * @param keywords 查询关键字
     * @param subdistrict 子级行政区
     * @param extensions 此项控制行政区信息中返回行政区边界坐标点；可选值：base、all;
     * -base:不返回行政区边界坐标点；all:只返回当前查询 district
     * -的边界值，不返回子节点的边界值；目前不能返回乡镇/街道级别的边界值
     * @return
     */
    @GetHttpInterface("/v3/config/district")
    public HttpResponse<String> district(@QueryPar("key") String key, @QueryPar("keywords") String keywords, @QueryPar("subdistrict") int subdistrict, @QueryPar("extensions") String extensions);
}

下面针对返回的数据进行反序列化，将字符串转换为对象，后续可以直接进行数据入库。对应我们定义两个 JavaBean 实体类，一个是行政区划响应类，代码如下：

package org.yelang.pcwater.amap.dto.amap.district;
import java.util.List;
import org.yelang.pcwater.amap.dto.amap.CommonDTO;
import lombok.AllArgsConstructor;
import lombok.EqualsAndHashCode;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import lombok.ToString;

@NoArgsConstructor
@AllArgsConstructor
@Setter
@Getter
@ToString(callSuper=true)//callSuper=true 表示输出父类属性
@EqualsAndHashCode(callSuper=true)
public class DistrictRespDTO extends CommonDTO{
    private static final long serialVersionUID = 3562870512223434443L;
    private List<DistrictDTO> districts;//行政区列表
}

还有一个最重要的行政区划信息类，在这里类中包含了一个 List 的集合，就是用来保存当前行政区划的下级单位，代码如下：

package org.yelang.pcwater.amap.dto.amap.district;
import java.io.Serializable;
import java.util.List;
import com.google.gson.annotations.SerializedName;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import lombok.ToString;

/**
 * - 行政区信息数据传输对象
 */
@NoArgsConstructor
@AllArgsConstructor
@Setter
@Getter
@ToString
public class DistrictDTO implements Serializable{
    private static final long serialVersionUID = -6086240995930742268L;
    @SerializedName("citycode")
    private String cityCode;//城市编码
    private String adcode;//区域编码
    private String name;//行政区名称
    private String polyline;//行政区边界坐标点
    private String center;//区域中心点
    private String level;//行政区划级别
    private List<DistrictDTO> districts;//下级行政区列表，包含 district 元素
}

2、递归获取数据

下面以深圳市为例，详细讲解三级行政区划的数据获取及离线存储。在前面的接口说明中，已经了解了一次可以返回多个下层数据的信息。大家可以根据自己的需要来调整业务，但是不可避免的需要对不同层级的数据进行统一处理。这里演示一种简单的使用递归的方式来进行数据的获取。

package org.yelang.pcwater.service.impl;
import java.util.ArrayList;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.yelang.pcwater.amap.dto.amap.district.DistrictDTO;
import org.yelang.pcwater.amap.dto.amap.district.DistrictRespDTO;
import org.yelang.pcwater.amap.service.AmapService;
import org.yelang.pcwater.domain.RegionInfo;
import org.yelang.pcwater.mapper.RegionInfoMapper;
import org.yelang.pcwater.service.IRegionInfoService;
import org.yelang.pcwater.utils.PolygonStringToWKTConverter;
import org.yelang.pcwater.utils.StringUtils;
import com.baomidou.mybatisplus.core.toolkit.IdWorker;
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.burukeyou.uniapi.http.core.response.HttpResponse;
import com.google.gson.Gson;

@Service
public class RegionInfoServiceImpl extends ServiceImpl<RegionInfoMapper, RegionInfo> implements IRegionInfoService{
    // 高德地图的 key，需要替换成自己申请的 key
    private static final String DEFAULT_AMAP_KEY = "yourkey";
    private static final String EXTENSIONS = "all";
    
    @Autowired
    private AmapService amapService;
    
    @Override
    public void syncDistrict() throws InterruptedException {
        Gson gson = new Gson();
        int subdistrict = 3;// 返回下三级行政区
        HttpResponse<String> result = amapService.district(DEFAULT_AMAP_KEY, "深圳市", subdistrict, EXTENSIONS);
        if (StringUtils.isEmpty(result.getBodyResult())) {
            return;
        }
        DistrictRespDTO districtRespDTO = gson.fromJson(result.getBodyResult(), DistrictRespDTO.class);
        List<RegionInfo> regionList = new ArrayList<RegionInfo>();
        this.extractDistrict(districtRespDTO.getDistricts(), regionList, 0L);
        if(StringUtils.isEmpty(regionList)) {
            return ;
        }
        for (RegionInfo regionInfo : regionList) {
            String polylineGeom = regionInfo.getPolylineGeom();
            String level = regionInfo.getLevel();
            //市、区等行政区划如果第一轮没有采集需要重新获取行政区划边界
            if(StringUtils.isEmpty(polylineGeom) && (level.equalsIgnoreCase("city") || level.equalsIgnoreCase("district"))) {
                //System.out.println("单独处理边界" + regionInfo.getAdcode()+ regionInfo.getName());
                //这里只需要返回当前层级即可
                HttpResponse<String> _tempResp = amapService.district(DEFAULT_AMAP_KEY, regionInfo.getAdcode(), 0, EXTENSIONS);
                String amapPolyline = this.getPolyline(_tempResp.getBodyResult());
                if(StringUtils.isNotEmpty(amapPolyline)) {
                    String polylineGeomWkt = PolygonStringToWKTConverter.convertToWKT(amapPolyline);
                    regionInfo.setPolylineGeom("SRID=" + 4326 + ";" + polylineGeomWkt);//拼接 srid，实现动态写入
                }
                Thread.sleep(100);
            }
        }
        this.saveBatch(regionList, 50);
    }

    /**
     * - 行政区划信息抽取
     * @param dataList
     * @param regionList
     * @param parentId
     */
    public void extractDistrict(List<DistrictDTO> dataList, List<RegionInfo> regionList, Long parentId) {
        if (StringUtils.isNotEmpty(dataList)) {
            for (DistrictDTO dto : dataList) {
                Long pkId = IdWorker.getId();
                String center = dto.getCenter();
                String polyline = dto.getPolyline();
                String level = dto.getLevel();
                double lon = Double.parseDouble(center.split(",")[0]);
                double lat = Double.parseDouble(center.split(",")[1]);
                String centerGeomWkt = PolygonStringToWKTConverter.point(lon, lat);
                RegionInfo region= new RegionInfo(pkId, parentId, dto.getCityCode(), dto.getAdcode(), dto.getName(), center, level, lon, lat, "SRID=" + 4326 + ";" + centerGeomWkt);
                if(StringUtils.isNotEmpty(polyline)) {
                    String polylineGeomWkt = PolygonStringToWKTConverter.convertToWKT(polyline);
                    region.setPolylineGeom("SRID=" + 4326 + ";" + polylineGeomWkt);//拼接 srid，实现动态写入
                }
                regionList.add(region);
                if (StringUtils.isNotEmpty(dto.getDistricts())) {
                    extractDistrict(dto.getDistricts(), regionList, pkId);
                }
            }
        }
    }

    /**
     * - 从响应文本中获取边界
     * @param responseResult 响应文本
     * @return
     */
    public String getPolyline(String responseResult) {
        String result = "";
        if (StringUtils.isEmpty(responseResult)) {
            return result;
        }
        DistrictRespDTO districtRespDTO = new Gson().fromJson(responseResult, DistrictRespDTO.class);
        if(null != districtRespDTO && StringUtils.isNotEmpty(districtRespDTO.getDistricts())) {
            result = districtRespDTO.getDistricts().get(0).getPolyline();
        }
        return result;
    }
}

使用以上代码就可以实现将行政区划代码离线存储保存到空间数据库中。大家可以使用 Junit 的方式进行集成，也可以做成 API 的方式进行调用。需要说明的是，在使用高德地图时，返回的数据坐标是高德的坐标系，在设置 SRID 时，大家可以使用 4326，但是在程序中需要进行标注，尤其是在别的底图上展示时，对坐标进行处理，处理偏移的问题。具体的处理方法，这里不进行赘述。

四、成果展示

本节将对深圳的三级行政区划信息进行展示，包括直接在 PostGIS 中进行查询和 WebGIS 可视化。以此验证我们的数据采集是否成功。

1、PostGIS 数据查询

在我们的程序中调用数据库的方法后，可以实现将深圳市的三级行政区划数据进行 PostGIS 存储，下面来验证一下是否成功，使用以下 SQL 语句查询，

select * from biz_region_info;

在 Navicat 客户端中执行以上 sql 后，在返回结果中可以看到以下内容：

如果能看到输出，说明数据已经成功进行了采集。

2、WebGIS 可视化

根据实际的需要，我们可以将上述的行政区划数据进行空间可视化。这里我们使用 Leaflet 对深圳市的三级区划进行展示，这里仅演示实际的效果，具体 Leaflet 的集成内容，之前有系列博客讲解。

深圳市行政区划

坪山行政区划

五、总结

以上就是本文的主要内容，本文将深入探讨如何结合强大的 SpringBoot 框架和专业的地理空间数据库 PostGIS，以高德地图开放平台为例，实现在线地图行政区划数据的离线存储，以满足多样化的业务需求，提升系统的灵活性和可靠性。通过本次实践探索，我们不仅能够掌握 SpringBoot 和 PostGIS 在地理空间数据处理方面的应用，还能深入了解在线地图数据离线存储的关键技术和实现方法。这将为我们在地理信息系统开发、大数据处理、移动应用开发等领域提供宝贵的经验和参考。