Android函数文档生成器

函数名称：requestLocationOnce — 请求一次高精度定位

简要描述：

• 发起一次高精度定位请求，自动检查并申请所需定位权限。
• 在指定超时时间内未获取到实时位置时，回退返回最近一次缓存位置。
• 通过回调返回经纬度与精度信息，完成后自动移除定位更新监听，避免资源泄漏。
• 适用于前台组件（Activity）内的单次定位场景。

参数详细说明：

• activity: ComponentActivity
  • 说明：用于权限申请与生命周期绑定的上下文组件。请在组件处于有效生命周期（如已启动/可见）时调用。
  • 约束：不可为 null；建议为当前前台页面的 Activity 实例。
• timeoutMs: Long
  • 说明：定位超时时间，单位为毫秒。超过该时间仍未获取到实时位置时，将回退到最近一次缓存位置。
  • 约束：应为正整数；过短可能导致频繁回退到缓存位置，过长会增加等待时间。
• priority: LocationPriority
  • 说明：定位精度策略，用于控制定位的精度与耗电/延迟权衡。具体可选值以项目中该类型定义为准。
  • 约束：传入合法的策略枚举/配置；不合法的策略可能被忽略或导致请求失败。
• onResult: (Location) -> Unit
  • 说明：定位成功回调，仅回调一次。可能为实时位置或在超时后返回的最近一次缓存位置。
  • 返回数据：Location 对象，包含至少以下信息：
    • latitude：纬度（Double）
    • longitude：经度（Double）
    • accuracy：精度（米，Float/Double，依实现而定）
• onDenied: () -> Unit
  • 说明：权限被拒绝时触发的回调（包括用户明确拒绝的情况）。仅回调一次。

返回值说明：

• 本函数为异步操作，无直接返回值（Unit）。
• 结果通过回调返回：
  • 成功：触发 onResult，提供 Location（实时或缓存）。
  • 权限拒绝：触发 onDenied。
• 完成回调后自动移除定位更新监听，无需手动清理。

使用示例代码：

class SampleActivity : ComponentActivity() {

    fun fetchLocationOnce() {
        requestLocationOnce(
            activity = this,
            timeoutMs = 10_000L, // 10 秒超时
            priority = /* 根据项目定义选择合适策略，例如：LocationPriority.HighAccuracy */,
            onResult = { location ->
                val lat = location.latitude
                val lng = location.longitude
                val acc = location.accuracy
                // 使用定位结果，例如上传或展示
                // updateUi(lat, lng, acc)
            },
            onDenied = {
                // 展示权限被拒绝的提示或引导用户查看权限设置
                // showPermissionDeniedDialog()
            }
        )
    }
}

注意事项和异常处理：

• 权限：
  • 函数会自动检查并申请定位权限；若用户拒绝，将触发 onDenied。
  • 已授予权限的情况下不会再次弹窗。
• 生命周期与上下文：
  • 需传入当前有效的 ComponentActivity；若组件已销毁或不可见，可能导致权限流程或定位请求无法正常进行。
• 超时与缓存：
  • 超时后回退到最近一次缓存位置。缓存位置可能与实时位置存在偏差，请根据业务判断可用性。
  • 建议为 timeoutMs 设定合理值，以平衡等待时长与缓存回退的概率。
• 回调调用次数：
  • onResult 与 onDenied 均为单次回调；不会重复触发。
• 线程与耗时操作：
  • 回调中的处理请避免阻塞（例如长时间 I/O），以免影响界面体验。
• 监听清理：
  • 函数在回调后会自动移除定位更新监听，无需额外清理。

相关函数或模块链接：

• 所属模块：位置/权限
• 相关：位置权限申请与单次定位功能（具体链接或文档条目以项目实际文档为准）

函数名称：fetchJsonWithCache 简要描述：从指定 URL 获取 JSON 数据，结合 ETag/Last-Modified 进行条件请求与本地磁盘缓存。支持在网络不可用时使用有效缓存进行离线回退，并处理请求超时。成功时将响应解析为 JSONObject 并通过回调返回，失败时通过错误回调返回异常。

参数详细说明

• url: String
  • 描述：请求地址，需为可访问的绝对 HTTP/HTTPS URL。
  • 约束：必须为有效的 URL；建议使用 HTTPS 以保障安全。
• cacheKey: String
  • 描述：本地磁盘缓存的键，用于标识与复用对应的缓存条目（包含响应体、ETag、Last-Modified、写入时间戳）。
  • 约束：在同一数据集内需保持唯一与稳定；变更后将视为不同缓存。
• maxAgeMinutes: Int
  • 描述：缓存有效期（分钟）。用于控制离线回退时是否允许使用缓存。
  • 约束：应为正整数（> 0）；过期缓存不会在离线回退中使用。
