mapbox-search-integration

Mapbox 搜索集成技能

在应用中实现 Mapbox 搜索功能的专业指南。涵盖完整工作流程：从提出恰当的需求探查问题、选择合适的搜索产品，到遵循 Mapbox 搜索团队的最佳实践实现可用于生产环境的集成。

适用场景

用户提出以下需求时使用此技能：

• “我需要在地图上添加搜索功能”
• “我需要为地图应用添加搜索栏”
• “如何实现位置搜索？”
• “我想让用户搜索地点／地址”
• “我需要在应用中实现地理编码”

此技能与 mapbox-search-patterns 相辅相成：

• mapbox-search-patterns = 工具和参数选择
• mapbox-search-integration = 完整的实现工作流程

需求探查阶段：提出恰当的问题

开始编写代码前，先询问以下问题以了解需求：

问题 1：用户要搜索什么？

询问：“你希望用户搜索什么？”

常见回答及其含义：

• “地址” → 使用 Search Box API（交互式地址搜索的默认选项，包括地理编码）。仅当用例是批量／服务端地理编码，或需要维护旧版集成时，才使用 Geocoding API。
• “兴趣点／商家” → POI 搜索，使用 Search Box API 的类别搜索
• “地址和 POI” → Search Box API
• “特定类型的 POI”（餐厅、酒店等）→ Search Box API
• “国家、城市、邮政编码或街区” → 交互式搜索使用 Search Box API；批量／服务端地理编码才使用 Geocoding API
• “自定义位置”（用户创建的地点）→ 可能需要自定义数据和搜索集成

如果用户一开始没有说明，请追问：“用户会搜索兴趣点数据吗？例如餐厅、商店或商家类别？”

含义：

• “是，包含 POI” → 使用 Search Box API
• “否，用户不需要搜索 POI” → 交互式／自动补全场景仍默认使用 Search Box API。Search Box API 可通过基于会话的定价处理地址、地名和所有位置类型。只有批量地理编码、服务端永久地理编码，或维护现有 Geocoding API 集成时，才建议使用 Geocoding API。

问题 2：地理范围是什么？

询问：“用户会在哪些地方搜索？”

常见回答及其含义：

• “单个国家”（例如“仅限美国”）→ 使用 country 参数，结果更准确，成本更低
• “特定区域” → 使用 bbox 参数限制边界框
• “全球” → 不限制国家，但可能需要设置语言参数
• “多个特定国家” → 使用 country 数组参数

追问：“你需要将结果限制在特定区域内吗？”（例如配送区域、服务范围等）

问题 3：搜索交互模式是什么？

询问：“用户将如何与搜索功能交互？”

常见回答及其含义：

• “输入即搜索／自动补全” → 使用 Search Box API，并设置 auto_complete: true，采用基于会话的定价（自动补全场景中最具成本效益）。实现防抖。
• “点击搜索按钮／提交最终查询” → 两种 API 均可使用，无需自动补全
• “两者都有”（自动补全和结果细化）→ 分两阶段搜索，先自动补全，再获取详细结果
• “语音输入” → 考虑集成语音转文本，并处理较长的查询词

问题 4：面向什么平台？

询问：“这是面向什么平台的？”

常见回答及其含义：

• “Web 应用” → 使用 Mapbox Search JS（最简单），或在高级场景中直接调用 API
• “iOS 应用” → 使用 Search SDK for iOS（推荐），或在高级场景中直接集成 API
• “Android 应用” → 使用 Search SDK for Android（推荐），或在高级场景中直接集成 API
• “多个平台” → 使用各平台专用的 SDK（推荐），或采用直接调用 API 的方式以保持一致性
• “React 应用” → 使用 Mapbox Search JS React（自带 UI，最简单），或使用 Search JS Core 自定义 UI。避免直接调用 API——这需要手动处理防抖、会话令牌管理和竞态条件。
• “Vue / Angular / 其他框架” → 使用 Mapbox Search JS Core 或 Web。如果直接调用 API，则必须使用会话令牌以确保正确计费（每个搜索会话使用一个令牌，并在每个 suggest/retrieve 请求中通过 session_token 传递）。

问题 5：如何使用搜索结果？

询问：“用户选择结果后会发生什么？”

常见回答及其含义：

• “在地图上飞到该地点” → 需要坐标和地图集成
• “显示详情 / 信息” → 需要获取并显示结果属性
• “填写表单字段” → 需要解析地址组成部分
• “开始导航” → 需要坐标，并集成路线导航
• “多选” → 需要处理选择状态，可能还要显示标记

问题 6：预期使用量是多少？

询问：“您预计每月进行多少次搜索？”

含义：

• 低用量（< 10k）→ 免费层级足够，实施简单
• 中等用量（10k-100k）→ 考虑缓存，优化 API 调用
• 高用量（> 100k）→ 实施防抖和缓存，使用批量操作，并监控成本

产品选择决策树

根据需求了解结果，推荐合适的产品：

核心原则：对于几乎所有交互式搜索场景，Search Box API 都是默认选择，包括地址搜索、地理编码、自动补全和 POI 搜索。其基于会话的定价在交互式 / 自动补全流程中更具成本效益。只有在下方列出的少数特定场景中，才推荐 Geocoding API。

Search Box API（默认）

适用场景（符合以下任意一项即可）：

