Android高频代码片段实战：工具封装、权限、协程与避坑

我电脑里有个叫snippets的目录，从入行第二年建到现在，里面塞满了这些年攒下来的 android 常用的代码片段：单位换算、键盘显隐、权限回调、协程模板、崩溃排查口诀。有意思的是，真正高频复用的其实就那么二三十段，剩下的都是当时觉得“以后肯定用得上”、结果再也没打开过的。这篇文章我打算把这些真正天天在用的代码摊开来聊一遍，不只是贴代码，更要讲清楚每一段为什么这么写、不这么写会出什么问题、参数为什么是这个值。内容偏实战，适合刚接手一个已有项目的新人快速对齐写法，也适合写了两三年、代码能跑但总觉得不够稳的同行对照着看看有没有漏掉的细节。全文基于常见工程实践整理，示例以 Kotlin 为主，Java 项目同样适用，思路是一致的。

1. 先把思路捋顺：常用代码到底该怎么攒

1.1 我为什么不再无脑收集代码片段

刚开始那两年，我的做法是见到好用的代码就复制进笔记，按日期建文件夹。结果半年后彻底失控：同一个功能有三四个版本，最早的那个还在用已经废弃的接口，我自己都分不清哪个是最新的。后来改成按“用途”而不是“来源”归档，情况才好转。具体来说分成三类：基础工具类（跟业务无关，任何项目都能直接搬）、架构模板（Activity、Fragment、ViewModel 的骨架写法）、问题修复记录（某个崩溃怎么解、某个机型怎么适配）。这三类的生命周期完全不同：基础工具类可以一直用，架构模板会随版本迭代，问题修复记录往往过一两年就失效了，得定期清理。

这么分的直接好处是，新建项目时我只需要导入第一类和第二类，第三类留在笔记里当参考手册，不会污染代码库。另一个好处是逼着我去判断“这段代码属于哪一类”，一旦发现某段代码既像工具又像业务，那就说明它其实不该被复用，直接留在原项目里就好。这个判断过程本身比代码本身更有价值。

1.2 别把业务逻辑塞进工具类

这是我踩过最大的一个坑。早期写了个Utils类，什么都往里放，从字符串判空到订单状态流转全在里面，最后这个类超过三千行，编译一次要等半天，任何人改一行都要重新跑全量测试。更麻烦的是它依赖了项目里的数据模型，导致这个类根本没法搬到别的项目去，“可复用”三个字完全落空。

现在的原则很硬：工具类只能依赖平台 API 和语言标准库，不能依赖项目里的任何类。一旦发现需要传入自己的实体对象，那说明这段代码的抽象层次不对，应该做成扩展函数或者干脆留在业务层。举个具体例子，判断一个字符串是不是合法手机号，这可以进工具类；判断一个用户对象是不是能下单，这绝对不行。前者只跟字符串有关，后者跟业务规则强绑定，规则一变工具类就得跟着改，到时候又是连锁反应。

1.3 版本兼容这件事，得在写的时候就想到

Android 的碎片化是老生常谈，但真正写代码时容易忘。我给自己定的规矩是：凡是涉及系统版本差异的 API，一律用官方提供的兼容封装，而不是自己写if (Build.VERSION.SDK_INT >= xx)。早期我很喜欢自己判断版本，觉得这样可控，后来发现同一个判断散落在十几个文件里，某次最低版本提升之后要挨个删，删漏一个就是潜在的逻辑分支。

现在的做法是优先用兼容库提供的静态方法，它内部已经处理了版本分支，调用方永远只写一行。实在没有封装的地方，才自己判断，而且必须加注释写明“这段判断在最低版本提升到 X 之后可以删掉”，给自己或者接手的人留个明确的清理入口。这个习惯看起来很小，但在一个需要维护三五年的项目里，能省下大量翻代码的时间。

2. 基础工具层：单位、键盘、时间这几样天天要碰

2.1 屏幕尺寸换算：dp、px、sp 一次说透

这三者的关系我用一个类比解释：px 是物理像素，相当于尺子上的最小刻度；dp 是密度无关像素，相当于“无论尺子多大，一段固定长度的线段看起来一样长”；sp 则是在 dp 基础上再叠加用户设置的字体缩放比例。设计稿给的是 dp 和 sp，代码里很多 API 要的是 px，所以转换函数是使用频率最高的代码之一。

