expo-gaode-map-web-api 1.1.4-next.1 → 1.1.4-next.3

package/README.md

@@ -55,19 +55,36 @@ npm install expo-gaode-map-web-api
 import { ExpoGaodeMapModule } from 'expo-gaode-map-navigation';
 
 ExpoGaodeMapModule.initSDK({
-  androidKey: 'your-android-key',
-  iosKey: 'your-ios-key',
   webKey: 'your-web-api-key', // 关键：供 Web API 包读取
 });
 ```
 
-### 3. 无参构造并使用
+### 3. 创建实例并使用
+
+你可以通过以下两种方式创建 API 实例：
+
+#### 方式 A：无参构造（推荐）
+先在基础模块初始化时配置 `webKey`，随后直接无参构造。这种方式便于统一管理 Key。
+
 ```ts
 import { GaodeWebAPI } from 'expo-gaode-map-web-api';
 
-// 无参：从基础模块运行时解析 webKey
+// 无参：从基础模块运行时自动解析 webKey
 const api = new GaodeWebAPI();
+```
+
+#### 方式 B：显式传入 Key
+如果你不想依赖基础模块的初始化，或者需要使用不同的 Key，可以在构造函数中显式传入。
+
+```ts
+import { GaodeWebAPI } from 'expo-gaode-map-web-api';
+
+// 显式传入：直接使用提供的 Web 服务 Key
+const api = new GaodeWebAPI({ key: 'your-web-api-key' });
+```
 
+### 4. 调用服务接口
+```ts
 // 逆地理编码：坐标 → 地址
 const result = await api.geocode.regeocode('116.481028,39.989643');
 console.log(result.regeocode.formatted_address);
