# gaodemap-frontend

**Repository Path**: shangguan-zeming/gaodemap-frontend

## Basic Information

- **Project Name**: gaodemap-frontend
- **Description**: 高德地图demo的前端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-10
- **Last Updated**: 2025-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 高德静态地图项目说明与常见问题排查

## 一、项目简介
本项目基于高德地图静态地图API，支持通过经纬度生成带标注的静态地图图片，支持自定义标注、标签、路径等功能，前端Vue3，后端Spring Boot。

---

## 二、常见问题与解决方法

### 1. API Key相关问题
- **Key无效/未开通服务/被禁用/超限**
  - 现象：所有请求都返回 infocode: 20003 或 10001
  - 解决：必须使用Web服务API类型的Key，并在高德开放平台开通“静态地图”服务。不要用JS API的Key。检查Key是否被禁用、删除、超限、或有IP白名单限制。
- **Key有IP白名单**
  - 现象：本地调试或服务器请求报错
  - 解决：在高德开放平台控制台将本地/服务器公网IP加入白名单，或暂时关闭白名单。

### 2. markers参数导致地图不显示
- **markers参数label为中文，地图不显示，返回 infocode: 20003**
  - 现象：只要markers参数label为中文，API就报错，地图不显示
  - 解决：label只能用英文或数字，不能用中文。自动标注label建议用“A”，手动标注label前端校验只允许英文/数字。
- **markers参数label为空时多了逗号，地图不显示**
  - 现象：markers=mid,0xFF0000,:经纬度 这样会报错
  - 解决：label为空时不要多加逗号，正确格式是 markers=mid,0xFF0000:经纬度
- **颜色格式错误**
  - 现象：颜色用#FF0000，地图不显示
  - 解决：所有颜色参数都要转为0xFF0000格式

### 3. 如何排查问题
- **先用最简单的URL测试Key**
  ```
  https://restapi.amap.com/v3/staticmap?location=116.481485,39.990464&zoom=10&size=400*400&key=你的key
  ```
  - 能显示，说明Key没问题
  - 不能显示，说明Key有问题
- **再加markers参数测试**
  - 用英文label或不带label测试
  - 只要加中文label就报错，说明label不支持中文
- **查看API返回的infocode和info**
  - 10001：Key不正确或过期
  - 20003：参数有误、权限不足、Key未开通服务、label为中文等

### 4. 前后端开发注意事项
- **前端**
  - 自动标注label用英文或数字
  - 手动标注label只允许英文或数字
  - 颜色参数全部转为0x开头
  - markers参数拼接时，label为空不多加逗号
- **后端**
  - buildMarkersParam方法拼接时，label为空不多加逗号
  - label只允许英文或数字
  - 颜色参数不做#转0x的处理，前端已处理

### 5. 常见高德API错误码速查
| infocode | info                  | 说明/排查建议                         |
|----------|-----------------------|--------------------------------------|
| 10000    | OK                    | 请求正常                             |
| 10001    | INVALID_USER_KEY      | key不正确或过期                      |
| 10002    | SERVICE_NOT_AVAILABLE | 没有权限/服务未开通/路径拼写错误      |
| 20003    | UNKNOWN_ERROR         | 其他未知错误（多为参数/权限/Key问题） |
| 10005    | INVALID_USER_IP       | IP白名单出错                         |
| 10009    | USERKEY_PLAT_NOMATCH  | key与平台不符                        |

### 6. 实用排查流程
1. 先用最简单URL测试Key
2. markers参数只用英文label或不带label测试
3. markers参数label用中文测试，若报错则只用英文/数字
4. 检查所有颜色参数格式
5. 检查API返回的infocode和info
6. 检查Key类型、权限、白名单、服务开通情况

### 7. 参考资料
- [高德API错误码官方文档](https://lbs.amap.com/api/webservice/guide/tools/info)
- [高德开放平台Key管理](https://lbs.amap.com/console/key)
- [高德静态地图API官方文档](https://lbs.amap.com/api/webservice/guide/api/staticmap)

---

## 三、代码关键注释示例

### 前端 MapView.vue
```js
// 自动标注功能：在输入经纬度时自动在地图上添加一个标注点
if (mapForm.autoMarker) {
  const centerLocation = `${mapForm.longitude},${mapForm.latitude}`;
  // 检查是否已存在相同位置的标注，避免重复
  const existingMarker = markers.find(m => m.location === centerLocation);
  if (!existingMarker) {
    markers.unshift({
      style: 'mid',
      color: '#FF0000'.replace('#', '0x'), // 高德API要求颜色为0x开头
      label: 'A', // 只能用英文或数字，不能用中文，否则API报错
      location: centerLocation
    });
  }
}

// 生成地图时，所有颜色参数都要转为0x开头，防止高德API报错
color: m.color.replace('#', '0x'),

// 手动添加标注时，建议校验label只能为英文或数字，防止API报错
if (!/^[A-Za-z0-9]*$/.test(marker.label)) {
  marker.label = '';
}
```

### 后端 GaodemapService.java
```java
/**
 * 构建markers参数，label为空时不多加逗号，防止高德API报错
 * 只允许label为英文或数字，不能为中文
 */
private String buildMarkersParam(List<StaticMapRequest.Marker> markers) {
    return markers.stream()
            .map(marker -> {
                StringBuilder markerStr = new StringBuilder();
                markerStr.append(marker.getStyle()).append(",");
                markerStr.append(marker.getColor());
                // 只有label不为空且为英文/数字时才拼接
                if (marker.getLabel() != null && !marker.getLabel().isEmpty() && marker.getLabel().matches("^[A-Za-z0-9]*$")) {
                    markerStr.append(",").append(marker.getLabel());
                }
                markerStr.append(":").append(marker.getLocation());
                return markerStr.toString();
            })
            .collect(Collectors.joining("|"));
}
```

---

如需进一步自动化校验、UI优化、功能扩展，欢迎随时提问！