Java集成百度地图驾车路线规划API实战指南：从接口调用到JSON数据封装

地理信息系统（GIS）的应用日益广泛，在出行导航、物流配送等场景中，高效的路线规划服务是关键。百度地图开放平台提供了强大的驾车路线规划API，结合Java后端开发的强大生态，能够为企业级应用构建稳定可靠的地理信息服务。本文将详细介绍如何使用Java调用百度地图驾车路线规划API，并重点讲解如何将复杂的JSON响应数据封装为结构清晰的Java对象，为后续的数据持久化与分析打下基础。

驾车路线服务简介

百度地图路线规划服务（Direction API）是一套基于REST风格的Web服务，支持驾车、骑行、步行、公交等多种出行方式。其中，驾车路线规划服务功能尤为丰富：

• 多路线备选：支持一次请求返回多条可行路线。
• 途径点设置：最多支持添加18个途经点。
• 智能规避：支持传入车牌号以规避限行路段。
• 未来规划：支持指定未来7天内的出发时间，基于预测路况进行规划。

其基础请求地址格式如下：

https://api.map.baidu.com/direction/v2/driving?origin=纬度,经度&destination=纬度,经度&ak=您的AK

使用Java进行接口调用集成

为了简化HTTP调用过程，我们可以使用如UniHttp（或类似如OkHttp、RestTemplate等）工具来封装请求。

1. 定义接口访问层

首先，定义一个服务接口，声明调用驾车路线规划API所需的各种参数。

import com.burukeyou.uniapi.http.annotation.param.QueryPar;
import com.burukeyou.uniapi.http.annotation.request.GetHttpInterface;
import com.burukeyou.uniapi.http.core.response.HttpResponse;

/**
 * 百度地图驾车路线规划服务V2接口
 */
public interface BaiduDrivingV2Service {

    @GetHttpInterface(path = "/direction/v2/driving")
    HttpResponse<String> getDrivingRoute(
            @QueryPar("ak") String ak,
            @QueryPar("origin") String origin,
            @QueryPar("destination") String destination,
            @QueryPar("coord_type") String coordType,
            @QueryPar("ret_coordtype") String retCoordtype,
            @QueryPar("tactics") int tactics,
            @QueryPar("alternatives") int alternatives,
            @QueryPar("cartype") int cartype,
            @QueryPar("speed") float speed,
            @QueryPar("steps_info") int stepsInfo
    );
}

接口参数涵盖了必填的AK、起终点坐标，以及路线策略（tactics）、是否返回备选路线（alternatives）、车辆类型、速度等可选参数，可根据实际业务需求灵活组合。

2. 本地服务调用测试

以下是一个使用SpringBoot环境，通过JUnit测试接口调用的示例。

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.http.core.response.HttpResponse;

@SpringBootTest
@RunWith(SpringRunner.class)
public class BaiduDrivingV2ServiceTest {

    private static final String BAIDU_CLIENT_AK = "your_ak_here";

    @Autowired
    private BaiduDrivingV2Service drivingService;

    @Test
    public void testDrivingRoute() {
        String origin = "23.115102,113.269043"; // 起点：广州 (纬度,经度)
        String destination = "27.728514,109.186249"; // 终点：铜仁 (纬度,经度)
        String coordType = "wgs84"; // 请求坐标类型
        String retCoordtype = "bd09ll"; // 返回坐标类型
        int tactics = 0; // 默认策略
        int alternatives = 1; // 返回备选路线
        int cartype = 0; // 普通燃油车
        float speed = 27.78F; // 车速 100km/h ≈ 27.78 m/s
        int stepsInfo = 1; // 返回分段详情

        HttpResponse<String> response = drivingService.getDrivingRoute(
                BAIDU_CLIENT_AK, origin, destination, coordType,
                retCoordtype, tactics, alternatives, cartype, speed, stepsInfo
        );

        System.out.println("API响应JSON: " + response.getBodyResult());
    }
}