@@ -660,6 +677,15 @@ try {
 - 导航一体化模块（推荐渲染地图并下发 key）：`expo-gaode-map-navigation`
 - 核心地图模块：`expo-gaode-map`
 
+## 📚 文档与资源
+- [在线文档](https://tomwq.github.io/expo-gaode-map/api/web-api.html)
+- [GitHub 仓库](https://github.com/TomWq/expo-gaode-map/packages/web-api)
+- [示例项目(地图)](https://github.com/TomWq/expo-gaode-map-example)
+- [高德地图开放平台](https://lbs.amap.com/)
+- [Expo Modules API](https://docs.expo.dev/modules/overview/)
+
+
 ## License
 
-MIT
+MIT License
+

package/build/index.js

@@ -150,15 +150,16 @@ class GaodeWebAPI {
      * ```
      */
     constructor(config = {}) {
-        const webKey = resolveWebKey();
+        // 优先使用传入的 key，其次尝试从 SDK 配置中解析
+        const webKey = config.key || resolveWebKey();
         if (!webKey) {
-            throw new Error('[expo-gaode-map-web-api] 必须先通过 ExpoGaodeMapModule.initSDK({ webKey }) 初始化并提供 Web API Key。\n' +
-                '请在应用启动时调用：\n' +
+            throw new Error('[expo-gaode-map-web-api] 缺少 Web API Key。您可以通过以下两种方式之一提供：\n' +
+                '1. 在构造函数中显式传入：new GaodeWebAPI({ key: "your-web-api-key" });\n' +
+                '2. 或者先通过 ExpoGaodeMapModule.initSDK({ webKey }) 初始化并提供 Web API Key：\n' +
                 "  import { ExpoGaodeMapModule } from 'expo-gaode-map';\n" +
-                '  ExpoGaodeMapModule.initSDK({ webKey: \"your-web-api-key\", iosKey, androidKey });\n' +
-                '随后再创建 GaodeWebAPI 实例使用 Web API 能力。');
+                '  ExpoGaodeMapModule.initSDK({ webKey: \"your-web-api-key\", iosKey, androidKey });');
         }
-        // 强制使用核心模块中的 webKey，避免直接在此处绕过初始化约束
+        // 使用解析出的 key 或传入的 key
         const effectiveConfig = { ...config, key: webKey };
         this.client = new client_1.GaodeWebAPIClient(effectiveConfig);
         this.geocode = new GeocodeService_1.GeocodeService(this.client);

package/build/services/GeocodeService.d.ts

@@ -61,7 +61,9 @@ export declare class GeocodeService {
      * const result = await geocode.geocode('阜通东大街6号', '北京');
      * ```
      */
-    geocode(address: string, city?: string): Promise<GeocodeResponse>;
+    geocode(address: string, city?: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<GeocodeResponse>;
     /**
      * 批量逆地理编码
      *
@@ -71,6 +73,7 @@ export declare class GeocodeService {
      *
      * @example
      * ```typescript
+     * // 方式1：使用字符串数组
      * const result = await geocode.batchRegeocode([
      *   '116.481028,39.989643',
      *   '116.434446,39.90816'
@@ -93,5 +96,7 @@ export declare class GeocodeService {
      * ], '北京');
      * ```
      */
-    batchGeocode(addresses: string[], city?: string): Promise<GeocodeResponse>;
+    batchGeocode(addresses: string[], city?: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<GeocodeResponse>;
 }

package/build/services/GeocodeService.js

@@ -4,6 +4,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GeocodeService = void 0;
+const validators_1 = require("../utils/validators");
 /**
  * 地理编码服务
  */
@@ -50,12 +51,15 @@ class GeocodeService {
             locationStr = `${location.longitude},${location.latitude}`;
         }
         // 构建请求参数
+        const { signal, ...rest } = options || {};
         const params = {
             location: locationStr,
-            ...options,
+            ...rest,
         };
+        // 校验坐标
+        (0, validators_1.validateCoordinate)(locationStr);
         // 发起请求
-        return this.client.request('/v3/geocode/regeo', params);
+        return this.client.request('/v3/geocode/regeo', { params, signal });
     }
     /**
      * 地理编码
@@ -76,12 +80,12 @@ class GeocodeService {
      * const result = await geocode.geocode('阜通东大街6号', '北京');
      * ```
      */
-    async geocode(address, city) {
+    async geocode(address, city, options) {
         const params = {
             address,
             city,
         };
-        return this.client.request('/v3/geocode/geo', params);
+        return this.client.request('/v3/geocode/geo', { params, signal: options?.signal });
     }
     /**
      * 批量逆地理编码
@@ -92,6 +96,7 @@ class GeocodeService {
      *
      * @example
      * ```typescript
+     * // 方式1：使用字符串数组
      * const result = await geocode.batchRegeocode([
      *   '116.481028,39.989643',
      *   '116.434446,39.90816'
@@ -99,12 +104,20 @@ class GeocodeService {
      * ```
      */
     async batchRegeocode(locations, options) {
+        // 检查是否有任何输入包含分隔符
+        if (locations.some(loc => loc.includes('|'))) {
+            throw new Error('Invalid location: Individual locations cannot contain the "|" separator.');
+        }
+        const locationStr = locations.join('|');
+        // 校验坐标
+        (0, validators_1.validateCoordinates)(locationStr);
+        const { signal, ...rest } = options || {};
         const params = {
-            location: locations.join('|'),
+            location: locationStr,
             batch: true,
-            ...options,
+            ...rest,
         };
-        return this.client.request('/v3/geocode/regeo', params);
+        return this.client.request('/v3/geocode/regeo', { params, signal });
     }
     /**
      * 批量地理编码
@@ -121,13 +134,17 @@ class GeocodeService {
      * ], '北京');
      * ```
      */
-    async batchGeocode(addresses, city) {
+    async batchGeocode(addresses, city, options) {
+        // 检查是否有任何输入包含分隔符
+        if (addresses.some(addr => addr.includes('|'))) {
+            throw new Error('Invalid address: Individual addresses cannot contain the "|" separator.');
+        }
         const params = {
             address: addresses.join('|'),
             batch: true,
             city,
         };
-        return this.client.request('/v3/geocode/geo', params);
+        return this.client.request('/v3/geocode/geo', { params, signal: options?.signal });
     }
 }
 exports.GeocodeService = GeocodeService;

package/build/services/InputTipsService.js

@@ -5,6 +5,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InputTipsService = void 0;
+const validators_1 = require("../utils/validators");
 /**
  * 输入提示服务
  * 提供根据用户输入的关键词查询返回建议列表
@@ -53,11 +54,15 @@ class InputTipsService {
      * ```
      */
     async getTips(keywords, options) {
+        const { signal, ...rest } = options || {};
+        if (rest.location) {
+            (0, validators_1.validateCoordinate)(rest.location);
+        }
         const params = {
             keywords,
-            ...options,
+            ...rest,
         };
-        return this.client.request('/v3/assistant/inputtips', params);
+        return this.client.request('/v3/assistant/inputtips', { params, signal });
     }
     /**
      * 获取 POI 输入提示

package/build/services/POIService.d.ts

@@ -113,7 +113,9 @@ export declare class POIService {
      * const result = await poi.getDetail('B000A8VE1H|B0FFKEPXS2', 'business,photos');
      * ```
      */
-    getDetail(id: string, show_fields?: string, version?: 'v3' | 'v5'): Promise<POISearchResponse>;
+    getDetail(id: string, show_fields?: string, version?: 'v3' | 'v5', options?: {
+        signal?: AbortSignal;
+    }): Promise<POISearchResponse>;
     /**
      * 批量查询POI详情
      *
@@ -129,5 +131,7 @@ export declare class POIService {
      * ], 'business,photos');
      * ```
      */
-    batchGetDetail(ids: string[], show_fields?: string, version?: 'v3' | 'v5'): Promise<POISearchResponse>;
+    batchGetDetail(ids: string[], show_fields?: string, version?: 'v3' | 'v5', options?: {
+        signal?: AbortSignal;
+    }): Promise<POISearchResponse>;
 }

package/build/services/POIService.js

@@ -4,6 +4,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.POIService = void 0;
+const validators_1 = require("../utils/validators");
 /**
  * POI 搜索服务
  */
@@ -41,13 +42,13 @@ class POIService {
      * ```
      */
     async search(keywords, options) {
-        const { version = 'v5', ...rest } = options || {};
+        const { version = 'v5', signal, ...rest } = options || {};
         const params = {
             keywords,
             ...rest,
         };
         const path = `/${version}/place/text`;
-        return this.client.request(path, params);
+        return this.client.request(path, { params, signal });
     }
     /**
      * 周边搜索
@@ -90,13 +91,15 @@ class POIService {
         else {
             locationStr = `${location.longitude},${location.latitude}`;
         }
-        const { version = 'v5', ...rest } = options || {};
+        // 校验坐标
+        (0, validators_1.validateCoordinate)(locationStr);
+        const { version = 'v5', signal, ...rest } = options || {};
         const params = {
             location: locationStr,
             ...rest,
         };
         const path = `/${version}/place/around`;
-        return this.client.request(path, params);
+        return this.client.request(path, { params, signal });
     }
     /**
      * 多边形搜索
@@ -118,13 +121,14 @@ class POIService {
      * ```
      */
     async searchPolygon(polygon, options) {
-        const { version = 'v5', ...rest } = options || {};
+        (0, validators_1.validateCoordinates)(polygon, '|');
+        const { version = 'v5', signal, ...rest } = options || {};
         const params = {
             polygon,
             ...rest,
         };
         const path = `/${version}/place/polygon`;
-        return this.client.request(path, params);
+        return this.client.request(path, { params, signal });
     }
     /**
      * POI详情查询
@@ -144,13 +148,13 @@ class POIService {
      * const result = await poi.getDetail('B000A8VE1H|B0FFKEPXS2', 'business,photos');
      * ```
      */
-    async getDetail(id, show_fields, version = 'v5') {
+    async getDetail(id, show_fields, version = 'v5', options) {
         const params = {
             id,
             show_fields,
         };
         const path = `/${version}/place/detail`;
-        return this.client.request(path, params);
+        return this.client.request(path, { params, signal: options?.signal });
     }
     /**
      * 批量查询POI详情
@@ -167,7 +171,7 @@ class POIService {
      * ], 'business,photos');
      * ```
      */
-    async batchGetDetail(ids, show_fields, version = 'v5') {
+    async batchGetDetail(ids, show_fields, version = 'v5', options) {
         if (ids.length > 10) {
             throw new Error('批量查询最多支持10个POI ID');
         }
@@ -176,7 +180,7 @@ class POIService {
             show_fields,
         };
         const path = `/${version}/place/detail`;
-        return this.client.request(path, params);
+        return this.client.request(path, { params, signal: options?.signal });
     }
 }
 exports.POIService = POIService;

package/build/services/RouteService.d.ts

@@ -89,7 +89,7 @@ export declare class RouteService {
      *
      * @example
      * ```typescript
-     * const result = await api.route.electr icBike(
+     * const result = await api.route.electricBike(
      *   '116.481028,39.989643',
      *   '116.434446,39.90816'
      * );

package/build/services/RouteService.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RouteService = void 0;
+const validators_1 = require("../utils/validators");
 /**
  * 路径规划服务
  * 提供驾车、步行、骑行、电动车、公交等多种出行方式的路径规划
@@ -13,10 +14,15 @@ class RouteService {
      * 坐标转换辅助方法
      */
     formatCoordinate(coord) {
+        let str;
         if (typeof coord === 'string') {
-            return coord;
+            str = coord;
         }
-        return `${coord.longitude},${coord.latitude}`;
+        else {
+            str = `${coord.longitude},${coord.latitude}`;
+        }
+        (0, validators_1.validateCoordinate)(str);
+        return str;
     }
     /**
      * 驾车路径规划
@@ -48,7 +54,7 @@ class RouteService {
      * ```
      */
     async driving(origin, destination, options) {
-        const { version = 'v5', ...rest } = options || {};
+        const { version = 'v5', signal, ...rest } = options || {};
         const params = {
             origin: this.formatCoordinate(origin),
             destination: this.formatCoordinate(destination),
@@ -64,7 +70,7 @@ class RouteService {
             }
         }
         const path = `/${version}/direction/driving`;
-        return this.client.request(path, params);
+        return this.client.request(path, { params, signal });
     }
     /**
      * 步行路径规划
@@ -85,14 +91,14 @@ class RouteService {
      * ```
      */
     async walking(origin, destination, options) {
-        const { version = 'v5', ...rest } = options || {};
+        const { version = 'v5', signal, ...rest } = options || {};
         const params = {
             origin: this.formatCoordinate(origin),
             destination: this.formatCoordinate(destination),
             ...rest,
         };
         const path = `/${version}/direction/walking`;
-        return this.client.request(path, params);
+        return this.client.request(path, { params, signal });
     }
     /**
      * 骑行路径规划
@@ -114,14 +120,14 @@ class RouteService {
      * ```
      */
     async bicycling(origin, destination, options) {
-        const { version = 'v5', ...rest } = options || {};
+        const { version = 'v5', signal, ...rest } = options || {};
         const params = {
             origin: this.formatCoordinate(origin),
             destination: this.formatCoordinate(destination),
             ...rest,
         };
         const path = `/${version}/direction/bicycling`;
-        return this.client.request(path, params);
+        return this.client.request(path, { params, signal });
     }
     /**
      * 电动车路径规划
@@ -132,21 +138,21 @@ class RouteService {
      *
      * @example
      * ```typescript
-     * const result = await api.route.electr icBike(
+     * const result = await api.route.electricBike(
      *   '116.481028,39.989643',
      *   '116.434446,39.90816'
      * );
      * ```
      */
     async electricBike(origin, destination, options) {
-        const { version = 'v5', ...rest } = options || {};
+        const { version = 'v5', signal, ...rest } = options || {};
         const params = {
             origin: this.formatCoordinate(origin),
             destination: this.formatCoordinate(destination),
             ...rest,
         };
         const path = `/${version}/direction/electrobike`;
-        return this.client.request(path, params);
+        return this.client.request(path, { params, signal });
     }
     /**
      * 公交路径规划（新版 V5 API）
@@ -198,7 +204,7 @@ class RouteService {
      * ```
      */
     async transit(origin, destination, city1, city2, options) {
-        const { version = 'v5', ...rest } = options || {};
+        const { version = 'v5', signal, ...rest } = options || {};
         const params = {
             origin: this.formatCoordinate(origin),
             destination: this.formatCoordinate(destination),
@@ -207,7 +213,7 @@ class RouteService {
             ...rest,
         };
         const path = `/${version}/direction/transit/integrated`;
-        return this.client.request(path, params);
+        return this.client.request(path, { params, signal });
     }
 }
 exports.RouteService = RouteService;

package/build/types/geocode.types.d.ts

@@ -63,6 +63,10 @@ export interface RegeocodeParams {
      * 此参数只在output参数设置为JSON时有效
      */
     callback?: string;
+    /**
+     * AbortSignal 用于取消请求
+     */
+    signal?: AbortSignal;
 }
 /**
  * 地址组成元素
@@ -291,6 +295,10 @@ export interface GeocodeParams {
      * callback值是用户定义的函数名称，此参数只在output参数设置为JSON时有效
      */
     callback?: string;
+    /**
+     * AbortSignal 用于取消请求
+     */
+    signal?: AbortSignal;
 }
 /**
  * 地理编码结果

package/build/types/inputtips.types.d.ts

@@ -24,6 +24,10 @@ export interface InputTipsParams {
      * - busline: 返回公交线路数据类型
      */
     datatype?: 'all' | 'poi' | 'bus' | 'busline' | string;
+    /**
+     * AbortSignal 用于取消请求
+     */
+    signal?: AbortSignal;
 }
 /**
  * 输入提示项

package/build/types/poi.types.d.ts

@@ -51,6 +51,10 @@ export interface POISearchParams {
      * @default 'v5'
      */
     version?: 'v3' | 'v5';
+    /**
+     * AbortSignal 用于取消请求
+     */
+    signal?: AbortSignal;
 }
 /**
  * 周边搜索参数
@@ -121,6 +125,10 @@ export interface POIAroundParams {
      * @default 'v5'
      */
     version?: 'v3' | 'v5';
+    /**
+     * AbortSignal 用于取消请求
+     */
+    signal?: AbortSignal;
 }
 /**
  * 多边形搜索参数
@@ -168,6 +176,10 @@ export interface POIPolygonParams {
      * @default 'v5'
      */
     version?: 'v3' | 'v5';
+    /**
+     * AbortSignal 用于取消请求
+     */
+    signal?: AbortSignal;
 }
 /**
  * POI 详情
@@ -336,4 +348,8 @@ export interface POIDetailParams {
      * @default 'v5'
      */
     version?: 'v3' | 'v5';
+    /**
+     * AbortSignal 用于取消请求
+     */
+    signal?: AbortSignal;
 }

package/build/types/route.types.d.ts

@@ -34,6 +34,10 @@ export interface BaseRouteParams {
      * @default 'v5'
      */
     version?: 'v3' | 'v5';
+    /**
+     * AbortSignal 用于取消请求
+     */
+    signal?: AbortSignal;
 }
 /**
  * 驾车路径规划策略（新版 V5 API）

package/build/utils/client.d.ts

@@ -2,6 +2,10 @@
  * 高德地图 Web API HTTP 客户端
  */
 import { type ErrorInfo } from './errorCodes';
+/**
+ * 从核心包解析 getWebKey（运行时解析，避免类型导出时序问题）
+ */
+export declare function resolveWebKey(): string | undefined;
 /**
  * 高德地图 API 错误类
  */
@@ -54,6 +58,25 @@ export interface ClientConfig {
     baseURL?: string;
     /** 请求超时时间（毫秒），默认：10000 */
     timeout?: number;
+    /** 最大重试次数，默认：3 */
+    maxRetries?: number;
+    /** 重试延迟（毫秒），默认：1000 */
+    retryDelay?: number;
+    /** 是否启用缓存，默认：false */
+    enableCache?: boolean;
+    /** 缓存容量，默认：100 */
+    cacheCapacity?: number;
+}
+/**
+ * 请求选项
+ */
+export interface RequestOptions {
+    /** 请求参数 */
+    params?: Record<string, any>;
+    /** AbortSignal 用于取消请求 */
+    signal?: AbortSignal;
+    /** 是否使用缓存（仅当全局启用缓存时有效），默认：true */
+    useCache?: boolean;
 }
 /**
  * 高德地图 Web API HTTP 客户端
@@ -62,11 +85,22 @@ export declare class GaodeWebAPIClient {
     private key;
     private baseURL;
     private timeout;
+    private maxRetries;
+    private retryDelay;
+    private cache?;
     constructor(config: ClientConfig);
     /**
      * 发起 HTTP 请求
      */
-    request<T>(path: string, params?: Record<string, any>): Promise<T>;
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * 判断是否为可重试的错误码
+     */
+    private shouldRetry;
+    /**
+     * 判断是否为可重试的异常
+     */
+    private isRetryableError;
     /**
      * 更新 API Key
      */

package/build/utils/client.js

@@ -4,7 +4,12 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GaodeWebAPIClient = exports.GaodeAPIError = void 0;
+exports.resolveWebKey = resolveWebKey;
 const errorCodes_1 = require("./errorCodes");
+const lru_1 = require("./lru");
+/**
+ * 从核心包解析 getWebKey（运行时解析，避免类型导出时序问题）
+ */
 function resolveWebKey() {
     // 1) 尝试从核心地图包读取
     try {
@@ -80,11 +85,17 @@ class GaodeWebAPIClient {
         this.key = config.key || resolveWebKey() || '';
         this.baseURL = config.baseURL || 'https://restapi.amap.com';
         this.timeout = config.timeout || 10000;
+        this.maxRetries = config.maxRetries ?? 3;
+        this.retryDelay = config.retryDelay ?? 1000;
+        if (config.enableCache) {
+            this.cache = new lru_1.LRUCache(config.cacheCapacity ?? 100);
+        }
     }
     /**
      * 发起 HTTP 请求
      */
-    async request(path, params = {}) {
+    async request(path, options = {}) {
+        const { params = {}, signal, useCache = true } = options;
         // 构建 URL
         const url = new URL(path, this.baseURL);
         // 添加 key 参数
@@ -95,38 +106,119 @@ class GaodeWebAPIClient {
                 url.searchParams.append(key, String(value));
             }
         });
-        // 创建 AbortController 用于超时控制
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-        try {
-            // 发起请求
-            const response = await fetch(url.toString(), {
-                method: 'GET',
-                signal: controller.signal,
-            });
-            clearTimeout(timeoutId);
-            // 检查 HTTP 状态
-            if (!response.ok) {
-                throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+        // 检查缓存
+        const cacheKey = url.toString();
+        if (this.cache && useCache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                return cached;
             }
-            // 解析 JSON
-            const data = await response.json();
-            // 检查 API 状态
-            if (data.status !== '1' && !(0, errorCodes_1.isSuccess)(data.infocode)) {
-                throw new GaodeAPIError(data.status, data.info || 'Unknown error', data.infocode || '0');
-            }
-            return data;
         }
-        catch (error) {
-            clearTimeout(timeoutId);
-            if (error instanceof Error) {
-                if (error.name === 'AbortError') {
-                    throw new Error(`Request timeout after ${this.timeout}ms`);
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            // 如果外部 signal 已经中止，则直接抛出
+            if (signal?.aborted) {
+                throw new Error('Request aborted');
+            }
+            // 创建 AbortController 用于超时控制
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+            // 处理 signal 合并：如果外部 signal 触发，也要 abort 内部 controller
+            const onAbort = () => controller.abort();
+            if (signal) {
+                signal.addEventListener('abort', onAbort);
+            }
+            try {
+                // 发起请求
+                const response = await fetch(url.toString(), {
+                    method: 'GET',
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (signal) {
+                    signal.removeEventListener('abort', onAbort);
+                }
+                // 检查 HTTP 状态
+                if (!response.ok) {
+                    throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+                }
+                // 解析 JSON
+                const data = await response.json();
+                // 检查 API 状态
+                if (data.status !== '1' && !(0, errorCodes_1.isSuccess)(data.infocode)) {
+                    // 检查是否为可重试的错误码 (QPS超限等)
+                    if (this.shouldRetry(data.infocode) && attempt < this.maxRetries) {
+                        const error = new GaodeAPIError(data.status, data.info || 'Unknown error', data.infocode || '0');
+                        // 抛出错误以触发重试逻辑
+                        throw error;
+                    }
+                    throw new GaodeAPIError(data.status, data.info || 'Unknown error', data.infocode || '0');
+                }
+                // 写入缓存
+                if (this.cache && useCache) {
+                    this.cache.set(cacheKey, data);
+                }
+                return data;
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                if (signal) {
+                    signal.removeEventListener('abort', onAbort);
+                }
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // 如果是 AbortError (无论是超时还是手动取消)
+                if (lastError.name === 'AbortError') {
+                    // 如果是手动取消，不重试
+                    if (signal?.aborted) {
+                        throw new Error('Request aborted');
+                    }
+                    // 如果是超时，且还有重试机会，则继续
+                    if (attempt < this.maxRetries) {
+                        // 继续下一次循环
+                    }
+                    else {
+                        throw new Error(`Request timeout after ${this.timeout}ms`);
+                    }
+                }
+                // 如果不是最后一次尝试，且是可重试的错误（网络错误或特定API错误）
+                if (attempt < this.maxRetries && this.isRetryableError(lastError)) {
+                    // 等待一段时间后重试（指数退避）
+                    const delay = this.retryDelay * Math.pow(2, attempt);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    continue;
                 }
-                throw error;
+                throw lastError;
             }
-            throw new Error('Unknown error occurred');
         }
+        throw lastError || new Error('Unknown error occurred');
+    }
+    /**
+     * 判断是否为可重试的错误码
+     */
+    shouldRetry(infocode) {
+        const retryableCodes = [
+            '10004', // ACCESS_TOO_FREQUENT
+            '10014', // QPS_HAS_EXCEEDED_THE_LIMIT
+            '10015', // GATEWAY_TIMEOUT
+            '10016', // SERVER_IS_BUSY
+            '10017', // RESOURCE_UNAVAILABLE
+            '10019', // CQPS_HAS_EXCEEDED_THE_LIMIT
+            '10020', // CKQPS_HAS_EXCEEDED_THE_LIMIT
+            '10021', // CUQPS_HAS_EXCEEDED_THE_LIMIT
+        ];
+        return retryableCodes.includes(infocode);
+    }
+    /**
+     * 判断是否为可重试的异常
+     */
+    isRetryableError(error) {
+        // GaodeAPIError 已经在 shouldRetry 中判断过了，这里只处理 GaodeAPIError 且 shouldRetry 为 true 的情况
+        if (error instanceof GaodeAPIError) {
+            return this.shouldRetry(error.code);
+        }
+        // 网络错误通常没有 status 属性或者 status 为 undefined (fetch 失败)
+        // 这里简单认为非 API 业务逻辑错误都可以尝试重试（除了 AbortError 已经在上面处理了）
+        return true;
     }
     /**
      * 更新 API Key

package/build/utils/lru.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 简单的 LRU (Least Recently Used) 缓存实现
+ */
+export declare class LRUCache<K, V> {
+    private capacity;
+    private cache;
+    constructor(capacity: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    clear(): void;
+    size(): number;
+}

package/build/utils/lru.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LRUCache = void 0;
+/**
+ * 简单的 LRU (Least Recently Used) 缓存实现
+ */
+class LRUCache {
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.cache = new Map();
+    }
+    get(key) {
+        if (!this.cache.has(key)) {
+            return undefined;
+        }
+        // 刷新访问顺序：先删除再重新添加
+        const value = this.cache.get(key);
+        this.cache.delete(key);
+        this.cache.set(key, value);
+        return value;
+    }
+    set(key, value) {
+        if (this.cache.has(key)) {
+            // 如果已存在，更新值并刷新位置
+            this.cache.delete(key);
+        }
+        else if (this.cache.size >= this.capacity) {
+            // 如果已满，删除最久未使用的项（Map 的第一个项）
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(key, value);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size;
+    }
+}
+exports.LRUCache = LRUCache;

package/build/utils/validators.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 校验经纬度坐标格式
+ * 格式要求：经度,纬度 (例如：116.481028,39.989643)
+ */
+export declare function validateCoordinate(coordinate: string): void;
+/**
+ * 校验多个坐标格式（用于批量请求或多边形）
+ * @param coordinates 坐标字符串
+ * @param separator 分隔符，默认 "|"
+ */
+export declare function validateCoordinates(coordinates: string, separator?: string): void;

package/build/utils/validators.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCoordinate = validateCoordinate;
+exports.validateCoordinates = validateCoordinates;
+/**
+ * 校验经纬度坐标格式
+ * 格式要求：经度,纬度 (例如：116.481028,39.989643)
+ */
+function validateCoordinate(coordinate) {
+    const pattern = /^-?((1[0-7]\d|\d{1,2})(\.\d+)?|180(\.0+)?),-?([0-8]\d(\.\d+)?|90(\.0+)?|\d(\.\d+)?)$/;
+    if (!pattern.test(coordinate)) {
+        throw new Error(`Invalid coordinate format: "${coordinate}". Expected format: "longitude,latitude" (e.g., "116.481028,39.989643")`);
+    }
+}
+/**
+ * 校验多个坐标格式（用于批量请求或多边形）
+ * @param coordinates 坐标字符串
+ * @param separator 分隔符，默认 "|"
+ */
+function validateCoordinates(coordinates, separator = '|') {
+    const coords = coordinates.split(separator);
+    coords.forEach(coord => validateCoordinate(coord));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-gaode-map-web-api",
-  "version": "1.1.4-next.1",
+  "version": "1.1.4-next.3",
   "description": "高德地图 Web API 服务 - 搜索、路径规划、地理编码（纯 JavaScript 实现），配合 expo-gaode-map 使用",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -9,13 +9,12 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
     "clean": "rm -rf build",
     "lint": "node -e \"const { spawnSync } = require('child_process'); const r = spawnSync('tsc', ['--noEmit', '--pretty', 'false'], { stdio: 'inherit' }); process.exit(r.status ?? 1);\" --",
     "test": "bun test",
-    "prepare": "npm run build",
-    "postinstall": "node -e \"try{require.resolve('expo-gaode-map');process.exit(0)}catch(e1){try{require.resolve('expo-gaode-map-navigation');process.exit(0)}catch(e2){console.error('[expo-gaode-map-web-api] 需要安装基础地图组件：expo-gaode-map 或 expo-gaode-map-navigation 中的任意一个。\\bun add expo-gaode-map 或 bun add expo-gaode-map-navigation');process.exit(1)}}\""
+    "prepare": "npm run build"
   },
   "keywords": [
     "react-native",
@@ -38,6 +37,7 @@
   "dependencies": {},
   "devDependencies": {
     "@types/react": "~19.1.0",
+    "bun-types": "^1.3.6",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {