验证 Android Geocoder 的离线可用性边界

直接回答

Android Geocoder 是设备地理编码实现的接口，不是一个有离线保证的本地地名数据库。isPresent() 只表示设备存在一个可能返回结果的实现；它不保证某一次请求成功，也不保证不使用网络。API 明确提醒地理编码服务的可用性和准确性均无保证，返回结果只是 best guess。其同步方法可能访问网络，也可能阻塞很长时间。这些是平台边界，不代表每个 provider 或手机行为完全相同。 API 33 增加三类 listener overload：按经纬度反向解析、按名称且不设边界框的前向解析、按名称并指定边界框的前向解析。对应同步 overload 自 API 1 存在，并于 API 33 弃用以避免阻塞线程；较旧设备仍须为同步回退明确安排后台线程。listener 可避免同步等待，但 Android 不保证回调时限；每次尝试只调用一种 callback，错误文字也可能缺失或格式不同。异步和同步路径都不保证本地执行、离线、可取消、快速或可用。listener 成功回调也可能带空列表；旧方法在无匹配或无 backend 时可返回 null 或空列表。记录准确 overload、callback 类别、API、locale、请求类型和时间，不要把所有空结果改写成“地址不存在”。 先判断产品是否确实需要地理编码。翻译或保留地址文本，和把地址解析成坐标、把坐标反查为本地化邮寄地址，是不同任务。不能为了让离线 AI 的功能介绍更丰富就调用 Geocoder。如果功能要求可靠的离线查询，应评估单独授权和分发的地理数据集，或保留地址未解析供用户确认。本地数据包另有覆盖范围、更新、存储、语言与授权合同；它不是 Geocoder 暗藏的能力。 若应用提供地理编码，应把地址或坐标视为可能敏感的输入。Android 警告 Geocoder 可能联网，但没有为所有设备指定统一 backend、目的地或载荷。AOSP 实现中 framework 会经 LocationManager/Binder 把请求交给 geocode provider；具体设备上的 provider 工作和外发流量可能位于应用进程/UID 之外。因此，只统计应用 UID 的计数器不能证明 provider 没有联网；Android 也限制普通应用读取其他 UID 的流量计数。不能从本地推理、应用 UID 计数为零或单次缓存结果推断零外发。联网行为应单独披露；敏感地址请求须由用户选择。描述数据流前需用设备级捕获或受控 provider 测试核实，并把结论限定到测试环境。 并发须通过一个状态 owner 处理。每次请求都带 request ID、输入版本、locale 和操作类型。callback 到达时，owner 必须在同一个串行/原子状态转换中比较其身份与当前活动请求并应用候选；若只在 callback 检查，随后再排队写入，旧地址可能在较新状态生效后覆盖结果。过期 callback 必须丢弃。listener 没有已记录的取消、完成顺序或时限保证。保留原地址、限制候选数量，多个地点都合理时由用户选择。 把能力检查和结果检查分开。记录 isPresent()、准确 API 路径、网络策略、输入夹具类别、locale、候选数、空结果与 NULL、IOException 或 callback 错误，以及是否观察到网络活动。断网后用新的合成地址重新请求，不能把先前会话的结果当成离线证明。某个实现可能使用缓存或本地服务，所以一次成功不证明所有查询离线；反之一次失败也不证明所有实现都必须联网。 不要用 best-guess 地理编码结果执行紧急路线、法律边界或其他安全/监管决策。保持用户复核和权威数据源独立于模型建议。本文给出的是核验方法：位置可以保持未解析、经人工确认，或通过明确选中的路径处理并披露限制。它不声称 Cove 集成 Geocoder、实现位置权限流程、包含离线地图数据或测得网络行为。

联网时地址可解析，飞行模式下却无结果

本地助手从用户笔记中提取酒店地址，应用调用 Android Geocoder 转成坐标。一次热启动测试曾返回候选，于是团队认为下次可离线使用。新设备关闭连接后，isPresent() 仍为 true，但 callback 返回空结果。

决策

分别验证 Geocoder 存在状态、每次请求结果、网络行为和地址语义；保留原文并提供人工复核，而不是猜坐标。

预期结果

应用可以报告该请求在已测试条件下未解析，但不能宣称地址无效或承诺所有设备都能离线地理编码。

需要收集的证据

只有将以下证据与同一模型文件和测试运行关联起来，结论才可复核：