object DisplayUtils { fun dp2px(context: Context, dp: Float): Int { val density = context.resources.displayMetrics.density return (dp * density + 0.5f).toInt() } fun px2dp(context: Context, px: Int): Float { val density = context.resources.displayMetrics.density return px / density } fun sp2px(context: Context, sp: Float): Int { val scaledDensity = context.resources.displayMetrics.scaledDensity return (sp * scaledDensity + 0.5f).toInt() } }

这里有两个细节值得单独说。第一，+ 0.5f不是随手写的，toInt()是直接截断小数部分，3.9会变成3，加上0.5f之后变成4.4，截断后是4，相当于实现了四舍五入，避免大量元素累加后出现一两个像素的偏差。第二，字体必须用scaledDensity而不是density，否则用户在系统设置里把字体调大，你的文字纹丝不动，这在无障碍场景下是很严重的问题。

注意：不要把displayMetrics缓存成静态变量。用户修改字体大小或切换显示缩放之后，Configuration变化会触发界面重建，如果缓存了旧值，新界面拿到的还是旧密度。每次调用时从context.resources现取，开销可以忽略。

另外一点经验：sp2px用于设置TextView的textSize其实没必要，直接用setTextSize(TypedValue.COMPLEX_UNIT_SP, 16f)更清晰，转换函数只在需要整数像素值的地方用，比如自定义 View 的绘制计算。

2.2 软键盘收起与输入框焦点：那些年踩过的坑

软键盘的显隐控制是公认的琐碎问题，因为它的行为和窗口的softInputMode强相关。先把最常用的收起代码放上来：

fun hideKeyboard(activity: Activity) { val imm = activity.getSystemService(Context.INPUT_METHOD_SERVICE) as InputMethodManager val focusView = activity.currentFocus val token = focusView?.windowToken ?: activity.window.decorView.windowToken imm.hideSoftInputFromWindow(token, 0) }

第一行的currentFocus可能为 null，比如页面刚打开还没任何控件获得焦点，这时候硬取.windowToken会直接空指针崩溃。我早期就是这么写的，测试机上都正常，上线之后在低端机上炸了一片。所以必须有兜底，用decorView的 token。清空焦点推荐配合focusView?.clearFocus()一起做，否则输入框虽然失焦视觉上还留着光标。

真正麻烦的是“键盘弹起时布局怎么动”。adjustResize在普通 Activity 上工作良好，内容会被顶上去；但如果你做了全面屏沉浸式、把decorView的fitsSystemWindows关掉了，adjustResize就失效了，键盘会盖住输入框。这种情况下只能手动监听键盘高度变化，用ViewCompat.setOnApplyWindowInsetsListener拿到底部 inset 值，自己给根布局加 padding。这段代码我不贴完整版了，因为不同项目布局结构差异太大，抄过去大概率跑不通，思路是通用的：监听 inset 变化，算出键盘高度，动态调整底部的 margin。

提示：如果页面上有RecyclerView且输入框在底部，记得在键盘弹起时把当前输入项滚动到可见区域，否则用户看不到自己打的字。scrollToPosition配合延迟一小段时间执行，效果更稳。

2.3 时间戳格式化与安全解析

时间处理的坑集中在两点：格式化对象不是线程安全的，以及解析失败会抛异常。先看格式化。

private val dateFormatHolder = object : ThreadLocal<SimpleDateFormat>() { override fun initialValue(): SimpleDateFormat = SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.getDefault()) } fun formatTime(timestamp: Long): String { val sdf = dateFormatHolder.get() ?: return "" return sdf.format(Date(timestamp)) }

用ThreadLocal的原因很直接：SimpleDateFormat内部有个Calendar成员变量，多线程同时格式化会互相覆盖，出现时间错乱甚至抛NumberFormatException。这个 bug 极其隐蔽，本地单线程测一百遍都没事，线上并发一上来就随机出错。API 26 之后可以用DateTimeFormatter，它是不可变对象，天然线程安全，但考虑到大量项目最低版本还压在 21 到 24 之间，ThreadLocal这套写法仍然有存在价值。

解析则必须包起来，绝不裸调：

fun parseTime(text: String?): Long? { if (text.isNullOrBlank()) return null return try { dateFormatHolder.get()?.parse(text)?.time } catch (e: ParseException) { null } }

