当前位置：首页 > news >正文

基于 Java 和高德开放平台的 WebAPI 集成实践——以“搜索 POI 2.0”为例

news 2026/4/14 4:40:06

在位置服务类应用里，“找点”（Point of Interest，POI）几乎是最常见能力：输入“咖啡”“地铁站”“医院”，返回可用地点列表。
高德开放平台的 WebAPI 在这类场景中非常成熟，而POI 2.0相比早期版本，在字段丰富度、检索能力和结果可用性上更适合企业级业务集成。

本文将从 Java 工程落地视角，完整讲解：如何从 0 到 1 接入高德 POI 2.0 搜索，包含配置、安全、代码实现、异常治理、性能优化与上线建议。

一、业务目标与技术选型

我们先定义一个最小可用目标：

输入：关键词（如“星巴克”）、城市（如“北京”）、分页参数
输出：标准化 POI 列表（名称、地址、坐标、距离、类型等）
要求：可扩展、可观测、可限流、可容错

技术栈建议：

Java 17+
Spring Boot 3.x
WebClient（或 RestTemplate）
Caffeine（本地缓存，可选）
Micrometer + Prometheus（监控，可选）

二、开通高德开放平台能力

注册高德开放平台账号
创建应用，选择Web 服务 API
获取key（必要）
开启安全校验（可选，生产建议开启sig签名）
阅读 POI 2.0 文档，确认接口地址与参数规则（例如文本搜索接口）

常见调用方式是 GET 请求，核心参数一般包含：key、keywords、region/city、page_num、page_size等。

三、Spring Boot 项目配置

1）`application.yml`

yaml

amap: webapi: key: your_amap_key secret: your_amap_secret # 可选，启用签名时使用 base-url: https://restapi.amap.com timeout-ms: 3000

2）配置类

java

@ConfigurationProperties(prefix = "amap.webapi") @Data public class AmapProperties { private String key; private String secret; private String baseUrl; private int timeoutMs = 3000; }

java

@Configuration @EnableConfigurationProperties(AmapProperties.class) public class HttpClientConfig { @Bean public WebClient amapWebClient(AmapProperties p) { HttpClient httpClient = HttpClient.create() .responseTimeout(Duration.ofMillis(p.getTimeoutMs())); return WebClient.builder() .baseUrl(p.getBaseUrl()) .clientConnector(new ReactorClientHttpConnector(httpClient)) .build(); } }

四、定义请求与响应模型（先做“防腐层”）

不要把高德原始 JSON 直接暴露给业务层，建议建一层 DTO 转换。

java

@Data public class PoiSearchRequest { private String keywords; private String city; // 或 region private Integer pageNum = 1; private Integer pageSize = 10; }

java

@Data public class PoiItem { private String id; private String name; private String address; private String location; // "lng,lat" private String type; private String distance; }

java

@Data public class PoiSearchResult { private Long total; private List<PoiItem> pois; }

五、核心调用实现（POI 2.0）

下面以“文本搜索”思路示例（具体路径以官方文档为准）：

java

@Service @RequiredArgsConstructor public class AmapPoiService { private final WebClient amapWebClient; private final AmapProperties props; private final ObjectMapper objectMapper; public PoiSearchResult search(PoiSearchRequest req) { Map<String, String> params = new TreeMap<>(); params.put("key", props.getKey()); params.put("keywords", req.getKeywords()); params.put("region", req.getCity()); params.put("page_num", String.valueOf(req.getPageNum())); params.put("page_size", String.valueOf(req.getPageSize())); params.put("show_fields", "business,indoor,navi,photos"); // 如开启签名，按官方规则计算 sig if (StringUtils.hasText(props.getSecret())) { params.put("sig", buildSig(params, props.getSecret())); } String body = amapWebClient.get() .uri(uriBuilder -> { UriBuilder b = uriBuilder.path("/v5/place/text"); params.forEach(b::queryParam); return b.build(); }) .retrieve() .onStatus(HttpStatusCode::isError, resp -> Mono.error(new RuntimeException("Amap http error: " + resp.statusCode()))) .bodyToMono(String.class) .block(); return parseResult(body); } private PoiSearchResult parseResult(String body) { try { JsonNode root = objectMapper.readTree(body); String status = root.path("status").asText(); if (!"1".equals(status)) { String info = root.path("info").asText("unknown"); String infocode = root.path("infocode").asText("unknown"); throw new RuntimeException("Amap biz error, info=" + info + ", infocode=" + infocode); } PoiSearchResult result = new PoiSearchResult(); result.setTotal(root.path("count").asLong(0L)); List<PoiItem> list = new ArrayList<>(); for (JsonNode n : root.path("pois")) { PoiItem item = new PoiItem(); item.setId(n.path("id").asText()); item.setName(n.path("name").asText()); item.setAddress(n.path("address").asText()); item.setLocation(n.path("location").asText()); item.setType(n.path("type").asText()); item.setDistance(n.path("distance").asText()); list.add(item); } result.setPois(list); return result; } catch (Exception e) { throw new RuntimeException("Parse amap response failed", e); } } private String buildSig(Map<String, String> params, String secret) { // 示例：按官方签名规则拼接后 MD5（请严格对照官方文档实现） StringBuilder sb = new StringBuilder(); params.forEach((k, v) -> sb.append(k).append("=").append(v).append("&")); sb.setLength(sb.length() - 1); sb.append(secret); return DigestUtils.md5DigestAsHex(sb.toString().getBytes(StandardCharsets.UTF_8)); } }

六、Controller 暴露内部统一接口

java

@RestController @RequestMapping("/api/poi") @RequiredArgsConstructor public class PoiController { private final AmapPoiService poiService; @GetMapping("/search") public PoiSearchResult search(@RequestParam String keywords, @RequestParam(required = false) String city, @RequestParam(defaultValue = "1") Integer pageNum, @RequestParam(defaultValue = "10") Integer pageSize) { PoiSearchRequest req = new PoiSearchRequest(); req.setKeywords(keywords); req.setCity(city); req.setPageNum(pageNum); req.setPageSize(pageSize); return poiService.search(req); } }

调用示例：

bash

curl "http://localhost:8080/api/poi/search?keywords=咖啡&city=北京&pageNum=1&pageSize=10"