在SpringBoot中使用UniHttp简化天地图路径规划调用实践

写在最前面

前言

一、天地图路径规划简介

1、天地图相关服务

写在最前面

"苔花如米小*，也学* 牡丹开"，不才在下也参加了CSDN博客之星的年度评选。如果平时的博客对您有所帮助，有所触动，可以请您给在下投上宝贵的一票。骐骥一跃，不能十步；驽马十驾，功在不舍，技术的道路充满了坚持与努力。愿未来的前行中，可以彼此交流成长，万分感谢。投票地址：https://www.csdn.net/blogstar2024/detail/037。

前言

在当今数字化飞速发展的时代，地理信息系统（GIS）技术在众多领域发挥着至关重要的作用。从城市规划、交通管理到物流配送、出行导航，路径规划作为 GIS 的核心功能之一，其重要性不言而喻。天地图作为我国权威的地理信息公共服务平台，提供了丰富且精准的地理数据和强大的路径规划接口，为开发者们带来了极大的便利。在今天交通环境非常丰富的场景下，我们大家都是交通的密切参与者，而路径规划和导航应该是大家平时用得非常多的一个应用。比如高德、百度等互联网平台。下图是从百度地图截取的从长沙黄花国际机场到橘子洲景区的驾车路径规划信息，如下图所示：

通过导航的规划，很轻松的就可以掌握如何快速便捷的到达目的地。然而，在实际的项目开发中，尤其是在基于 Spring Boot 框架的应用里，直接调用相关互联网服务的路径规划接口往往面临着诸多挑战。接口的调用涉及到复杂的参数配置、身份认证以及数据格式的处理，这使得开发人员需要花费大量的时间和精力去研究和理解接口文档，编写繁琐的代码来实现与服务接口的交互。对于一些对地理信息系统不太熟悉的开发人员来说，这无疑增加了项目的开发难度和周期。

在这样的背景下，UniHttp 应运而生。UniHttp 是一款优秀的 HTTP 客户端工具，它以其简洁易用的 API 设计和强大的功能特性，为开发者们提供了一种更加高效、便捷的方式来处理 HTTP 请求。在 Spring Boot 项目中引入 UniHttp，可以极大地简化与路径规划接口的调用过程。通过使用 UniHttp，开发人员可以轻松地构建符合要求的 HTTP 请求，无需再纠结于底层的连接管理、请求头设置以及参数编码等细节问题。UniHttp 提供了直观的接口，让开发者能够以一种声明式的方式快速生成请求，同时它还具备良好的错误处理机制，能够及时捕获并反馈接口调用过程中出现的问题，方便开发人员进行调试和排查。

在本次技术博客中，我们将深入探讨如何在 Spring Boot 项目中利用 UniHttp 来简化天地图路径规划的调用实践。从项目的初始搭建，到 UniHttp 的集成配置，再到具体的天地图路径规划接口调用代码示例，以及对调用结果的解析和处理，我们都将进行详细的讲解和分析。希望通过本次分享，能够为广大开发人员提供一种更加高效、可靠的天地图路径规划调用解决方案，让大家在项目开发中能够更加轻松地应对地理信息相关的功能需求，提升项目的开发效率和质量，为推动地理信息系统技术在更多领域的应用贡献一份力量。

一、天地图路径规划简介

天地图作为一款在线的免费地图服务方，上面有很多的资源可以使用。如果是在线应用，大家可以直接使用来辅助自己的业务系统，提高产品研发的效率，降低空间技术开发的难度。比如本文提到的路径规划的服务。当然，基于在线模式的路径规划服务，有常见的百度、高德、腾讯地图等，还有我们的天地图，这里的地图数据是符合相关标准的，是规范的地图。因此大家可以放心使用，当然为了保证一些服务的可用，在调用相关的接口之前，需要进行开发者认证，其实也很简单，只要到官方网站上进行注册即可，在之前的博文中有一定讲解，在此不赘述。

1、天地图相关服务

天地图的API主要包含以下四类，如下图所示：