返回可空类型而不是0L，因为0L对应的是 1970 年，跟“解析失败”在语义上没法区分，调用方很容易误判成有效数据。这是我在一次统计数据报表里发现的问题：某天大批用户的时间显示成 1970 年，排查半天发现是服务端某个字段返回了空字符串，客户端解析失败返回 0，直接拿去格式化了。

3. 界面层：权限、Fragment 通信、状态栏

3.1 运行时权限的标准写法与“拒绝后不再询问”

权限申请的老写法onRequestPermissionsResult已经过时了，现在统一用 Activity Result API。好处是回调不再分散，每个权限申请的逻辑收在发起的地方。

private val cameraPermissionLauncher = registerForActivityResult(ActivityResultContracts.RequestPermission()) { granted -> if (granted) { openCamera() } else { handlePermissionDenied() } } fun requestCamera() { val status = ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) if (status == PackageManager.PERMISSION_GRANTED) { openCamera() } else { cameraPermissionLauncher.launch(Manifest.permission.CAMERA) } }

关键在于handlePermissionDenied里要区分两种情况：用户只是这次点了拒绝，还是勾了“不再询问”。判断方式是再看一眼shouldShowRequestPermissionRationale，返回 false 说明系统已经不打算再弹框了，这时候再申请也没用，必须引导用户去设置页。

private fun handlePermissionDenied() { val canAskAgain = ActivityCompat.shouldShowRequestPermissionRationale( this, Manifest.permission.CAMERA ) if (canAskAgain) { showRationaleDialog() } else { showGoToSettingsDialog() } }

注意：shouldShowRequestPermissionRationale在首次申请前也返回 false，所以不能单独用它判断“是否永久拒绝”，必须结合“是否已经申请过”这个状态一起判断。我一般用一个字段记录本次会话是否发起过申请，避免首次进入就弹“去设置页”的引导，那个体验很差。

还有一个细节：跳设置页之后返回，Activity会重新走onResume，此时权限状态可能已经变了，但不会触发任何回调。正确做法是在onResume里重新检查一次权限状态并更新 UI，而不是干等回调。

3.2 Fragment 与宿主通信：别再强转 Activity

早期写法是在 Fragment 里activity as XxxActivity，然后直接调方法。这写法能跑，但耦合极重，Fragment 一旦被复用到另一个宿主就直接崩。后来官方给了接口回调方案，再后来有了 Fragment Result API，现在我的默认选择是后者。

// 发送方 button.setOnClickListener { setFragmentResult("request_key", bundleOf("amount" to 100)) } // 接收方 override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setFragmentResultListener("request_key") { _, bundle -> val amount = bundle.getInt("amount") updateUi(amount) } }

这个 API 的好处是发送方和接收方互不感知，只依赖一个字符串 key，Fragment 可以随便挪位置。代价是字符串 key 容易写错，所以我会把 key 抽成常量放在一个文件里，发送和接收都引用它，避免手抖。

如果通信方向是“宿主通知 Fragment”，用ViewModel共享数据比回调更合适，因为 Fragment 可能在后台被销毁重建，而ViewModel的生命周期挂在宿主上，数据不会丢。这一点在配置变更（比如旋转屏幕）时体现得特别明显，用回调的写法旋转之后数据就没了，用共享ViewModel则安然无恙。

3.3 沉浸式状态栏的稳妥实现

沉浸式的写法这几年变过好几轮，从SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN到WindowInsetsController。我现在的做法是用兼容封装，一行搞定布局延伸到系统栏后面：

fun setupEdgeToEdge(activity: Activity) { WindowCompat.setDecorFitsSystemWindows(activity.window, false) val controller = WindowCompat.getInsetsController(activity.window, activity.window.decorView) controller.isAppearanceLightStatusBars = true }

isAppearanceLightStatusBars = true的意思是状态栏用深色图标，适合浅色背景；如果页面是深色背景，要设成 false，否则图标和背景糊成一片看不见。这个属性经常被忘记设置，导致深色页面上状态栏时间完全隐形，用户投诉“手机坏了”。

布局延伸之后必须自己处理内边距，否则内容会被状态栏盖住：

ViewCompat.setOnApplyWindowInsetsListener(rootView) { view, insets -> val bars = insets.getInsets(WindowInsetsCompat.Type.systemBars()) view.setPadding(bars.left, bars.top, bars.right, bars.bottom) insets }