执行测试后，控制台将输出API返回的原始JSON字符串。格式化后，可以看到一个包含状态、路线方案、距离、耗时、分段导航点（steps）等信息的嵌套JSON结构。这个结构是我们进行Java对象封装的直接依据。

响应JSON数据的Java对象封装

为了在业务中方便地操作数据，我们需要将JSON响应反序列化为Java对象。根据API返回的数据结构，我们可以设计如下一组Java类。

1. 基础公共响应类

所有百度API响应共有的状态字段。

import lombok.Data;
import java.io.Serializable;

@Data
public class BdCommonDTO implements Serializable {
    private Integer status; // 状态码，0为成功
    private String message; // 状态信息
}

2. 驾车路线规划主响应类

继承公共类，并包含具体的规划结果。

import lombok.Data;
import lombok.EqualsAndHashCode;
import java.io.Serializable;

@EqualsAndHashCode(callSuper = true)
@Data
public class BdDrivingDTO extends BdCommonDTO implements Serializable {
    private Integer type;
    private BdDrivingResultDTO result; // 核心结果数据
}

3. 规划结果详情类

包含方案总数、具体路线列表等信息。

import com.google.gson.annotations.SerializedName;
import lombok.Data;
import java.io.Serializable;
import java.util.List;

@Data
public class BdDrivingResultDTO implements Serializable {
    private String restriction; // 限行信息
    private Integer total; // 方案总数
    @SerializedName("routes")
    private List<BdDrivingRouteDTO> routes; // 路线方案列表
    // 其他字段如 session_id, holiday 等省略...
}

4. 单条路线方案类

封装一条路线的详细信息，如起终点、距离、耗时、分段步骤等。

import com.google.gson.annotations.SerializedName;
import lombok.Data;
import java.io.Serializable;
import java.util.List;

@Data
public class BdDrivingRouteDTO implements Serializable {
    private BdLocationDTO origin; // 起点坐标对象
    private BdLocationDTO destination; // 终点坐标对象
    private Float distance; // 总距离，单位：米
    private Integer duration; // 预计耗时，单位：秒
    @SerializedName("steps")
    private List<BdDrivingStepDTO> steps; // 路线分段详情
    // 其他字段如 taxi_fee(打车费), toll(路桥费) 等省略...
}

此外，还需要定义 BdLocationDTO（坐标点）、BdDrivingStepDTO（导航分段）等子类来完整映射JSON结构。

5. 使用Gson进行反序列化

对象定义完成后，可以使用Gson库方便地将JSON字符串转换为Java对象。

import com.google.gson.Gson;

public class JsonParserUtil {
    private static final Gson gson = new Gson();

    public static BdDrivingDTO parseDrivingResponse(String jsonStr) {
        return gson.fromJson(jsonStr, BdDrivingDTO.class);
    }
}

集成过程中的常见问题与解决

1. 坐标顺序问题

问题现象：调用API时返回“参数错误”。
原因分析：百度地图API要求的坐标格式为 “纬度,经度” (lat,lng)，而开发者习惯的“经度,纬度”顺序会导致错误。
解决方案：严格确保传入的 origin 和 destination 参数格式为“纬度,经度”。

2. 坐标类型不一致问题

问题现象：设置返回坐标类型(ret_coordtype)为wgs84时报错。
原因分析：百度地图驾车规划API的返回坐标不支持wgs84格式，仅支持bd09ll或gcj02。
解决方案：查阅官方文档，将 ret_coordtype 参数设置为允许的值，例如 bd09ll。

总结

本文通过实战演示了在Java项目中集成百度地图驾车路线规划服务的完整流程，从使用HTTP客户端调用API，到根据复杂的JSON响应结构设计并封装对应的Java数据模型。掌握这一过程，不仅能够实现路线规划功能，更能深入理解如何处理和封装第三方API的数据，提升后端服务的架构设计能力。正确的参数传递（特别是坐标顺序和类型）是成功调用的关键，仔细阅读官方文档能避免很多不必要的麻烦。