使用 Spring Boot 整合高德地图实现路线规划功能
作者:一位拥有8年Java开发经验的程序员
时间:2025年7月
一、业务场景分析
在日常的开发项目中,地图服务是很多系统的核心能力之一,尤其是在物流、同城配送、出行导航等领域。作为一名有多年后端开发经验的工程师,我在近期的一个项目中,需要实现以下功能:
用户下单后,系统需要根据起点和终点地址,自动计算推荐路径(驾车)与预计耗时、距离,从而用于后续调度与价格评估。
该功能涉及地图服务的路线规划接口调用。市面上的地图服务有高德、百度、腾讯等,考虑到高德地图的接口文档丰富、服务稳定、性能高、价格可控,最终选择了高德地图作为路线规划服务提供商。
二、技术实现思路
整个技术实现主要包含以下几个步骤:
- 申请高德地图 Web 服务的开发者 Key(AK)
- 理解高德路线规划 API 的接口规范
- 构建 Spring Boot 项目,封装 HTTP 请求调用接口
- 定义统一的请求与响应模型
- 结合业务逻辑处理路线结果,例如选择最优方案、计算耗时、距离等
三、高德地图路线规划 API 简介
高德路线规划 API 提供了多种出行方式的路线规划服务,包括驾车、公交、步行、骑行、货车导航等。
我们选择的接口是:
-
接口名称:驾车路线规划
-
请求方式:GET
-
核心参数:
origin
:起点经纬度(如:116.481028,39.989643)destination
:终点经纬度(如:116.434446,39.90816)key
:开发者 Key
四、Spring Boot 项目整合步骤
4.1 创建 Spring Boot 项目
使用 Spring Boot 3.x,添加以下依赖:
xml
<dependencies>
<!-- Web -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- JSON处理 -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
</dependency>
<!-- Lombok 简化开发 -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
</dependencies>
4.2 配置高德相关参数
在 application.yml
中添加:
yaml
gaode:
key: your_amap_api_key # 替换为你自己的高德Key
driving-url: https://restapi.amap.com/v3/direction/driving
4.3 构建配置类
less
@Configuration
@ConfigurationProperties(prefix = "gaode")
@Data
public class GaoDeConfig {
private String key;
private String drivingUrl;
}
五、封装路线规划服务
5.1 创建路线请求与响应模型
less
@Data
@AllArgsConstructor
@NoArgsConstructor
public class RouteRequest {
private String origin; // 起点坐标 - 格式:经度,纬度
private String destination; // 终点坐标 - 格式:经度,纬度
}
java
复制
less
@Data
@NoArgsConstructor
@AllArgsConstructor
public class RouteResult {
private String distance; // 距离(单位:米)
private String duration; // 时间(单位:秒)
private String strategy; // 策略说明
}
5.2 创建 Service 调用高德接口
java
@Service
@RequiredArgsConstructor
public class GaoDeRouteService {
private final GaoDeConfig config;
private final RestTemplate restTemplate = new RestTemplate();
public RouteResult getDrivingRoute(RouteRequest request) {
String url = UriComponentsBuilder.fromHttpUrl(config.getDrivingUrl())
.queryParam("origin", request.getOrigin())
.queryParam("destination", request.getDestination())
.queryParam("key", config.getKey())
.queryParam("strategy", 0) // 推荐策略
.toUriString();
ResponseEntity<String> response = restTemplate.getForEntity(url, String.class);
if (response.getStatusCode() == HttpStatus.OK) {
try {
ObjectMapper mapper = new ObjectMapper();
JsonNode root = mapper.readTree(response.getBody());
JsonNode route = root.path("route");
JsonNode paths = route.path("paths");
if (paths.isArray() && paths.size() > 0) {
JsonNode path = paths.get(0);
return new RouteResult(
path.path("distance").asText(),
path.path("duration").asText(),
path.path("strategy").asText()
);
}
} catch (Exception e) {
throw new RuntimeException("解析高德路线规划响应失败", e);
}
}
throw new RuntimeException("调用高德地图接口失败");
}
}
六、提供 REST 接口供前端调用
less
@RestController
@RequestMapping("/api/route")
@RequiredArgsConstructor
public class RouteController {
private final GaoDeRouteService routeService;
@PostMapping("/driving")
public ResponseEntity<RouteResult> getDrivingRoute(@RequestBody RouteRequest request) {
RouteResult result = routeService.getDrivingRoute(request);
return ResponseEntity.ok(result);
}
}
七、Postman 测试示例
- 请求地址 :
POST http://localhost:8080/api/route/driving
- 请求体:
json
{
"origin": "116.481028,39.989643",
"destination": "116.434446,39.90816"
}
- 响应示例:
json
{
"distance": "9346",
"duration": "1234",
"strategy": "推荐"
}
八、经验与优化建议
8.1 缓存策略
- 高德接口有并发限制(QPS),建议对频繁请求的数据做缓存(例如 Redis 缓存常用路线)。
8.2 错误处理
- 对于高德返回的错误码,要做好异常解析与日志上报,避免接口调用失败而无感知。
8.3 模块解耦
- 建议将地图服务抽象为接口,例如
MapService
,方便未来替换为腾讯地图或百度地图。
8.4 单元测试
- 使用 MockRestServiceServer 编写单元测试,确保服务逻辑的稳定性。
九、总结
路线规划功能虽然看似简单,但涉及到外部服务调用、性能优化、错误处理等多个维度。通过本文的介绍,我们完整实现了:
- 高德地图路线规划接口的调用
- Spring Boot 项目的集成
- 路由结果的业务处理与封装
这类功能在后端系统中虽然是"配角",却是影响用户体验的关键一环。作为一名有多年经验的 Java 开发者,在处理这类接口时,除了代码实现,更要注重稳定性、可扩展性与可维护性。