提示：不要给所有子 View 都加这个监听，只在根容器加一次就够了。多个层级同时消费 inset 会导致内边距叠加，页面被顶得老远。我见过一个项目在三个层级都加了监听，最后内容被压到屏幕中间一小条，排查了半天。

4. 数据层：本地存储、网络、JSON 防御

4.1 本地存储的封装与它的边界

轻量配置用SharedPreferences没问题，但有几个点必须注意。第一，写入用apply()不用commit()。前者是异步落盘，不阻塞主线程；后者是同步写，在主线程调用超过一定次数会掉帧。只有一种情况必须用commit()：写入之后立刻要跨进程读取，这时候得保证数据已经落盘。

第二，不要存大对象。有人喜欢把整个 JSON 序列化后塞进去，几百 KB 的字符串会让首次读取变慢，因为SharedPreferences是在主线程一次性把整个文件加载进内存的。经验阈值是单个 key 超过 100KB 就该换方案，用文件或者数据库。

object ConfigStore { private const val NAME = "app_config" private const val KEY_TOKEN = "key_token" private fun prefs(context: Context) = context.applicationContext.getSharedPreferences(NAME, Context.MODE_PRIVATE) fun saveToken(context: Context, token: String) { prefs(context).edit().putString(KEY_TOKEN, token).apply() } fun getToken(context: Context): String? = prefs(context).getString(KEY_TOKEN, null) }

这里applicationContext是必须的，用 Activity 作 context 会导致整个 Activity 被静态持有，是经典的内存泄漏来源。另一个隐雷是MODE_MULTI_PROCESS，这个模式早就废弃了，多进程读写同一个文件没有任何一致性保证，如果确实需要跨进程共享配置，老老实实用ContentProvider或者数据库。

4.2 网络请求封装：超时、重试、错误统一

网络层的封装核心不是“怎么发请求”，而是“出错时怎么让上层好处理”。我见过太多项目在每个页面各自try-catch，错误提示文案写得五花八门。统一的做法是定义一个结果类型，把所有异常收敛成有限几种状态。

sealed class ApiResult<out T> { data class Success<T>(val data: T) : ApiResult<T>() data class Failure(val code: Int, val message: String) : ApiResult<Nothing>() data class NetworkError(val throwable: Throwable) : ApiResult<Nothing>() } suspend fun <T> safeApiCall(block: suspend () -> T): ApiResult<T> { return try { ApiResult.Success(block()) } catch (e: SocketTimeoutException) { ApiResult.Failure(-1, "请求超时，请检查网络") } catch (e: UnknownHostException) { ApiResult.NetworkError(e) } catch (e: CancellationException) { throw e } catch (e: Exception) { ApiResult.NetworkError(e) } }

这段代码里最容易被忽略的是CancellationException必须重新抛出。协程取消时也会抛异常，如果把它当成普通错误吞掉，会导致页面已经关闭了请求还在继续，回调回来更新已经销毁的界面，轻则日志报错重则崩溃。这个坑我踩过两次才记住。

超时参数方面，连接超时我一般设 10 到 15 秒，读取超时设 20 到 30 秒。连接超时太短在弱网下会频繁失败，太长用户会以为卡死；读取超时要比连接长，因为服务端处理复杂查询确实需要时间。这些值不是拍脑袋，是拿真实弱网环境跑出来的经验值，具体项目还要根据自己的接口耗时分布调整。

4.3 JSON 解析的空值防御

解析 JSON 时最常见的事故是字段缺失或者类型不对。optString系列方法不会抛异常，但会返回空字符串，跟“本来就没这个字段”区分不开；getString会抛异常，得有兜底。我的习惯是：对外部输入的数据一律用安全取值加默认值，对内部约定的数据可以用严格取值，内部约定崩了说明是程序 bug，早点暴露比藏起来好。

另外一个隐蔽的坑是数字精度。服务端返回一个超过 16 位的 ID，用Double接会丢精度，最后两位变成 0，导致这个 ID 查不到数据。这类问题在订单号、雪花算法 ID 上特别常见。解决方式很简单：ID 一律用字符串接收，或者用Long显式解析，绝不让它走Double通道。

fun parseId(json: JSONObject, key: String): Long? { val raw = json.optString(key).orEmpty() if (raw.isBlank()) return null return raw.toLongOrNull() }

用optString先转成字符串再转Long，可以同时兼容“服务端返回数字”和“服务端返回字符串”两种情况，这在对接多个数据源时非常省事。

