1. 为什么我又把 com.blankj:utilcodex 捡回来了做 Android 开发时间长了你会发现每个项目里总有那么一堆「小工具」存个登录态要写 SharedPreferences 的 apply 和 commit判断个网络要拿 ConnectivityManager弹个 Toast 还要担心主线程文件读写、字符串判空、屏幕尺寸换算……这些代码不难但每个项目都重写一遍纯属浪费生命。com.blankj:utilcodex就是来解决这个问题的它把 Android 开发里高频用到的工具类打包成一个库你只要加一行依赖SPUtils、FileUtils、ToastUtils、SizeUtils、NetworkUtils 这些就能直接用。这篇内容适合两类人一是刚接触这个库、想知道怎么正确引入和初始化的开发者二是已经用过但踩过坑、想搞清楚「为什么我的工具类报空指针」的人。我会从 Gradle 依赖配置讲到初始化再挑几个最常用的工具类做实战调用最后给出验证步骤和常见报错排查。全程配置片段可以直接复制你跟着敲一遍就能跑起来。需要先说明一点utilcodex 是utilcode的 AndroidX 版本包名从com.blankj.utilcode.util开始。如果你项目还在用 support 库那应该用老的utilcode但新项目基本都上 AndroidX 了所以这篇以 utilcodex 为准。2. 引入之前先把 TaoToken 的 Key 准备好在写代码之前有个前置动作容易被忽略如果你打算在项目里接入大模型能力比如让 AI 帮你生成工具类调用示例、做代码补全或者用 Claude Code 这类编码助手来辅助开发那需要一个稳定的 API 入口。我这边一直用的是 TaoToken它的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。具体操作是先到控制台创建一个 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成密钥页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后如果你只是想验证模型通不通可以直接用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 试一句如果是长期写代码、跑 Agent建议看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Claude Code 相关的配置参考 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。这一步和 utilcodex 本身没有强绑定但如果你习惯让 AI 辅助写 Android 代码提前把入口配好后面查工具类用法会顺手很多。Key 拿到后先放一边我们回到 Gradle。3. 可复制的 Gradle 依赖与初始化配置3.1 依赖到底加在哪一层这是 utilcodex 最容易踩的坑也是 excerpt 里特别强调的一点implementation com.blankj:utilcodex:1.30.6这个依赖只能加在主工程app 模块里不能加在 library 模块里再指望主工程能用。原因是 utilcodex 内部依赖了 Android 的资源和 Context 相关能力library 模块打包成 aar 时这些工具类的初始化上下文会丢失最终在主工程调用时就会出现Utils not initialized或者空指针。所以正确做法是打开主工程的app/build.gradle在dependencies块里加dependencies { // 其他依赖... implementation com.blankj:utilcodex:1.30.6 }如果你用的是 Kotlin DSLbuild.gradle.kts写法是dependencies { implementation(com.blankj:utilcodex:1.30.6) }版本号 1.30.6 是写这篇时比较稳定的一个版本你可以按需升级但建议先锁定这个版本跑通再动。3.2 初始化一行代码但位置很关键utilcodex 的初始化必须在Application的onCreate里做而且要在任何工具类调用之前。新建或打开你的自定义 Applicationpublic class MyApp extends Application { Override public void onCreate() { super.onCreate(); // 初始化工具类传入 Application 上下文 Utils.init(this); } }Kotlin 版本class MyApp : Application() { override fun onCreate() { super.onCreate() Utils.init(this) } }别忘了在AndroidManifest.xml里注册这个 Applicationapplication android:name.MyApp android:iconmipmap/ic_launcher android:labelstring/app_name !-- 其他配置 -- /application这里有个细节Utils.init(this)传的是 Application 实例不是 Activity。如果你在 Activity 里初始化虽然当时能用但 Activity 销毁后工具类持有的 Context 就失效了后面在别的页面调用就会出问题。所以老老实实放 Application 里。3.3 混淆规则别忘了加release 包开启混淆后utilcodex 的部分反射逻辑可能被裁掉建议在proguard-rules.pro里加一行-keep class com.blankj.utilcode.** { *; } -keepclassmembers class com.blankj.utilcode.** { *; }不加的话debug 包一切正常release 包突然崩排查起来很费时间。4. 常用工具类实战SPUtils、FileUtils、ToastUtils4.1 SPUtils存登录态和配置项SharedPreferences 原生写法要拿getSharedPreferences、再edit、再applyutilcodex 把它压成一行。默认使用名为Utils的 SP 文件// 存字符串 SPUtils.getInstance().put(token, abc123); // 取字符串第二个参数是默认值 String token SPUtils.getInstance().getString(token, ); // 存布尔值 SPUtils.getInstance().put(is_login, true); boolean isLogin SPUtils.getInstance().getBoolean(is_login, false); // 存对象内部用 Gson 序列化 User user new User(张三, 18); SPUtils.getInstance().put(user, user); User cached SPUtils.getInstance().getString(user) ! null ? new Gson().fromJson(SPUtils.getInstance().getString(user), User.class) : null;如果你想要独立的 SP 文件比如用户相关的单独存SPUtils userSp SPUtils.getInstance(user_config); userSp.put(nickname, coder);实测下来SPUtils 的put默认用的是apply异步写入不会阻塞主线程这点比手写 commit 省心。4.2 FileUtils文件读写和目录判断FileUtils 的方法很多挑几个日常用得上的// 判断文件是否存在 boolean exists FileUtils.isFileExists(/sdcard/test.txt); // 创建文件第二个参数是是否覆盖 File file FileUtils.getFileByPath(/sdcard/demo.txt); FileUtils.createOrExistsFile(file); // 写入字符串 FileUtils.writeFileFromString(file, hello utilcodex, false); // 读取文件内容为字符串 String content FileUtils.readFile2String(file, Charset.defaultCharset()); // 获取应用内部缓存目录 File cacheDir FileUtils.getFileByPath( Utils.getApp().getCacheDir().getAbsolutePath());注意读写外部存储需要权限Android 6.0 以上要动态申请Android 10 以上还要考虑分区存储。utilcodex 帮你简化的是文件操作本身权限这块还是得自己处理。4.3 ToastUtils主线程弹提示不再崩原生 Toast 在子线程调用会抛Cant create handler inside thread that has not called Looper.prepare()ToastUtils 内部做了主线程切换// 简单提示 ToastUtils.showShort(保存成功); // 在子线程里也能直接调 new Thread(() - { ToastUtils.showShort(来自子线程的提示); }).start();如果你觉得默认样式丑可以在 Application 初始化后设置全局样式ToastUtils.setGravity(Gravity.CENTER, 0, 0); ToastUtils.setBgColor(Color.parseColor(#333333)); ToastUtils.setMsgColor(Color.WHITE);这样整个 App 的 Toast 风格就统一了不用每个地方单独写。5. 验证请求跑通第一个工具类调用配置写完怎么确认真的生效了我一般用下面这个最小验证流程。第一步在MainActivity的onCreate里加一段测试代码Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // 验证 SPUtils SPUtils.getInstance().put(init_test, ok); String value SPUtils.getInstance().getString(init_test, fail); Log.d(UtilCodexTest, SPUtils value value); // 验证 ToastUtils ToastUtils.showShort(utilcodex 初始化成功); // 验证 FileUtils File testFile FileUtils.getFileByPath( getCacheDir().getAbsolutePath() /test.txt); FileUtils.writeFileFromString(testFile, hello, false); Log.d(UtilCodexTest, File exists FileUtils.isFileExists(testFile)); }第二步运行 App看 Logcat 过滤UtilCodexTest标签。如果输出SPUtils value ok和File exists true同时屏幕上弹出 Toast说明依赖、初始化、工具类调用全链路通了。第三步如果要做更完整的验证可以写个单元测试需要 Robolectric 或仪器测试环境Test public void testSpUtils() { SPUtils.getInstance().put(unit_test, 123); int result SPUtils.getInstance().getInt(unit_test, 0); assertEquals(123, result); }跑通这一步你就可以放心在项目里用其他工具类了。6. 本篇常见错排查报错一java.lang.NullPointerException在调用 SPUtils 时九成是没初始化或者初始化位置不对。检查AndroidManifest.xml里android:name是否指向了你的 Application 类以及Utils.init(this)是否在onCreate第一行附近。还有一种情况是你在 library 模块里调用了工具类但依赖加在了 library 里——回到 3.1 节依赖必须加在主工程。报错二Utils not initialized或Utils.getApp()返回 null这个和上面类似本质是 Application 上下文没传进去。如果你用了多进程注意每个进程都会走一遍 Application 的onCreate但工具类初始化是全局的多进程场景下要确认主进程先初始化。报错三release 包崩溃debug 正常大概率是混淆问题。加上 3.3 节的 keep 规则然后 clean 重新打包。如果还不行检查是不是用了 Gson 序列化对象但没加 Gson 的混淆规则。报错四Toast 不显示或显示位置异常部分国产 ROM 对 Toast 做了限制尤其是后台弹 Toast。确认你的调用是在前台页面并且没有在 Application 里过早调用。另外ToastUtils.setGravity要在showShort之前设置才生效。报错五FileUtils 读写失败返回 false先确认权限。Android 10 以上写外部存储要用MediaStore或者应用专属目录直接写/sdcard/根路径会被拒。建议优先用getCacheDir()或getExternalFilesDir()这类应用专属路径测试。排查思路总结成一句先看初始化再看依赖层级最后看权限和混淆。这三板斧能解决 90% 的 utilcodex 接入问题。7. 后续怎么用得更顺utilcodex 里工具类很多除了上面三个SizeUtilsdp/px 转换、NetworkUtils网络状态判断、KeyboardUtils软键盘控制、StringUtils字符串判空和格式化都是高频使用的。我的建议是不要一次性全背下来用到哪个查哪个官方文档和源码注释都挺清楚。如果你在写代码时想让 AI 帮你生成某个工具类的调用示例可以先把 TaoToken 的 Key 配好用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接问或者用 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 接入编码助手。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。Claude Code 用户看 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。最后提醒一句utilcodex 虽然方便但别把它当成万能胶。工具类解决的是重复劳动业务逻辑该自己写的还是得自己写。依赖版本也别盲目追新锁定一个稳定版跑通比每次升级踩坑划算。