• ANDROID-GEOCODER-OFFLINE-AVAILABILITY-2026-10：Android 文档说明 isPresent 只报告实现是否存在；具体请求仍可能失败，服务不保证可用性或准确性。
• ARCH-02：混合架构应明确任务路由和传输数据；该事实不说明 Geocoder 的具体 provider 或网络行为。
• ANDROID-PRIVACY-01：地址和坐标的访问、网络传输与用户控制须由应用单独核验。

任务质量需要有版本记录的语料和验收规则；流畅的单条样例不等于准确度结果。

实施流程

1. 区分地址文本与地理编码. 写明任务需要地址文字、坐标，还是坐标反查标签。保留原始地址；若应用只需翻译或展示，就不要调用 Geocoder。
2. 固定 API 和实现可用状态. 记录设备/API、locale、Geocoder.isPresent()、请求重载和 provider 环境。只把存在状态作为实现线索，不把它当成具体请求成功或离线能力。
3. 选择 overload 并原子应用当前结果. API 33 listener overload 分别处理反向查询、无边界框前向查询、带边界框前向查询；API 33 弃用的同步版本可能阻塞，回退时不得放在主线程。由一个 owner 在同一串行事务内比较 request ID/输入版本并应用结果，不能把校验和写入拆开。丢弃过时 callback，不假设可取消、回调时限或顺序。
4. 分类结果而不猜原因. 分别处理候选、空/NULL、后端缺失、IOException 与后续 callback 失败。保留原始输入并展示候选歧义，不把最佳猜测解释成 ground truth。
5. 验证 provider 的网络归属. 在联网和明确断网策略下运行新鲜夹具，记录准确 overload、应用 UID 和设备级网络观察。framework 的 Binder 委派可能使 provider 外发流量位于应用 UID 之外；应用 UID TrafficStats 为零不能证明无网络。不能从缓存结果或其他阶段本地推理推断零外发。
6. 提供明确回退. 若必须保证离线结果，选用另行审核的本地地理数据集并声明覆盖/更新策略，或让位置保持未决并请求用户确认。不要静默回退到未披露的网络路线。

让每个阶段的状态都可观察。失败信息应指出阶段、模型、运行时和恢复动作，同时避免记录用户私密内容。

验收标准

• 功能分别说明地址翻译/展示、前向地理编码和反向地理编码，不混为一种操作。
• 不把 Geocoder.isPresent() 当成请求成功或离线证明；不把 API 33 异步行为表述为网络或取消保证。
• 区分三种 API 33 listener overload 及同步旧版回退；不假设 callback 顺序/时限/错误格式，过时结果的校验与应用在 owner 内原子完成。
• listener 空列表、旧方法 null/空结果、错误 callback、无 backend、locale 差异和新鲜断网请求都有不同结果。
• 没有独立证据时不声称安全关键位置决策、Cove 集成、provider 去向或零上传。

决策对照表

需要避免的失败模式

• 把 isPresent() 当作特定请求成功或离线工作的证明。
• 把 API 33 GeocodeListener 误解为网络隔离、可取消或按请求顺序完成。
• 把空结果直接标记成地址无效，或把最佳猜测当作准确地点。
• 因本地模型运行就声称地址从未出设备，或默认启动未披露网络回退。

还要避免静默回退、版本未固定、缺少取消处理，以及把不同配置的结果混在一起下结论。失败运行也应与成功记录一并保存。

最小复现记录

发布检查表

• ☐ 主要搜索问题已回答，且没有未经支持的数字。
• ☐ 所有模型文件和运行时版本均已固定。
• ☐ 代表性任务和失败处理策略均有说明。
• ☐ 生命周期、取消、清理和回退均已测试。
• ☐ 用户内容与网络边界均有说明。
• ☐ 结论只适用于被记录的配置。
• ☐ 新增测试结果时链接到原始方法或证据。

来源与相关证据

• 端侧与混合路由边界
• Android privacy and security
• Android API — Geocoder 可用性、网络警告和结果语义
• Android API — GeocodeListener 异步回调
• Android API — NetworkCapabilities 连接状态
• Android API — TrafficStats UID 归属限制
• AOSP — Geocoder framework 委派给 LocationManager
• AOSP — GeocoderProxy 经 Binder 转发给 provider

中文部署与排错专题见。奇连 AI 端侧专题。

常见问题