天地图的API服务主要包含四大类：1、地图API，2、Web端开发，3、WEB服务API，4、数据API。其中地图API主要是提供相关的底图服务，比如矢量底图、影像底图和它对应的注记地图。Web端API主要是提供前端的接口支持，提供Javascript3.0和4.0的相关操作接口。Web服务API主要是提供服务接口，不仅可以直接为前端请求，也可以为后台服务提供服务，可以无缝对接Java、Python、C#等多种语言。最后的数据API用得比较少，这里的服务暂时访问不了。之前咨询了官方技术人员，大家需要的可以自行去数据资源中下载即可。

2、天地图路径规划接口

首先不得不吐槽一下天地图的一些错误，在接口的说明上没有维护好元数据。比如下图中的公交规划和驾车规划，虽然是两个接口，但是关于接口的说明却不明确。

上图是公交规划的接口简介。下图是实际的驾车规划接口：

小瑕疵，还是期望有相关人员及时更新，毕竟是一个面向大众的互联网应用。下面以驾车路径规划为例，重点说说在天地图中的接口请求参数以及响应参数信息，这里帮大家整理好了，当然也可以到天地图的官网中查看相关说明。

驾车服务简介：

驾车服务API是一类简单的HTTP/HTTPS接口，根据输入起点、终点和途经点规划查询驾车路线。根据输入的起点、终点和途径点规划查询驾车路线。除了输入起始点，天地图还有一个非常实用的功能，就是添加途经点，它可以辅助我们进行更复杂的规划。

|--------|----------|-----------|---------------------------------|------------------------------------------------------------------------------|
| 参数 | 参数说明 | 参数类型 | 返回条件 | 备注 |
| orig | string | 起点经纬度 | 是 | -180,-90,180,90。 |
| dest | string | 终点经纬度 | 是 | -180,-90,180,90。 |
| mid | string | 途径点经纬度字符串 | 否 | 途径点字符串格式：116.35506,39.92277;116.35506,39.92277两个坐标之间以分号隔开，坐标xy之间用逗号隔开(都是半角)。 |
| style | string | 导航路线类型 | 默认0 （0：最快路线，1：最短路线，2：避开高速，3：步行） | 0-3。 |

以下是服务请求示例：

bash 复制代码

根据起点、终点经纬度字符串查询导航信息：http://api.tianditu.gov.cn/drive?postStr={"orig":"116.35506,39.92277","dest":"116.39751,39.90854","style":"0"}&type=search&tk=您的密钥
加入途径点的导航查询：http://api.tianditu.gov.cn/drive?postStr={"orig":"116.35506,39.92277","dest":"116.39751,39.90854","mid":"116.36506,39.91277;116.37506,39.92077","style":"0"}&type=search&tk=您的密钥

接下来是响应参数，这里也要提一下，天地图的响应参数格式xml，没错，它不是采用json的格式。这里也可以请官方的人士调整一下，毕竟目前很多接口的响应格式都是用的json。xml用的还是少了些。相应参数如下：

bash 复制代码