5. 异步与线程：主线程之外的事怎么安排

5.1 主线程更新 UI 的几种姿势

从子线程回到主线程，最常用的还是Handler和runOnUiThread。runOnUiThread内部会判断当前线程，如果已经在主线程就直接执行，否则 post 到消息队列，用起来最省心。Handler的优势是可以延迟执行和取消，比如搜索框的防抖：

private val handler = Handler(Looper.getMainLooper()) private val searchRunnable = Runnable { performSearch() } fun onTextChanged(text: String) { handler.removeCallbacks(searchRunnable) if (text.isNotBlank()) { handler.postDelayed(searchRunnable, 300) } }

removeCallbacks那行是关键，每次输入变化先把上一个待执行的任务撤掉，避免用户快速输入时堆出一串请求。300 毫秒这个值是我试出来的：再短防抖意义不大，再长用户会觉得反应迟钝。写完记得在页面销毁时handler.removeCallbacksAndMessages(null)，否则延迟任务可能在界面已经关闭后触发，访问到已销毁的 View。

5.2 协程常用模板：生命周期、取消、异常

协程的代码看着简单，坑在生命周期绑定。直接在lifecycleScope.launch里写循环收集数据流，页面退到后台时收集器还在跑，白白耗电。正确写法加repeatOnLifecycle，让它在可见时才收集、不可见时自动取消。

lifecycleScope.launch { repeatOnLifecycle(Lifecycle.State.STARTED) { viewModel.uiState.collect { state -> render(state) } } }

repeatOnLifecycle的语义是：进入 STARTED 时启动协程块，离开时取消，再回来重新启动。这比手动在onStart/onStop里记标志位可靠得多，因为配置变更、跳转返回各种边界情况它都处理了。

异常处理上我有个习惯：所有可能失败的挂起函数都在最外层统一 catch，而不是每层都 try。中间层加 try 会让异常传播路径变得模糊，调试时很难判断异常在哪一层被吞了。另外给withTimeout设一个明确的值，比如 8 秒，超时就抛异常走失败分支，比让用户干等强。

5.3 线程池核心参数怎么定

自己建线程池时最容易随便写数字。核心线程数和最大线程数跟任务类型强相关：CPU 密集型任务（大量计算、图片处理）设成 CPU 核数加一就够，再多的线程只会互相抢 CPU 时间片，反而更慢；IO 密集型任务（网络、文件读写）可以设到核数的两倍甚至更多，因为线程大部分时间在等，不占 CPU。

队列也不能用无界的。无界队列意味着任务无限堆积，内存一路涨到崩溃，而且完全看不出问题出在哪。我的做法是用有界队列加明确的拒绝策略，拒绝之后记录日志或者降级处理，至少能观测到压力。这些参数我没有固定值，通常会写个压力测试跑一遍，观察任务排队时间和内存占用，再调两轮定下来。

6. 常见问题与排查实录

6.1 高频问题速查表

下面这张表是我这些年总结的高频问题，按“现象到原因”组织，遇到类似症状可以直接对照。

6.2 排查问题的几个习惯

第一个习惯是先看日志的因果顺序，而不是只看报错行。崩溃堆栈里最后一行往往只是压垮骆驼的那根稻草，真正的原因在更早的地方。我习惯从崩溃点往上翻十几行，看当时的生命周期状态和参数值，很多时候一眼就能看出是空指针还是并发问题。

第二个习惯是所有可疑的 catch 都要留痕。空 catch 块是排查问题最大的敌人，异常被吞掉之后，现象是“功能没反应”，完全无线索。至少打一行日志，哪怕只有一句“解析失败”。

第三个习惯是把版本兼容性当成常规检查项。每次引入一个新 API 之前先确认最低版本支持情况，不确定就去官方文档查，别靠猜。我见过太多“在我的测试机上好好的，在旧机型上直接崩”的情况，根本原因就是没留意最低版本。

最后一个习惯，可能也是最实用的一个：每修完一个 bug，把它对应的代码片段和一句说明加到笔记里。不是为了以后抄，而是为了下次遇到同类问题时能想起“我好像处理过类似的”。这些年真正帮我省时间的，不是那些写得多漂亮的工具类，而是这类“当时是怎么想通的”的记录。它让我在面对一个陌生的崩溃时，至少知道该从哪个方向先怀疑。