您现在的位置是：网站首页> 开发积累
常用开放平台开发接口及库使用总结
- 开发积累
- 2026-04-11
- 11人已阅读
常用开放平台开发接口及库使用总结
全程基于高德定位 SDK V9.0+（最新稳定版），适配 Android 6.0 + 动态权限、Android 10 + 后台定位、Android 12 + 精确 / 模糊定位，步骤清晰可落地，包含配置、编码、调试全流程。
一、前期准备：获取高德 Key（核心）
1 注册 / 登录，高德地图开放平台，进入控制台→应用管理→创建新应用，填写应用名称、类型（选择「Android 端」）。
2 为应用添加 Key：选择「定位 SDK」，填写Android 包名（与项目build.gradle中applicationId完全一致）、SHA1 指纹（debug/release 环境需分别配置，测试阶段先配 debug）。
3 保存后得到唯一的高德 Key（如d48xxxxxxxxxxxxxxxxxxxxxx7e），后续配置全程用到。
快速获取 SHA1 指纹（Windows/macOS 通用）
Debug 环境：使用 Android Studio 默认 debug 签名，终端执行命令：
bash
运行
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
（macOS 直接执行，Windows 需先进入 JDK 的 bin 目录，~替换为C:\Users\你的用户名）
Release 环境：替换为自己的正式签名文件路径、别名、密码即可。
二、集成 SDK：两种方式（推荐远程依赖，无需手动导包）
方式 1：远程依赖（build.gradle，推荐）
1. 项目根目录build.gradle（Project 级）
添加高德 maven 仓库（若已有可忽略），在allprojects→repositories中配置：
gradle
allprojects {
repositories {
google()
jcenter()
// 高德maven仓库
maven { url 'https://maven.aliyun.com/repository/public/' }
maven { url 'https://developer.amap.com/maven/' }
}
}
2. 模块目录build.gradle（Module 级，一般是 app）
添加依赖：在dependencies中加入定位 SDK 核心依赖（无需其他额外依赖）：
gradle
dependencies {
// 高德定位SDK V9.0+（最新稳定版，兼容Android 14）
implementation 'com.amap.api:location:9.0.0'
}
配置编译参数：在android→defaultConfig中添加 NDK 架构（按需，至少保留armeabi-v7a/arm64-v8a）：
gradle
android {
compileSdk 34 // 适配自己的项目版本，最低支持21
defaultConfig {
applicationId "com.xxx.xxx" // 与高德Key的包名完全一致
minSdk 21
targetSdk 34
// 高德定位SDK需要的NDK架构
ndk {
abiFilters "armeabi-v7a", "arm64-v8a"
}
}
// 若使用Android Gradle Plugin 7.0+，需开启JDK8兼容
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
3. 同步 Gradle
点击 Android Studio 右上角「Sync Now」，等待 SDK 下载集成完成（若失败，检查网络或仓库地址）。
方式 2：手动集成（不推荐，适合无网络环境）
1 从高德地图SDK下载页下载最新 SDK，解压得到amap_location_v9.x.x.jar和jniLibs文件夹。
2 将jar包复制到app/libs目录，右键→「Add as Library」添加依赖。
3 将jniLibs文件夹（包含各架构 so 文件）复制到app/src/main目录，与java/res同级。
三、配置 AndroidManifest.xml：权限 + Key + 服务
在app/src/main/AndroidManifest.xml中添加权限、高德 Key、定位服务，缺一不可，按位置粘贴即可。
1. 声明权限（分基础定位 / 后台定位，按需配置）
粘贴在<manifest>标签内、<application>标签外，Android 6.0 + 需动态申请，这里仅为清单声明：
xml
<!-- 基础定位权限（必须）：精确定位 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- 粗略定位（备用，可选） -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!-- 网络权限（必须：基站/Wi-Fi定位需要） -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- 网络状态（可选：判断网络是否可用，优化定位） -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- Wi-Fi状态（可选：Wi-Fi定位需要） -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- 读取Wi-Fi MAC（可选：部分设备定位需要） -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<!-- 后台定位权限（Android 10+需要，若应用在后台也需定位则加） -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<!-- 悬浮窗权限（Android 13+后台定位需要，可选） -->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<!-- 声明定位硬件特性（可选，告诉应用市场该应用需要定位功能） -->
<uses-feature
android:name="android.hardware.location"
android:required="true" />
<uses-feature
android:name="android.hardware.location.gps"
android:required="false" />
2. 配置高德 Key（必须）
粘贴在<application>标签内，替换为自己的高德 Key：
xml
<meta-data
android:name="com.amap.api.v2.apikey"
android:value="你的高德Key" /> <!-- 核心，替换成第一步获取的Key -->
3. 声明定位服务（必须，高德 SDK 内部使用）
粘贴在<application>标签内，与上述 meta-data 同级：
xml
<!-- 高德定位服务，无需修改 -->
<service
android:name="com.amap.api.location.APSService"
android:exported="false" />
四、核心编码：Java 实现高德定位（Activity/Fragment 通用）
以Activity为例，实现单次定位（最常用，如获取当前位置）和连续定位（如轨迹追踪），包含动态权限申请（Android 6.0 + 强制要求）、定位初始化、结果回调、资源释放（防止内存泄漏），代码可直接复制修改。
核心步骤：
1 动态申请定位权限（基础 / 后台）；
2 初始化高德定位客户端AMapLocationClient；
3 配置定位参数AMapLocationClientOption；
4 设置定位回调AMapLocationListener，处理定位结果；
5 启动定位；
6 在生命周期（onDestroy）释放定位资源。
完整 Java 代码（Activity）
java
运行
package com.xxx.xxx; // 替换为自己的包名
import android.Manifest;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.widget.Toast;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;
import com.amap.api.location.AMapLocation;
import com.amap.api.location.AMapLocationClient;
import com.amap.api.location.AMapLocationClientOption;
import com.amap.api.location.AMapLocationListener;
public class LocationActivity extends AppCompatActivity {
// 高德定位客户端（核心）
public AMapLocationClient mLocationClient = null;
// 高德定位参数配置
public AMapLocationClientOption mLocationOption = null;
// 定位权限请求码（自定义，建议100以上）
private static final int LOCATION_PERMISSION_REQUEST_CODE = 101;
// 后台定位权限请求码（Android 10+）
private static final int BACKGROUND_LOCATION_REQUEST_CODE = 102;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_location); // 替换为自己的布局
// 第一步：检查并申请定位权限
checkLocationPermission();
}
/**
* 检查定位权限：Android 6.0+动态申请
*/
private void checkLocationPermission() {
// 检查精确定位权限是否已授予
if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION)
!= PackageManager.PERMISSION_GRANTED) {
// 未授予，申请基础定位权限（精确定位）
ActivityCompat.requestPermissions(this,
new String[]{Manifest.permission.ACCESS_FINE_LOCATION},
LOCATION_PERMISSION_REQUEST_CODE);
} else {
// 已授予基础权限，若需要后台定位，检查后台权限（Android 10+）
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.Q) {
if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_BACKGROUND_LOCATION)
!= PackageManager.PERMISSION_GRANTED) {
ActivityCompat.requestPermissions(this,
new String[]{Manifest.permission.ACCESS_BACKGROUND_LOCATION},
BACKGROUND_LOCATION_REQUEST_CODE);
} else {
// 所有权限已授予，初始化定位
initLocation();
}
} else {
// 低于Android 10，直接初始化定位
initLocation();
}
}
}
/**
* 第二步：初始化高德定位客户端+配置参数
*/
private void initLocation() {
try {
// 初始化定位客户端
mLocationClient = new AMapLocationClient(getApplicationContext());
// 设置定位回调监听器
mLocationClient.setLocationListener(mLocationListener);
// 初始化定位参数
mLocationOption = new AMapLocationClientOption();
// 配置定位参数（重点，按需修改）
// 1. 定位模式：高精度（GPS+网络+Wi-Fi）/仅网络/仅GPS，推荐高精度
mLocationOption.setLocationMode(AMapLocationClientOption.AMapLocationMode.Hight_Accuracy);
// 2. 定位类型：单次定位（推荐）/连续定位，根据业务选择
mLocationOption.setOnceLocation(true); // 单次定位（获取当前位置后停止）
// 若要连续定位，注释上面一行，打开下面两行：
// mLocationOption.setOnceLocation(false);
// mLocationOption.setInterval(2000); // 连续定位间隔，单位ms，最小1000ms
// 3. 是否返回地址信息（省/市/区/街道，推荐true）
mLocationOption.setNeedAddress(true);
// 4. 是否开启缓存（推荐true，优化首次定位速度）
mLocationOption.setLocationCacheEnable(true);
// 5. 定位超时时间（单位ms，默认30000，建议设为5000-10000）
mLocationOption.setHttpTimeOut(8000);
// 将配置参数设置给定位客户端
mLocationClient.setLocationOption(mLocationOption);
// 第三步：启动定位
mLocationClient.startLocation();
} catch (Exception e) {
e.printStackTrace();
Toast.makeText(this, "定位初始化失败：" + e.getMessage(), Toast.LENGTH_SHORT).show();
}
}
/**
* 第三步：定位回调监听器（处理定位结果/错误）
*/
public AMapLocationListener mLocationListener = new AMapLocationListener() {
@Override
public void onLocationChanged(AMapLocation aMapLocation) {
if (aMapLocation != null) {
// 定位成功：aMapLocation.getErrorCode() == 0
if (aMapLocation.getErrorCode() == 0) {
// 获取定位结果（核心字段，按需取值）
double latitude = aMapLocation.getLatitude(); // 纬度（GCJ02坐标系，高德专属）
double longitude = aMapLocation.getLongitude(); // 经度
float accuracy = aMapLocation.getAccuracy(); // 定位精度（米）
String address = aMapLocation.getAddress(); // 详细地址（如：北京市朝阳区XX路XX号）
String province = aMapLocation.getProvince(); // 省
String city = aMapLocation.getCity(); // 市
String district = aMapLocation.getDistrict(); // 区/县
String street = aMapLocation.getStreet(); // 街道
long time = aMapLocation.getTime(); // 定位时间（毫秒）
String locationType = aMapLocation.getLocationType(); // 定位类型（如GPS/基站/Wi-Fi）
// 打印结果（测试用，实际业务按需处理）
Toast.makeText(LocationActivity.this,
"定位成功：\n经纬度：" + longitude + "," + latitude +
"\n地址：" + address, Toast.LENGTH_LONG).show();
// 单次定位：成功后停止定位（可选，SDK会自动停止）
if (mLocationClient != null) {
mLocationClient.stopLocation();
}
} else {
// 定位失败：获取错误信息
String errorInfo = aMapLocation.getErrorInfo(); // 错误描述
int errorCode = aMapLocation.getErrorCode(); // 错误码
Toast.makeText(LocationActivity.this,
"定位失败：错误码" + errorCode + "，原因：" + errorInfo,
Toast.LENGTH_SHORT).show();
// 高德错误码查询：https://lbs.amap.com/api/android-location-sdk/guide/util/errorcode
}
} else {
Toast.makeText(LocationActivity.this, "定位结果为空", Toast.LENGTH_SHORT).show();
}
}
};
/**
* 权限申请结果回调
*/
@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults);
if (requestCode == LOCATION_PERMISSION_REQUEST_CODE) {
// 基础定位权限申请结果
if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
// 授予，继续检查后台定位权限（Android 10+）
checkLocationPermission();
} else {
// 拒绝，提示用户开启权限
Toast.makeText(this, "请开启定位权限，否则无法使用定位功能", Toast.LENGTH_SHORT).show();
}
} else if (requestCode == BACKGROUND_LOCATION_REQUEST_CODE) {
// 后台定位权限申请结果
if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
initLocation();
} else {
// 拒绝，仅能前台定位，后台定位失效
Toast.makeText(this, "后台定位权限未开启，应用后台将无法定位", Toast.LENGTH_SHORT).show();
initLocation();
}
}
}
/**
* 第四步：释放定位资源（必须，防止内存泄漏）
* 在Activity/Fragment销毁时调用
*/
@Override
protected void onDestroy() {
super.onDestroy();
if (mLocationClient != null) {
mLocationClient.onDestroy(); // 销毁定位客户端
mLocationClient = null;
mLocationOption = null;
}
}
}
五、关键配置说明（按需修改）
1. 定位模式选择
java
运行
// 高精度模式（推荐）：GPS+基站+Wi-Fi，定位最快、精度最高
mLocationOption.setLocationMode(AMapLocationClientOption.AMapLocationMode.Hight_Accuracy);
// 仅网络模式：无GPS时使用，精度约100-1000米，室内可用
// mLocationOption.setLocationMode(AMapLocationClientOption.AMapLocationMode.Battery_Saving);
// 仅GPS模式：精度最高（1-10米），但冷启动慢、室内无信号，适合户外
// mLocationOption.setLocationMode(AMapLocationClientOption.AMapLocationMode.Device_Sensors);
2. 单次 / 连续定位
单次定位：适合「获取当前位置」（如外卖、打车、签到），调用setOnceLocation(true)，定位成功后 SDK 自动停止，也可手动调用stopLocation()。
连续定位：适合「轨迹追踪」（如运动、导航），调用setOnceLocation(false)+setInterval(2000)（间隔≥1000ms），后台定位需开启ACCESS_BACKGROUND_LOCATION权限。
3. 坐标系说明
高德定位 SDK 返回的是GCJ02（火星坐标系），与高德地图 / 导航 SDK 完全兼容，无需转换；若需转换为 WGS84（国际坐标系），需手动调用高德的坐标转换接口（商用需申请权限）。
六、常见问题与调试技巧
1. 定位失败：错误码排查（核心）
高德定位失败会返回错误码，可通过aMapLocation.getErrorCode()获取，对照高德错误码文档
排查，高频错误码：
1001：Key 错误 / 无效→检查 Key 是否正确、包名 / SHA1 是否与高德控制台一致；
1002：网络错误→检查网络是否可用、是否开启INTERNET权限；
1008：权限拒绝→检查动态权限是否申请成功、系统设置中是否开启 App 定位权限；
1012：GPS 未开启→提示用户在系统设置中开启 GPS；
1013：定位超时→延长HttpTimeOut、检查网络 / GPS 信号。
2. 调试注意事项
必须使用真机：模拟器无法定位（高德提供模拟器定位工具，不推荐）；
开启系统定位：手机设置→「位置信息」→开启，选择「高精度模式」；
关闭省电模式：部分国产手机（小米 / 华为 / OPPO）的省电模式会限制定位，测试时关闭；
SHA1 / 包名一致：这是最常见的问题，确保build.gradle的applicationId、高德控制台的包名 / SHA1（debug/release）完全一致，大小写敏感。
3. 国产 ROM 适配（小米 / 华为 / OPPO/vivo）
部分国产手机会限制 App 的定位 / 后台权限，需在手机设置中手动开启：
1 开启「后台活动」/「允许后台运行」；
2 关闭「应用速冻」/「省电优化」；
3 加入「后台白名单」（如小米的「自启动管理」、华为的「应用启动管理」）。
七、进阶用法（可选）
1 后台连续定位：除了申请ACCESS_BACKGROUND_LOCATION权限，还可结合Service实现，将定位客户端初始化在 Service 中，保证应用后台时仍能定位；
2 定位缓存：开启setLocationCacheEnable(true)，SDK 会缓存最近一次定位结果，无网络时可快速获取；
3 地址解析：若仅需经纬度转地址，可使用高德地理编码 / 逆地理编码 SDK，与定位 SDK 配合使用；
4 多进程适配：若 App 使用多进程，需在AMapLocationClient初始化时指定进程，或在 Manifest 中为定位服务配置android:process。
八、官方资源
快速验证
按上述步骤配置后，运行真机，若弹出权限申请弹窗，允许后能看到「定位成功」的 Toast，显示经纬度和详细地址，即接入成功。
如果需要Service 版后台连续定位代码、经纬度转 WGS84 坐标系代码，或排查具体定位失败问题（如错误码 1001/1008），可以告诉我，我会补充对应的代码和解决方案。
上一篇：开源库收集