<?xml version="1.0" encoding="UTF-8" ?>
<result orig='起点经纬度' mid='途径点信息' dest='终点经纬度'>
    <parameters>
        <orig>起点加密经纬度</orig>
        <dest>终点加密经纬度</dest>
        <mid>途径点加密经纬度集合</mid>
        <key>经纬度加密的 key 值</key>
        <width>地图宽度</width>
        <height>地图高度</height>
        <style>导航路线类型</style>
        <version>版本控制</version>
        <sort>排序方式</sort>
    </parameters>
    <routes count='分段总数' time='查询时间'>
        <item id='0'>
            <strguide>每段线路文字描述</strguide>
            <signage>"路牌"引导提示/高速路收费站出口信息</signage>
            <streetName>当前路段名称</streetName>
            <nextStreetName>下一段道路名称</nextStreetName>
            <tollStatus>道路收费信息(0=免费路段，1=收费路段，2=部分收费路段)</tollStatus>
            <turnlatlon>转折点经纬度</turnlatlon>
        </item>
        <item id='1'>
            ....
        </item>
        ....其他分段线路信息
    </routes>
    <simple>
        <item id='0'>
            <strguide>每段线路文字描述</strguide>
            <streetNames>当前行驶路段名称（含多个路段）</streetNames>
            <lastStreetName>最后一段道路名称</lastStreetName>
            <linkStreetName>合并段之间衔接的道路名称</linkStreetName>
            <signage>"路牌"引导提示/高速路收费站出口信息</signage>
            <tollStatus>道路收费信息(0=免费路段，1=收费路段，2=部分收费路段)</tollStatus>
            <turnlatlon>转折点经纬度</turnlatlon>
            <streetLatLon>线路经纬度</streetLatLon>
            <streetDistance>行驶总距离（单位：米）</streetDistance>
            <segmentNumber>合并后的号段，对应详细描述中的号段</segmentNumber>
        </item>
        <item id='1'>
            ....
        </item>
        ....其他分段线路信息
    </simple>
    <distance>全长（单位：公里）</distance>
    <duration>行驶总时间（单位：秒）</duration>
    <routelatlon>线路经纬度字符串</routelatlon>
    <mapinfo>
        <center>全部结果同时显示的适宜中心经纬度</center>
        <scale>全部结果同时显示的适宜缩放比例</scale>
    </mapinfo>
</result>

以上就是天地图的驾车规划接口详情介绍，希望大家可以熟悉接口的入参和响应参数。在后续的接口调用介绍中会使用到。

二、UniHttp简介

从企业级项目来说，传统的接口访问我们会使用编程式Http客户端比如HttpClient、Okhttp去直接对接第三方Http接口，那么项目一定充斥着大量的对接逻辑和代码。本节将重点讲解Unihttp的相关知识，可以通过uniHttp来简化http接口的调用。

1、UniHttp是什么？

UniHttp是一个声明式的Http请求对接框架，能以极快的方式完成对一个第三方Http接口的对接和使用，只要配置一下即可重复使用，不需要开发者去关注如何发送一个请求，如何去传递Http请求参数，以及如何对请求结果进行处理和反序列化，这些框架都帮你一一实现就像配置 Spring的Controller 那样简单，只不过相当于是反向配置而已。该框架更注重于如何保持高内聚和可读性高的代码情况下与快速第三方渠道接口进行对接和集合，而非像传统编程式的Http请求客户端（比如HttpClient、Okhttp）那样专注于如何去发送和响应一个Http请求，二者并不冲突只是注重点不一样，UniHttp 目前底层也是用的Okhttp去发送请求。与其说的是对接的Http接口，不如说是对接的第三方渠道，UniHttp可支持自定义接口渠道方HttpAPI注解以及一些自定义的对接和交互行为，为此扩展了发送和响应和反序列化一个Http请求接口的各种生命周期钩子需要开发者去自定义实现。

这里只对其做一个简单介绍，关于其强大的方法，在后续的内容中结合相关案例进行介绍。

2、UniHttp能做什么？

首先来看一下UniHttp的官方API文档，如下所示：

官方api手册的地址是：UniHttp文档。如何在Java环境中集成上述组件有详细的说明。在Springboot中引入UniHttp的Maven声明如下所示，这里我们使用的版本是0.0.8：

XML 复制代码

<!--  增加uniapi-http add by 夜郎king in 2025.02.14 begin -->
<dependency>
	<groupId>io.github.burukeyou</groupId>
	<artifactId>uniapi-http</artifactId>
	<version>0.0.8</version>
</dependency>
<!--  增加uniapi-http add by 夜郎king in 2025.02.14 end -->

三、UniHttp调用天地图接口

1、请求接口的定义

在SpringBoot中定义相关接口的代理类，这个比较简单，直接创建一个接口即可，为了演示方便，这里定义了天地图中的两个地址，一个是地理名称检索以及驾车路径规划调用。具体Java接口方法如下：

java 复制代码

package com.yelang.project.thridinterface;
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;