• headers: Map<String, String>
  • 描述：追加到 HTTP 请求的额外请求头。
  • 约束：键与值均为非空字符串；若包含 If-None-Match 或 If-Modified-Since，可能被内部的条件请求头覆盖或与其冲突，建议不要自行设置这两个头。
• onSuccess: (JSONObject) -> Unit
  • 描述：成功回调，提供解析后的 JSONObject。
  • 调用约束：仅调用一次；回调线程未作保证，调用方如需在主线程处理，请自行切换线程。
• onError: (Throwable) -> Unit
  • 描述：失败回调，提供导致失败的异常信息。
  • 调用约束：仅调用一次；当网络不可用且缓存不存在或已过期、HTTP 非 2xx、超时、解析失败等情况将触发。

返回值说明

• 返回类型：Unit（异步执行）
• 结果交付：通过 onSuccess 或 onError 二选一回调交付结果，不直接返回数据。
• 成功条件：
  • 在线场景：服务端返回 200 及合法 JSON；或返回 304 时读取缓存成功。
  • 离线场景：存在未过期（maxAgeMinutes 内）缓存并读取成功。
• 失败条件：
  • URL 无效、网络不可用且无有效缓存、请求超时、HTTP 非 2xx/304、响应体为空或非合法 JSON、磁盘读写异常等。

函数行为与数据处理流程（概要）

• 条件请求与缓存协作
  • 若缓存中存在 ETag 或 Last-Modified：
    • 在线发起条件请求，分别设置 If-None-Match 与/或 If-Modified-Since。
    • 响应 304 Not Modified：读取并返回缓存 JSON。
    • 响应 200 OK：更新缓存（响应体 + 新的 ETag/Last-Modified + 写入时间戳），返回新的 JSON。
  • 若无缓存元数据：直接 GET，成功后写入缓存。
• 离线回退
  • 检测网络不可用时，若存在未过期缓存（当前时间 - 写入时间 ≤ maxAgeMinutes）：直接返回缓存。
  • 无缓存或缓存过期则走错误回调。
• 请求超时
  • 超时作为失败处理，触发 onError；超时时间由内部实现或全局网络配置决定。

使用示例代码

// 调用示例（Kotlin）
fetchJsonWithCache(
    url = "https://api.example.com/v1/profile",
    cacheKey = "profile_v1",
    maxAgeMinutes = 30,
    headers = mapOf(
        "Authorization" to "Bearer <token>",
        "Accept" to "application/json"
    ),
    onSuccess = { json ->
        // 解析字段示例（确保服务端返回顶层为对象）
        val name = json.optString("name")
        val age = json.optInt("age", -1)
        // 更新 UI：如需在主线程，请切换线程（例如使用 Handler/Dispatchers.Main）
    },
    onError = { error ->
        // 统一错误处理与提示
        // 可根据异常类型进行分支处理（超时、网络不可用、解析失败等）
        // 例如：Log.e("fetchJsonWithCache", "request failed", error)
    }
)

注意事项和异常处理

• 顶层 JSON 类型：onSuccess 回调的参数类型为 JSONObject，若服务端返回顶层为数组或非 JSON，解析将失败并触发 onError。请确保接口返回顶层为对象，或在服务端调整格式。
• 缓存键设计：cacheKey 应与接口路径及业务版本强关联；若接口字段或结构变更，请更换 cacheKey 以隔离旧缓存。
• 有效期控制：离线回退仅在缓存未过期时进行；过期缓存不会返回。若需“过期但可用”的策略，请在调用侧增加降级逻辑（例如自行读取缓存文件）。
• 条件请求头冲突：内部会设置 If-None-Match/If-Modified-Since（基于缓存元数据）。请勿在 headers 中重复设置这两个头，以避免不可预期行为。
• 回调线程：不保证在主线程回调。UI 更新前请切换到主线程。
• 错误类型（可能的 Throwable）
  • IllegalArgumentException：URL 不合法或参数不符合约束。
  • IOException/UnknownHostException：网络错误或域名解析失败。
  • SocketTimeoutException：请求超时。
  • JSONException：响应体无法解析为 JSONObject。
  • 其他 I/O 异常：磁盘读写失败、缓存损坏等。
• 数据一致性：在同一 cacheKey 上并发请求可能引起缓存写入竞争；如需严格一致性，请在调用侧序列化请求或加锁。
• 安全建议：优先使用 HTTPS；避免在 headers 中传递敏感信息的明文。

相关函数或模块链接

• 模块：网络/数据访问（内部文档，待补充）
• HTTP 条件请求与缓存规范（ETag/Last-Modified）：https://www.rfc-editor.org/rfc/rfc7232
• Android org.json.JSONObject 文档：https://developer.android.com/reference/org/json/JSONObject