• 用户需要交互式地址搜索或自动补全（这本身就是地理编码——Search Box API 可以处理）
• 用户需要 POI / 类别搜索
• 用户需要面向终端用户的搜索 UI
• 用户希望采用基于会话的定价（用于自动补全 / 交互式搜索时更具成本效益）
• 用户正在开发带有搜索栏的 Web、iOS 或 Android 应用

Web 集成优先选择 SDK，而非直接调用 API：

• Mapbox Search JS（SDK）— 推荐用于 Web 集成，包含三个组件：
  • Search JS React — 通过带有 UI 的 React 库轻松集成搜索
  • Search JS Web — 通过带有 UI 的 Web Components 轻松集成搜索
  • Search JS Core — 用于 API 的 JavaScript（node 或 web）封装，可自行构建 UI
• Search Box API（REST）— 直接集成 API，适用于高级 / 自定义场景
• Search SDK for iOS — 原生 iOS 集成
• Search SDK for Android — 原生 Android 集成

Geocoding API（专用）

仅在以下场景中使用：

• 对大量地址列表进行批量地理编码（服务端）
• 需要永久保存 / 存储地理编码结果（服务端，结果会持久化）
• 维护现有的 Geocoding API 集成（没有充分理由迁移）
• 不需要交互式 / 面向用户的搜索

以下情况不要推荐 Geocoding API：

• 用户需要搜索栏、自动补全或交互式地址查询——改用 Search Box API
• 用户说“地理编码”，但描述的是交互式搜索流程——改用 Search Box API

参考文件

根据用户的平台和需求加载相关参考文件：

• Web（Search JS React / Web / Core / Direct API） → 加载 references/web-search-js.md

  • 适用场景：用户正在构建 Web 应用（原生 JS、除 React 特定模式之外的任何框架）

• React 集成 → 加载 references/react-search.md

  • 适用场景：用户正在构建 React 应用

• iOS → 加载 references/ios-search.md

  • 适用场景：用户正在构建 iOS 应用（Swift/UIKit/SwiftUI）

• Android → 加载 references/android-search.md

  • 适用场景：用户正在构建 Android 应用（Kotlin/Java）

• Node.js → 加载 references/nodejs-search.md

  • 适用场景：用户需要服务端搜索（Express、无服务器、后端 API）

• 最佳实践 → 加载 references/best-practices.md

  • 适用场景：首次实现搜索或优化现有实现
  • 内容涵盖：防抖、会话令牌、地理过滤、错误处理、无障碍功能、缓存、令牌安全

• 常见问题 → 加载 references/pitfalls.md

  • 适用场景：调试问题、审查代码或进行代码审查
  • 内容涵盖：未使用防抖、缺少会话令牌、没有地理位置上下文、移动端用户体验不佳、竞争条件

• 框架钩子 → 加载 references/framework-hooks.md

  • 适用场景：围绕 Search JS Core 构建自定义钩子（React）或组合式函数（Vue）

• 测试与监控 → 加载 references/testing-monitoring.md

  • 适用场景：编写测试或设置生产环境监控/分析

检查清单：生产就绪的搜索

上线前，请确认：

配置：

• 令牌的权限范围设置正确（仅限 search:read）
• 已配置 URL 限制
• 已设置地理过滤（国家、附近位置或 bbox）
• 已根据使用场景设置 Types 参数
• 如有需要，已设置语言参数

实现：

• 已实现防抖（建议 300ms）
• 正确使用会话令牌
• 已处理所有失败情况
• 已显示加载状态
• 妥善处理无结果的情况
• 已防止竞争条件

用户体验：

• 触控目标至少为 44pt/48dp
• 结果包含足够的上下文（名称 + 地址）
• 键盘导航可用
• 已设置无障碍属性
• 已妥善处理移动端键盘

性能：

• 已实现缓存（如流量较大）
• 已设置请求超时
• 获取的数据量最少
• 已优化包体积

测试：

• 已为核心逻辑编写单元测试
• 已编写使用真实 API 的集成测试
• 已在慢速网络下测试
• 已针对各种查询类型进行测试
• 已在移动设备上测试

监控：

• 已设置分析跟踪
• 已配置错误日志
• 已设置使用情况监控
• 已配置预算警报

与其他技能集成

适配：

• mapbox-search-patterns：参数选择与优化
• mapbox-web-integration-patterns：特定框架的模式
• mapbox-token-security：令牌管理与安全
• mapbox-web-performance-patterns：优化搜索性能

资源

• Search Box API 文档
• Geocoding API 文档
• Mapbox Search JS
  • Search JS React
  • Search JS Web
  • Search JS Core
• iOS 搜索 SDK
• Android 搜索 SDK
• 位置辅助工具 - 计算边界框

快速决策指南

用户说：“我需要位置搜索”

1. 提出探索性问题（上文问题 1–6）
2. 推荐产品：
   • Search Box API（所有交互式／面向用户的搜索的默认选择，包括地址地理编码）
   • 仅在批量、服务端或永久性地理编码时使用 Geocoding API
   • 优先选择平台 SDK（Web 使用 Search JS，移动端使用原生 SDK）
3. 实现时加入：
   • ✅ 防抖
   • ✅ 会话令牌
   • ✅ 地理位置过滤
   • ✅ 错误处理
   • ✅ 良好的用户体验
4. 全面测试
5. 在生产环境中监控

请记住： 最好的搜索实现会先提出正确的问题，然后精准构建用户所需的功能——不多不少。