@HttpApi(url = "http://api.tianditu.gov.cn/")
public interface ITdtOptionService {
	@GetHttpInterface("geocoder")
	HttpResponse<String> getGeocoder(@QueryPar("ds") String ds,@QueryPar("tk") String tk);

	@GetHttpInterface("drive")
	HttpResponse<String> drivePlan(@QueryPar("postStr") String postStr,@QueryPar("type") String type,@QueryPar("tk") String tk);
}

2、实际调用

为了演示方便，这里以Junit为例，重点讲解如何在SprintBoot环境中进行集成和调用。代码如下（请注意，下面代码中的key需要大家到天地图中去申请才能看到结果）：

java 复制代码

package com.yelang.project.unihttp;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import com.burukeyou.uniapi.annotation.UniAPIScan;
import com.burukeyou.uniapi.http.core.response.HttpResponse;
import com.yelang.project.thridinterface.ITdtOptionService;

@SpringBootTest
@RunWith(SpringRunner.class)
@UniAPIScan("com.yelang.project.thridinterface") // 指定@HttpApi接口所在的包路径
public class TdtUniHttpCase {
	//服务端访问key
	//private static final String TDT_BROWSE_KEY = "xxx";
    private static final String TDT_SERVER_KEY = "xxx";
	@Autowired
	private ITdtOptionService tdtOptService;
	@Test
	public void testGeocoder() {
		String target = "北京市延庆区延庆镇莲花池村前街50夕阳红养老院";
		String keyWord = "%7B'keyWord':'" + target + "'%7D" ;
		HttpResponse<String> resp = tdtOptService.getGeocoder(keyWord, TDT_SERVER_KEY);
		System.out.println(resp.getBodyResult());
	}
	@Test
	public void testDrivePlan() {
		String origInfo = "113.216171,28.190967";//黄花国际机场
		String destInfo = "112.957124,28.198626";//橘子洲景区
		// style 默认0 （0：最快路线，1：最短路线，2：避开高速，3：步行）
		// 这里选择避开高速
		String postStr = "%7B'orig':'" + origInfo + "','dest':'" + destInfo + "','style':'2'%7D" ;
		HttpResponse<String> resp = tdtOptService.drivePlan(postStr,"search",TDT_SERVER_KEY);
		System.out.println(resp.getBodyResult());
	}
}

在第二个驾车的规划中，在参数中需要传的经纬度位置，而日常生活中，我们通常拿到的都是地址信息，因此还需要一个根据中文名称找它的对应经纬度位置的过程。当然我们也可以直接调用天地图的服务来实现。这里假设已经成功的获取起始点和目标点的经纬度坐标。

3、相应结果展示

上面的起始点和目标点分别是：长沙黄花机场和橘子洲风景区。将两者作为导航的起始点输入，默认选用避开高速的方式（最小成本的模式），最后得到的响应结果如下：

我们将得到的响应结果格式化之后可以看到以下的信息：

基本上可以跟导航软件上实现的结果是一致的，由此可以得到具体路径规划信息。通过这个实验表明，通过天地图的驾车路径规划服务可以得到满足我们日常使用的一些接口。后续大家可以基于这种方法进行业务开发。当然，前提是一定要去注册天地图的开发者才可以调用相关服务。

四、总结

以上就是本文的主要内容，在本次技术博客中，我们将深入探讨如何在 Spring Boot 项目中利用 UniHttp 来简化天地图路径规划的调用实践。从项目的初始搭建，到 UniHttp 的集成配置，再到具体的天地图路径规划接口调用代码示例，以及对调用结果的解析和处理，我们都将进行详细的讲解和分析。希望通过本次分享，能够为广大开发人员提供一种更加高效、可靠的天地图路径规划调用解决方案，让大家在项目开发中能够更加轻松地应对地理信息相关的功能需求，提升项目的开发效率和质量，为推动地理信息系统技术在更多领域的应用贡献一份力量。行文仓促，难免有许多不足之处，如有不足，在此恳请各位专家博主在评论区不吝留言指出，不胜感激。

参考内容：

1、HTTP客户端框架之UniHttp讲解。

2、天地图驾车服务API。