package com.estate.expert.admin.component.map;
|
|
import lombok.extern.slf4j.Slf4j;
|
import org.springframework.beans.factory.annotation.Value;
|
import org.springframework.stereotype.Component;
|
import org.springframework.web.client.RestTemplate;
|
|
/**
|
* 地理位置翻译组件
|
*
|
* <p>该组件提供地址到地理坐标的转换功能，基于高德地图API实现。
|
* 主要用于将中文地址转换为精确的经纬度坐标，支持各种基于位置的服务。</p>
|
*
|
* <p>主要功能：</p>
|
* <ul>
|
* <li>地址解析：将文本地址转换为地理坐标</li>
|
* <li>坐标获取：提供精确的经纬度信息</li>
|
* <li>位置服务：支持地图定位和导航功能</li>
|
* </ul>
|
*
|
* <p>技术特点：</p>
|
* <ul>
|
* <li>基于高德地图Web服务API</li>
|
* <li>支持中文地址解析</li>
|
* <li>提供高精度的地理坐标</li>
|
* <li>包含完整的错误处理机制</li>
|
* </ul>
|
*
|
* <p>使用场景：</p>
|
* <ul>
|
* <li>工程项目位置定位</li>
|
* <li>设备安装位置记录</li>
|
* <li>安全检查地点标记</li>
|
* <li>地图可视化展示</li>
|
* </ul>
|
*
|
* @author daisy
|
* @since 2023/10/29
|
*/
|
@Slf4j
|
@Component
|
public class GeoTranslateComponent {
|
|
/**
|
* 高德地图地理编码API地址
|
*
|
* <p>高德地图提供的地理编码服务接口，用于将地址转换为地理坐标。</p>
|
*
|
* <p>API说明：</p>
|
* <ul>
|
* <li>服务类型：RESTful Web API</li>
|
* <li>请求方式：HTTP GET</li>
|
* <li>响应格式：JSON</li>
|
* <li>坐标系统：WGS84</li>
|
* </ul>
|
*
|
* <p>请求参数：</p>
|
* <ul>
|
* <li>address：待解析的地址（必填）</li>
|
* <li>key：API密钥（必填）</li>
|
* </ul>
|
*
|
* <p>API文档：https://lbs.amap.com/api/webservice/guide/api/georegeo</p>
|
*/
|
private static final String MAP_API_URL = "https://restapi.amap.com/v3/geocode/geo";
|
|
/**
|
* 高德地图API密钥
|
*
|
* <p>用于访问高德地图服务的认证密钥，从配置文件中读取。</p>
|
*
|
* <p>配置说明：</p>
|
* <ul>
|
* <li>配置文件：application.yml</li>
|
* <li>配置项：map.api.key</li>
|
* <li>默认值：5ad97434d47b7cc74b4145d5509d28d2</li>
|
* </ul>
|
*
|
* <p>安全注意事项：</p>
|
* <ul>
|
* <li>API密钥应妥善保管，避免泄露</li>
|
* <li>建议在生产环境中使用环境变量或加密配置</li>
|
* <li>定期检查和更新API密钥</li>
|
* </ul>
|
*/
|
@Value("${map.api.key}")
|
private final String API_KEY = "5ad97434d47b7cc74b4145d5509d28d2";
|
|
/**
|
* HTTP客户端模板
|
*
|
* <p>用于发送HTTP请求到高德地图API服务。
|
* Spring RestTemplate提供了便捷的HTTP客户端功能。</p>
|
*/
|
RestTemplate restTemplate = new RestTemplate();
|
|
/**
|
* 地址转坐标方法
|
*
|
* <p>该方法将文本地址转换为地理坐标（经纬度），支持中文地址解析。
|
* 通过调用高德地图地理编码API实现地址到坐标的转换。</p>
|
*
|
* <p>处理流程：</p>
|
* <ol>
|
* <li>构建API请求URL，包含地址和API密钥参数</li>
|
* <li>发送HTTP GET请求到高德地图API</li>
|
* <li>解析JSON响应数据</li>
|
* <li>提取第一个地理编码结果的坐标信息</li>
|
* <li>将坐标字符串解析为Double数组</li>
|
* <li>处理异常情况并返回null</li>
|
* </ol>
|
*
|
* <p>坐标格式：</p>
|
* <ul>
|
* <li>返回数组：[经度, 纬度]</li>
|
* <li>经度范围：-180.0 到 180.0</li>
|
* <li>纬度范围：-90.0 到 90.0</li>
|
* <li>精度：通常精确到小数点后6位</li>
|
* </ul>
|
*
|
* <p>异常处理：</p>
|
* <ul>
|
* <li>网络异常：记录错误日志，返回null</li>
|
* <li>API错误：记录错误信息，返回null</li>
|
* <li>解析异常：记录解析错误，返回null</li>
|
* <li>空结果：当API返回空结果时，返回null</li>
|
* </ul>
|
*
|
* @param address 待解析的地址文本，支持中文地址
|
* @return Double[] 坐标数组，格式为[经度, 纬度]，解析失败时返回null
|
*
|
* @see GeoResponse API响应格式说明
|
*
|
* <p>使用示例：</p>
|
* <pre>
|
* GeoTranslateComponent component = new GeoTranslateComponent();
|
* Double[] coords = component.translate("北京市朝阳区阜通东大街6号");
|
* if (coords != null) {
|
* double longitude = coords[0]; // 经度
|
* double latitude = coords[1]; // 纬度
|
* }
|
* </pre>
|
*/
|
public Double[] translate(String address) {
|
try {
|
// 构建API请求URL
|
String url = MAP_API_URL + "?address=" + address + "&key=" + API_KEY;
|
log.debug("发送地理编码请求: {}", url);
|
|
// 发送HTTP GET请求并获取响应
|
var response = restTemplate.getForObject(url, GeoResponse.class);
|
|
// 检查响应数据是否有效
|
if (response != null && response.getGeocodes() != null && !response.getGeocodes().isEmpty()) {
|
// 获取第一个地理编码结果的坐标字符串
|
var location = response.getGeocodes().get(0).getLocation();
|
log.debug("获取到坐标: {}", location);
|
|
// 解析坐标字符串为Double数组
|
var locationArray = location.split(",");
|
if (locationArray.length >= 2) {
|
double longitude = Double.parseDouble(locationArray[0]);
|
double latitude = Double.parseDouble(locationArray[1]);
|
log.info("地址 '{}' 解析成功: 经度={}, 纬度={}", address, longitude, latitude);
|
return new Double[]{longitude, latitude};
|
} else {
|
log.warn("坐标格式无效: {}", location);
|
}
|
} else {
|
log.warn("地址 '{}' 未找到匹配的地理编码结果", address);
|
}
|
|
} catch (Exception e) {
|
// 记录详细的错误信息
|
log.error("地理编码API请求失败, 地址: {}, 错误: {}", address, e.getMessage(), e);
|
}
|
|
// 异常情况下返回null
|
return null;
|
}
|
|
/**
|
* 测试方法 - 地址转坐标示例
|
*
|
* <p>该方法演示了如何使用地理编码组件进行地址到坐标的转换。
|
* 适用于功能测试和开发调试。</p>
|
*
|
* <p>测试地址：</p>
|
* <ul>
|
* <li>示例地址：北京市朝阳区阜通东大街6号</li>
|
* <li>预期结果：返回该地址的精确经纬度坐标</li>
|
* </ul>
|
*
|
* <p>使用说明：</p>
|
* <ul>
|
* <li>该方法主要用于功能测试和演示</li>
|
* <li>实际使用时需要根据具体需求调整地址参数</li>
|
* <li>建议在生产环境中移除或注释掉此方法</li>
|
* </ul>
|
*/
|
public static void main(String[] args) {
|
// 创建地理编码组件实例
|
GeoTranslateComponent component = new GeoTranslateComponent();
|
|
// 测试地址转坐标功能
|
var result = component.translate("北京市朝阳区阜通东大街6号");
|
|
// 输出结果
|
if (result != null) {
|
System.out.println("地址解析成功:");
|
System.out.println("经度: " + result[0]);
|
System.out.println("纬度: " + result[1]);
|
} else {
|
System.out.println("地址解析失败");
|
}
|
}
|
|
}
|
