简介这套安卓通讯录开发源码专为初学安卓的开发者设计用 Java 实现了账号登录、注册以及通讯录联系人的添加、修改、删除、查询等完整功能既适合课堂练习也可作为课程设计或毕业设计的参考原型。资源包共含 1034 个文件以 XML 布局与配置、PNG 图标、JSON 数据、Java 源码和构建生成的 class、jar 文件为主并附带了可手机直接安装的 APK整体大小约 5.67MB目录结构清晰便于按需查看与二次开发。项目将登录注册与联系人管理串联成完整流程涉及 Activity 跳转、事件监听、数据存储和列表展示等核心知识点同时保留了构建脚本、调试信息与打包产物初学者可对照源码理解从界面设计到逻辑实现的每一步也能借助构建产物验证运行效果。目前已有 5563 人浏览学习适合需要快速上手安卓项目或准备相关实训作业的开发者参考使用。1. 项目需求与整体技术选型1.1 通讯录项目到底在练什么做通讯录开发是我带新人时最喜欢安排的一个实战项目。原因很简单它麻雀虽小五脏俱全把Android开发的核心知识点几乎全部串起来了。你看着就是一个联系人增删改查实际上背后涉及界面布局、列表复用、本地数据库、运行时权限、生命周期管理、数据绑定每一项都是日常开发里躲不开的东西。拿Android Studio来说从创建项目那一刻开始你就要面对Gradle版本、SDK版本、依赖库选型这一堆选择。很多新手在这里就被绕晕了项目还没写几行代码先花了一下午配环境。我见过不少同事和朋友卡在依赖下载慢、Gradle同步失败、AGP和Gradle版本不匹配这些问题上最后连Hello World都没跑起来。所以这次写这个项目我会先从工程搭建讲起把版本选型和依赖配置的坑一起填掉。这个项目适合谁来参考如果你已经能跑通一个空白的Android项目但对Room数据库、RecyclerView、ViewModel这一套组合还不熟那这篇实战记录能帮你把整条链路理清。如果你还在纠结“通讯录到底该用什么架构”那我把自己的选型思路和踩坑过程完整讲一遍你至少能少走几周弯路。1.2 技术栈选型为什么是Room RecyclerView ViewModel通讯录项目的核心诉求很简单存联系人、读联系人、改联系人、删联系人外加一个列表展示和搜索。技术选型我首推四件套Kotlin Room RecyclerView ViewModel/LiveData。这套组合可以说是Google官方推荐的标准姿势社区资料最多遇到问题基本都能搜到答案。数据库这块SQLite当然也能写但你得手动处理大量的模板代码定义表结构、写增删改查语句、管理数据库连接、处理游标关闭。Room的本质是在SQLite上面包了一层编译期帮你校验SQL语句是否正确运行期用DAO接口直接操作对象。对通讯录这种实体关系比较简单的项目来说Room能把数据层代码量砍掉一半以上。而且Room天生支持LiveData返回查询结果数据库一变化UI立刻自动刷新这正好解决通讯录列表“加了联系人马上能看到”这个核心体验。列表展示用RecyclerView适配器里配合ListAdapter DiffUtil做差量更新。用过ListView的朋友应该有体会数据一变就得notifyDataSetChanged整个列表全刷又卡又浪费。DiffUtil能精准算出哪一行变了、哪一行新增了只刷新有变化的部分性能表现完全不在一个级别。界面架构上用ViewModel来持有联系人数据配合LiveData实现数据和UI分离。这样旋转屏幕时数据不丢Activity只负责观察数据、渲染界面逻辑清晰后续加需求也好加。Kotlin协程用来做数据库的异步操作避免在主线程读写数据库导致卡顿。2. 数据库设计与业务逻辑拆解2.1 联系人表怎么设计才够用通讯录的数据模型看起来简单但设计的时候还是有几个细节需要注意。基础字段无非是姓名、电话、邮箱、头像、备注这些。但我建议从第一天起就加上创建时间和更新时间这两个字段别问我为什么——等你要做排序、做“最近添加”功能、或者排查数据异常的时候就会感谢我。主键这里有个讲究。联系人这种数据适合用自增Long作为主键因为电话号码不适合当主键一个人可能有好几个号码同一个号码也可能被家人共用比如家庭固话。如果直接用号码当唯一标识后面会给自己埋坑。Room支持PrimaryKey(autoGenerate true)让数据库自己分配ID这是最稳妥的方案。姓名索引要不要加看数据量。通讯录几百条联系人不加索引全表扫描也就几毫秒但如果后面要做到几千上万条搜索就会明显变慢。我习惯在姓名列上加一个索引成本极低收益长期存在。Room里加索引很省事直接在Entity注解里写indices就行。Entity( tableName contacts, indices [Index(value [name])] ) data class Contact( PrimaryKey(autoGenerate true) val id: Long 0, val name: String, val phone: String, val email: String , val avatarUri: String? null, val note: String , val createdAt: Long System.currentTimeMillis(), val updatedAt: Long System.currentTimeMillis() )2.2 Room的接入配置和Gradle依赖在Android Studio里接Room第一个要面对的就是Gradle依赖版本问题。这里我把2024年这个节点上稳定可用的版本组合写出来。我用的Android Studio版本是Hedgehog2023.1.1 Patch 2AGP版本8.2.2Gradle 8.2Kotlin 1.9.22Room 2.6.1。这个组合实测下来兼容性很好没有遇到KAPT和KSP的兼容冲突。Room 2.6.1默认开始推荐用KSP替代KAPT来做注解处理。KSP比KAPT快很多编译一次能省下几十秒。你需要在项目根目录的build.gradle.kts里声明KSP插件版本然后在模块级里应用。plugins { id(com.google.devtools.ksp) version 1.9.22-1.0.17 apply false }模块级的依赖配置plugins { id(com.android.application) id(org.jetbrains.kotlin.android) id(com.google.devtools.ksp) } dependencies { implementation(androidx.room:room-runtime:2.6.1) implementation(androidx.room:room-ktx:2.6.1) ksp(androidx.room:room-compiler:2.6.1) implementation(androidx.lifecycle:lifecycle-viewmodel-ktx:2.7.0) implementation(androidx.lifecycle:lifecycle-livedata-ktx:2.7.0) }还有一点需要特别注意KSP版本必须跟Kotlin版本严格匹配。我见过很多人报错ksp version mismatch就是因为换了Kotlin版本但忘了同步升级KSP插件。这个对应关系在KSP的GitHub仓库里有一张表每次升级Kotlin之前先查一下。2.3 DAO层的编写思路与常见坑DAO是Room的核心操作入口它的接口定义直接决定了你后续业务代码好不好写。通讯录的常规操作就四类查询全部、按ID查询、插入、更新、删除。我建议再额外加两个方法按关键字搜索和统计总数。查询全部的时候我直接用LiveData作为返回类型。这样数据库里数据一变LiveData会自动收到通知列表自动刷新完全不需要手动重新查询。这在通讯录场景下特别实用因为你新增、修改、删除联系人之后列表必须同步变化LiveData把这些同步逻辑全部省掉了。搜索接口我用的方式是WHERE name LIKE % || :keyword || %虽然在大数据量下不走索引但通讯录这个量级完全够用。如果以后数据量上去了可以考虑用FTS4全文搜索那是另外一套玩法。Dao interface ContactDao { Query(SELECT * FROM contacts ORDER BY createdAt DESC) fun getAllContacts(): LiveDataListContact Query(SELECT * FROM contacts WHERE id :id) suspend fun getContactById(id: Long): Contact? Query(SELECT * FROM contacts WHERE name LIKE % || :keyword || % ORDER BY name ASC) fun searchContacts(keyword: String): LiveDataListContact Insert suspend fun insert(contact: Contact): Long Update suspend fun update(contact: Contact) Delete suspend fun delete(contact: Contact) }这里有一个FileNotFoundException的经典坑想提醒一下。很多人第一次写Room插入操作时直接在主线程调用DAO方法结果崩溃日志里报AndroidRuntimeException: Cannot access database on the main thread。Room默认不允许在主线程跑数据库操作我这套代码里DAO方法全部用了suspend关键字配合协程在IO线程执行这个坑就不会踩到。如果你用的Room版本比较老不支持协程那就得手动用executor.execute()包一层麻烦很多。3. 核心实现界面搭建与权限处理3.1 动态权限申请这一步绕不开通讯录App有个特殊的地方它不是读取系统通讯录而是自己管理一批联系人所以严格来说不需要申请READ_CONTACTS权限。但如果你的需求是“从系统通讯录导入联系人”那就必须处理运行时权限。我建议一开始就把权限这块做对不然后面加导入功能的时候又要返工。Android 6.0API 23之后危险权限必须在运行时动态申请。Manifest.permission.READ_CONTACTS就属于危险权限。写权限同理如果你要支持“导出联系人到本地文件”WRITE_EXTERNAL_STORAGE在Android 10以后用MediaStore那一套Android 13以后又加了READ_MEDIA_VIDEO这些细分权限这块每个版本都有差异执行时一点要查清楚当前targetSdkVersion对应的规则。下面是我用的动态权限申请模板基于registerForActivityResult这套API这是目前最推荐的写法private val requestPermissionLauncher registerForActivityResult( ActivityResultContracts.RequestPermission() ) { granted - if (granted) { importFromSystemContacts() } else { Toast.makeText(this, 需要通讯录权限才能导入联系人, Toast.LENGTH_SHORT).show() } } private fun checkAndRequestPermission() { val permission Manifest.permission.READ_CONTACTS if (ContextCompat.checkSelfPermission(this, permission) PackageManager.PERMISSION_GRANTED) { importFromSystemContacts() } else { requestPermissionLauncher.launch(permission) } }这套写法要注意一点如果用户拒绝了权限你再次调用launch()的时候系统不会再弹出授权框而是直接回调granted false。所以严谨一点应该用shouldShowRequestPermissionRationale()判断用户是否点了“不再询问”引导用户去设置页手动开启。我在第四章节会专门讲这个问题的排查方法。3.2 RecyclerView列表与ListAdapter实现列表界面我用了RecyclerView ListAdapter的组合。ListAdapter和普通Adapter最大的区别是它内置了AsyncListDiffer在后台线程计算新旧列表的差异然后精准刷新。通讯录列表这种频繁增删改的场景这个特性太关键了。DiffUtil的回调需要你告诉它“什么时候两个item代表同一个人”以及“什么时候item内容变了”class ContactDiffCallback : DiffUtil.ItemCallbackContact() { override fun areItemsTheSame(oldItem: Contact, newItem: Contact): Boolean { return oldItem.id newItem.id } override fun areContentsTheSame(oldItem: Contact, newItem: Contact): Boolean { return oldItem newItem } }这里有个细节areContentsTheSame我直接用了data class的equals比较。如果你之后在Contact里加了Bitmap这种不适合放在equals里的字段就得手动逐字段比较了。所以Contact里我存的是avatarUri字符串而不是Bitmap这也是一个经验——数据库和实体类里永远不要直接放Bitmap这类重量级对象存路径或者URI才是正确姿势。ViewHolder的绑定逻辑也很直白两个Textview一个显示姓名一个显示电话号码class ContactViewHolder(private val binding: ItemContactBinding) : RecyclerView.ViewHolder(binding.root) { fun bind(contact: Contact) { binding.tvName.text contact.name binding.tvPhone.text contact.phone } }Adapter继承ListAdapter之后对外只需要一个submitList()方法。更新数据的逻辑全在ViewModel里做数据一变化LiveData回调触发再调用adapter.submitList(newList)剩下的事交给DiffUtil。3.3 新增和编辑联系人界面一个Activity怎么复用增和改在很多代码示例里是分开写的一个AddActivity一个EditActivity。但实际开发中这两个界面往往长得一模一样差别只是有没有预填数据。我建议用一个EditContactActivity通过Intent传一个contactId参数。ID为-1表示新增ID大于0表示编辑用同一个布局和同一套保存逻辑代码能省一半。布局文件里就是几个TextInputLayoutTextInputEditText分别放姓名、电话、邮箱、备注。电子邮箱不是必填项但校验逻辑不能省。电话号码这块也有讲究最好是限制输入类型为phone并且不要限制长度——因为有些国家区号加电话号码能到十几位硬限制11位会让用户输不进去。这个坑我实际遇到过用户从国外回来发现号码存不进去反馈了一整页。保存按钮的点击逻辑大概是这样的private fun saveContact() { val name binding.etName.text?.toString()?.trim().orEmpty() val phone binding.etPhone.text?.toString()?.trim().orEmpty() if (name.isEmpty()) { binding.etName.error 姓名不能为空 return } if (phone.isEmpty()) { binding.etPhone.error 电话号码不能为空 return } val contact if (contactId 0) { Contact(id contactId, name name, phone phone, ...) } else { Contact(name name, phone phone, ...) } viewModel.saveContact(contact) }DAO层的Insert和Update方法是分开的但Room里还有一个隐藏技巧Upsert注解可以自动判断数据存在就更新、不存在就插入。如果你用的是Room 2.5.0以上版本直接定义Upsert suspend fun upsert(contact: Contact)新增和编辑就能共用同一个方法业务代码又简化一层。这就是我推荐在选型时尽量用最新稳定版的原因——很多好用的语法糖都是新版才有的。4. 踩坑实录常见问题与定位思路4.1 Gradle同步慢、依赖下载失败这个坑几乎人人都会遇到而且它跟你的代码质量没有半点关系纯粹是环境问题。国内外网速差异导致Maven仓库下载很慢尤其Google的仓库一个包几百兆卡上半小时很正常。解决思路有两个一是配置镜像仓库把google()和mavenCentral()替换成国内可访问的镜像地址比如阿里云的镜像二是用Gradle提供的离线模式把依赖缓存好之后断网编译。我自己常用的做法是配置镜像仓库地址repositories { maven { url uri(https://maven.aliyun.com/repository/public) } maven { url uri(https://maven.aliyun.com/repository/google) } maven { url uri(https://maven.aliyun.com/repository/gradle-plugin) } mavenCentral() }配置好之后建议把Gradle的distributionUrl也切换成国内镜像加速下载那段URL在项目根目录的gradle/wrapper/gradle-wrapper.properties里。Android Studio自己的镜像地址在File - Settings - Appearance Behavior - System Settings - HTTP Proxy里也能设置。4.2 AGP版本和Gradle版本不匹配这个报错信息非常经典The Android Gradle plugin requires Gradle X.Y.Z. Current version is X.Y.Z.。我整理了一下2024年初比较稳的组合参考Android Studio版本AGP版本Gradle版本备注Hedgehog 2023.1.18.2.x8.2项目实测稳定Giraffe 2022.3.18.1.x8.0常见组合Koala 2024.1.18.5.x8.7新版本组合对照表的查看方法很简单Android Studio菜单栏 Help - About先确认AS版本然后看项目里gradle-wrapper.properties里的distributionUrl确认Gradle版本最后看根目录build.gradle.kts里声明的AGP版本。三者必须落在Google官方兼容表的范围内最怕的就是你用了最新的AS但项目里的Gradle还停留在老版本那个报错信息还特别容易让人误判成依赖冲突。4.3 Room的编译期报错怎么读Room的一大特性是在编译期做SQL合法性检查。它的报错信息比运行时崩溃友好很多但新手刚开始看不太懂。最常见的报错是Entities and POJOs must have a usable public constructor这个意思是你的实体类要么是data class要么必须提供无参构造函数。还有一种是The query returns some columns which are not used by这是SQL查询返回的字段和实体类字段对不上比如你只select了name但实体类里还有phoneRoom就会警告你。我踩过一次很隐蔽的坑修改了Contact实体类给一个字段改了名但DAO里的SQL语句还写着旧字段名。编译直接报错no such column排查了半天才意识到是字段重命名忘了同步SQL。所以我的习惯是实体类字段名保持和数据库列名一致如果非要用ColumnInfo(name xxx)做映射那改字段名的时候一定全局搜索一遍所有SQL语句。Room虽然有编译期检查但它只能检查出列不存在检查不出你逻辑上用错了字段。4.4 权限回调不触发点击事件没反应权限回调不触发的情况多半是因为你把registerForActivityResult写在了一个函数里而不是直接写在Activity类的属性声明位置。这个API有一个限制register的调用必须在Activity创建之初完成也就是lifecycle的STARTED状态之前。如果你在按钮点击之后才调用register它虽然不报错但回调永远不执行。这是ActivityResult API和旧的onRequestPermissionsResult最大的区别我见过不少人从旧代码迁移过来后在这个问题上卡了好几天。还有一个在权限被拒绝后点击按钮没反应的情况。第一次拒绝后你还能再次申请但勾选了“不再询问”之后再次launch就相当于直接返回拒绝回调不会弹系统对话框。这时必须跳转设置页代码是Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.parse(package:$packageName))。这里有个细节从设置页返回App后应该在onResume里重新检测一次权限状态而不是靠回调因为从设置页回来的结果不会触发PermissionResult回调。5. 非功能性优化与后续扩展方向5.1 App启动速度和列表滑动优化通讯录功能本身简单但简单的东西要做到流畅反而更考验基本功。我第一次写完列表后在低端测试机上滑动时肉眼可见地掉帧用Android Studio自带的Profiler一查发现问题出在onBindViewHolder里做了一次文件读取操作——加载联系人头像时直接从磁盘读了Bitmap。解决办法就是加了一层内存缓存用LruCache把头像Bitmap缓存起来滑动时缓存命中直接显示只有未命中才去读磁盘。同样的思路也可以用Glide或Coil来处理头像加载。Coil是Kotlin写的扩展函数风格很简洁一行代码搞定头像加载和缓存。如果不想引入第三方库就用我上面说的LruCache几十行代码写一个简单的缓存工具类对通讯录这种头像文件不大的场景也够用。还有一个很容易被忽略的点数据库查询的触发频率。通讯录App的列表页每次从后台切回来都会重新查询一次数据库如果数据量大这个开销不可忽视。我的优化方案是给列表页的ViewModel加一个SavedStateHandle只做一次全量查询后续靠Room的LiveData自动更新避免从后台回来时重复查询。实测下来从几百毫秒的加载降到几十毫秒。5.2 扩展方向从通讯录到完整通讯管理工具通讯录做到这个程度已经是一个能正常使用的App了。如果你还想继续往下深入我有几个方向可以给参考。一个是批量导入导出导入系统联系人时把AVAILABLE标签也迁移过来导出到vCard格式文件共享给别人。这个功能需要处理权限和文件格式实用性很强。另一个是联系人分组比如“家人”“同事”“朋友”这需要在数据库里加一个group_id字段然后列表页做分组展示正好可以练一练ConcatAdapter或者ListAdapter里多布局的用法。语音搜索也是现在通讯录App的标配功能之一用的SpeechRecognizer接口适配不同厂商ROM的时候要注意测试一下有的ROM对语音权限控制得比较严格。还有一个方向是做联系人去重按电话号码分组聚合通过GROUP BY phone HAVING COUNT(*) 1找出重复项这个SQL写一次就很有成就感。5.3 用Profiler定位性能问题的实战思路最后再分享一个排查问题的思路。Android Studio的Profiler工具其实没有那么高不可攀关键是要知道怎么看数据。打开Profiler的Memory面板操作App让列表反复滚动观察内存曲线的走势。正常情况是曲线稳定在一个区间内起伏如果看到阶梯式上升并且不回降八成是内存泄漏。结合LeakCanary库它会直接告诉你泄漏对象是哪个Activity、哪一行代码创建的。CPU面板可以看方法耗时我定位列表卡顿问题的时候就是用CPU Profiler录制了一段滚动操作发现BitmapFactory.decodeFile占了40%的时间。优化之后再看一下CPU曲线明显下了一个台阶。这种“先量化、再优化、再验证”的思路比凭感觉猜哪里慢要高效得多。我个人的体会是通讯录这个项目虽然小但正因为小你有精力去关注每个细节的实现质量。把它做到流畅、稳定、没有内存泄漏你对Android开发的理解会上一个台阶。这些经验迁移到任何大型项目里都是通用的底层能力。本文还有配套的精品资源点击获取 
长河君 · 2026/9/1 3:14:40 · 阅读 1.2k Android通讯录开发实战：Room+RecyclerView+ViewModel架构与踩坑指南
简介这套安卓通讯录开发源码专为初学安卓的开发者设计用 Java 实现了账号登录、注册以及通讯录联系人的添加、修改、删除、查询等完整功能既适合课堂练习也可作为课程设计或毕业设计的参考原型。资源包共含 1034 个文件以 XML 布局与配置、PNG 图标、JSON 数据、Java 源码和构建生成的 class、jar 文件为主并附带了可手机直接安装的 APK整体大小约 5.67MB目录结构清晰便于按需查看与二次开发。项目将登录注册与联系人管理串联成完整流程涉及 Activity 跳转、事件监听、数据存储和列表展示等核心知识点同时保留了构建脚本、调试信息与打包产物初学者可对照源码理解从界面设计到逻辑实现的每一步也能借助构建产物验证运行效果。目前已有 5563 人浏览学习适合需要快速上手安卓项目或准备相关实训作业的开发者参考使用。1. 项目需求与整体技术选型1.1 通讯录项目到底在练什么做通讯录开发是我带新人时最喜欢安排的一个实战项目。原因很简单它麻雀虽小五脏俱全把Android开发的核心知识点几乎全部串起来了。你看着就是一个联系人增删改查实际上背后涉及界面布局、列表复用、本地数据库、运行时权限、生命周期管理、数据绑定每一项都是日常开发里躲不开的东西。拿Android Studio来说从创建项目那一刻开始你就要面对Gradle版本、SDK版本、依赖库选型这一堆选择。很多新手在这里就被绕晕了项目还没写几行代码先花了一下午配环境。我见过不少同事和朋友卡在依赖下载慢、Gradle同步失败、AGP和Gradle版本不匹配这些问题上最后连Hello World都没跑起来。所以这次写这个项目我会先从工程搭建讲起把版本选型和依赖配置的坑一起填掉。这个项目适合谁来参考如果你已经能跑通一个空白的Android项目但对Room数据库、RecyclerView、ViewModel这一套组合还不熟那这篇实战记录能帮你把整条链路理清。如果你还在纠结“通讯录到底该用什么架构”那我把自己的选型思路和踩坑过程完整讲一遍你至少能少走几周弯路。1.2 技术栈选型为什么是Room RecyclerView ViewModel通讯录项目的核心诉求很简单存联系人、读联系人、改联系人、删联系人外加一个列表展示和搜索。技术选型我首推四件套Kotlin Room RecyclerView ViewModel/LiveData。这套组合可以说是Google官方推荐的标准姿势社区资料最多遇到问题基本都能搜到答案。数据库这块SQLite当然也能写但你得手动处理大量的模板代码定义表结构、写增删改查语句、管理数据库连接、处理游标关闭。Room的本质是在SQLite上面包了一层编译期帮你校验SQL语句是否正确运行期用DAO接口直接操作对象。对通讯录这种实体关系比较简单的项目来说Room能把数据层代码量砍掉一半以上。而且Room天生支持LiveData返回查询结果数据库一变化UI立刻自动刷新这正好解决通讯录列表“加了联系人马上能看到”这个核心体验。列表展示用RecyclerView适配器里配合ListAdapter DiffUtil做差量更新。用过ListView的朋友应该有体会数据一变就得notifyDataSetChanged整个列表全刷又卡又浪费。DiffUtil能精准算出哪一行变了、哪一行新增了只刷新有变化的部分性能表现完全不在一个级别。界面架构上用ViewModel来持有联系人数据配合LiveData实现数据和UI分离。这样旋转屏幕时数据不丢Activity只负责观察数据、渲染界面逻辑清晰后续加需求也好加。Kotlin协程用来做数据库的异步操作避免在主线程读写数据库导致卡顿。2. 数据库设计与业务逻辑拆解2.1 联系人表怎么设计才够用通讯录的数据模型看起来简单但设计的时候还是有几个细节需要注意。基础字段无非是姓名、电话、邮箱、头像、备注这些。但我建议从第一天起就加上创建时间和更新时间这两个字段别问我为什么——等你要做排序、做“最近添加”功能、或者排查数据异常的时候就会感谢我。主键这里有个讲究。联系人这种数据适合用自增Long作为主键因为电话号码不适合当主键一个人可能有好几个号码同一个号码也可能被家人共用比如家庭固话。如果直接用号码当唯一标识后面会给自己埋坑。Room支持PrimaryKey(autoGenerate true)让数据库自己分配ID这是最稳妥的方案。姓名索引要不要加看数据量。通讯录几百条联系人不加索引全表扫描也就几毫秒但如果后面要做到几千上万条搜索就会明显变慢。我习惯在姓名列上加一个索引成本极低收益长期存在。Room里加索引很省事直接在Entity注解里写indices就行。Entity( tableName contacts, indices [Index(value [name])] ) data class Contact( PrimaryKey(autoGenerate true) val id: Long 0, val name: String, val phone: String, val email: String , val avatarUri: String? null, val note: String , val createdAt: Long System.currentTimeMillis(), val updatedAt: Long System.currentTimeMillis() )2.2 Room的接入配置和Gradle依赖在Android Studio里接Room第一个要面对的就是Gradle依赖版本问题。这里我把2024年这个节点上稳定可用的版本组合写出来。我用的Android Studio版本是Hedgehog2023.1.1 Patch 2AGP版本8.2.2Gradle 8.2Kotlin 1.9.22Room 2.6.1。这个组合实测下来兼容性很好没有遇到KAPT和KSP的兼容冲突。Room 2.6.1默认开始推荐用KSP替代KAPT来做注解处理。KSP比KAPT快很多编译一次能省下几十秒。你需要在项目根目录的build.gradle.kts里声明KSP插件版本然后在模块级里应用。plugins { id(com.google.devtools.ksp) version 1.9.22-1.0.17 apply false }模块级的依赖配置plugins { id(com.android.application) id(org.jetbrains.kotlin.android) id(com.google.devtools.ksp) } dependencies { implementation(androidx.room:room-runtime:2.6.1) implementation(androidx.room:room-ktx:2.6.1) ksp(androidx.room:room-compiler:2.6.1) implementation(androidx.lifecycle:lifecycle-viewmodel-ktx:2.7.0) implementation(androidx.lifecycle:lifecycle-livedata-ktx:2.7.0) }还有一点需要特别注意KSP版本必须跟Kotlin版本严格匹配。我见过很多人报错ksp version mismatch就是因为换了Kotlin版本但忘了同步升级KSP插件。这个对应关系在KSP的GitHub仓库里有一张表每次升级Kotlin之前先查一下。2.3 DAO层的编写思路与常见坑DAO是Room的核心操作入口它的接口定义直接决定了你后续业务代码好不好写。通讯录的常规操作就四类查询全部、按ID查询、插入、更新、删除。我建议再额外加两个方法按关键字搜索和统计总数。查询全部的时候我直接用LiveData作为返回类型。这样数据库里数据一变LiveData会自动收到通知列表自动刷新完全不需要手动重新查询。这在通讯录场景下特别实用因为你新增、修改、删除联系人之后列表必须同步变化LiveData把这些同步逻辑全部省掉了。搜索接口我用的方式是WHERE name LIKE % || :keyword || %虽然在大数据量下不走索引但通讯录这个量级完全够用。如果以后数据量上去了可以考虑用FTS4全文搜索那是另外一套玩法。Dao interface ContactDao { Query(SELECT * FROM contacts ORDER BY createdAt DESC) fun getAllContacts(): LiveDataListContact Query(SELECT * FROM contacts WHERE id :id) suspend fun getContactById(id: Long): Contact? Query(SELECT * FROM contacts WHERE name LIKE % || :keyword || % ORDER BY name ASC) fun searchContacts(keyword: String): LiveDataListContact Insert suspend fun insert(contact: Contact): Long Update suspend fun update(contact: Contact) Delete suspend fun delete(contact: Contact) }这里有一个FileNotFoundException的经典坑想提醒一下。很多人第一次写Room插入操作时直接在主线程调用DAO方法结果崩溃日志里报AndroidRuntimeException: Cannot access database on the main thread。Room默认不允许在主线程跑数据库操作我这套代码里DAO方法全部用了suspend关键字配合协程在IO线程执行这个坑就不会踩到。如果你用的Room版本比较老不支持协程那就得手动用executor.execute()包一层麻烦很多。3. 核心实现界面搭建与权限处理3.1 动态权限申请这一步绕不开通讯录App有个特殊的地方它不是读取系统通讯录而是自己管理一批联系人所以严格来说不需要申请READ_CONTACTS权限。但如果你的需求是“从系统通讯录导入联系人”那就必须处理运行时权限。我建议一开始就把权限这块做对不然后面加导入功能的时候又要返工。Android 6.0API 23之后危险权限必须在运行时动态申请。Manifest.permission.READ_CONTACTS就属于危险权限。写权限同理如果你要支持“导出联系人到本地文件”WRITE_EXTERNAL_STORAGE在Android 10以后用MediaStore那一套Android 13以后又加了READ_MEDIA_VIDEO这些细分权限这块每个版本都有差异执行时一点要查清楚当前targetSdkVersion对应的规则。下面是我用的动态权限申请模板基于registerForActivityResult这套API这是目前最推荐的写法private val requestPermissionLauncher registerForActivityResult( ActivityResultContracts.RequestPermission() ) { granted - if (granted) { importFromSystemContacts() } else { Toast.makeText(this, 需要通讯录权限才能导入联系人, Toast.LENGTH_SHORT).show() } } private fun checkAndRequestPermission() { val permission Manifest.permission.READ_CONTACTS if (ContextCompat.checkSelfPermission(this, permission) PackageManager.PERMISSION_GRANTED) { importFromSystemContacts() } else { requestPermissionLauncher.launch(permission) } }这套写法要注意一点如果用户拒绝了权限你再次调用launch()的时候系统不会再弹出授权框而是直接回调granted false。所以严谨一点应该用shouldShowRequestPermissionRationale()判断用户是否点了“不再询问”引导用户去设置页手动开启。我在第四章节会专门讲这个问题的排查方法。3.2 RecyclerView列表与ListAdapter实现列表界面我用了RecyclerView ListAdapter的组合。ListAdapter和普通Adapter最大的区别是它内置了AsyncListDiffer在后台线程计算新旧列表的差异然后精准刷新。通讯录列表这种频繁增删改的场景这个特性太关键了。DiffUtil的回调需要你告诉它“什么时候两个item代表同一个人”以及“什么时候item内容变了”class ContactDiffCallback : DiffUtil.ItemCallbackContact() { override fun areItemsTheSame(oldItem: Contact, newItem: Contact): Boolean { return oldItem.id newItem.id } override fun areContentsTheSame(oldItem: Contact, newItem: Contact): Boolean { return oldItem newItem } }这里有个细节areContentsTheSame我直接用了data class的equals比较。如果你之后在Contact里加了Bitmap这种不适合放在equals里的字段就得手动逐字段比较了。所以Contact里我存的是avatarUri字符串而不是Bitmap这也是一个经验——数据库和实体类里永远不要直接放Bitmap这类重量级对象存路径或者URI才是正确姿势。ViewHolder的绑定逻辑也很直白两个Textview一个显示姓名一个显示电话号码class ContactViewHolder(private val binding: ItemContactBinding) : RecyclerView.ViewHolder(binding.root) { fun bind(contact: Contact) { binding.tvName.text contact.name binding.tvPhone.text contact.phone } }Adapter继承ListAdapter之后对外只需要一个submitList()方法。更新数据的逻辑全在ViewModel里做数据一变化LiveData回调触发再调用adapter.submitList(newList)剩下的事交给DiffUtil。3.3 新增和编辑联系人界面一个Activity怎么复用增和改在很多代码示例里是分开写的一个AddActivity一个EditActivity。但实际开发中这两个界面往往长得一模一样差别只是有没有预填数据。我建议用一个EditContactActivity通过Intent传一个contactId参数。ID为-1表示新增ID大于0表示编辑用同一个布局和同一套保存逻辑代码能省一半。布局文件里就是几个TextInputLayoutTextInputEditText分别放姓名、电话、邮箱、备注。电子邮箱不是必填项但校验逻辑不能省。电话号码这块也有讲究最好是限制输入类型为phone并且不要限制长度——因为有些国家区号加电话号码能到十几位硬限制11位会让用户输不进去。这个坑我实际遇到过用户从国外回来发现号码存不进去反馈了一整页。保存按钮的点击逻辑大概是这样的private fun saveContact() { val name binding.etName.text?.toString()?.trim().orEmpty() val phone binding.etPhone.text?.toString()?.trim().orEmpty() if (name.isEmpty()) { binding.etName.error 姓名不能为空 return } if (phone.isEmpty()) { binding.etPhone.error 电话号码不能为空 return } val contact if (contactId 0) { Contact(id contactId, name name, phone phone, ...) } else { Contact(name name, phone phone, ...) } viewModel.saveContact(contact) }DAO层的Insert和Update方法是分开的但Room里还有一个隐藏技巧Upsert注解可以自动判断数据存在就更新、不存在就插入。如果你用的是Room 2.5.0以上版本直接定义Upsert suspend fun upsert(contact: Contact)新增和编辑就能共用同一个方法业务代码又简化一层。这就是我推荐在选型时尽量用最新稳定版的原因——很多好用的语法糖都是新版才有的。4. 踩坑实录常见问题与定位思路4.1 Gradle同步慢、依赖下载失败这个坑几乎人人都会遇到而且它跟你的代码质量没有半点关系纯粹是环境问题。国内外网速差异导致Maven仓库下载很慢尤其Google的仓库一个包几百兆卡上半小时很正常。解决思路有两个一是配置镜像仓库把google()和mavenCentral()替换成国内可访问的镜像地址比如阿里云的镜像二是用Gradle提供的离线模式把依赖缓存好之后断网编译。我自己常用的做法是配置镜像仓库地址repositories { maven { url uri(https://maven.aliyun.com/repository/public) } maven { url uri(https://maven.aliyun.com/repository/google) } maven { url uri(https://maven.aliyun.com/repository/gradle-plugin) } mavenCentral() }配置好之后建议把Gradle的distributionUrl也切换成国内镜像加速下载那段URL在项目根目录的gradle/wrapper/gradle-wrapper.properties里。Android Studio自己的镜像地址在File - Settings - Appearance Behavior - System Settings - HTTP Proxy里也能设置。4.2 AGP版本和Gradle版本不匹配这个报错信息非常经典The Android Gradle plugin requires Gradle X.Y.Z. Current version is X.Y.Z.。我整理了一下2024年初比较稳的组合参考Android Studio版本AGP版本Gradle版本备注Hedgehog 2023.1.18.2.x8.2项目实测稳定Giraffe 2022.3.18.1.x8.0常见组合Koala 2024.1.18.5.x8.7新版本组合对照表的查看方法很简单Android Studio菜单栏 Help - About先确认AS版本然后看项目里gradle-wrapper.properties里的distributionUrl确认Gradle版本最后看根目录build.gradle.kts里声明的AGP版本。三者必须落在Google官方兼容表的范围内最怕的就是你用了最新的AS但项目里的Gradle还停留在老版本那个报错信息还特别容易让人误判成依赖冲突。4.3 Room的编译期报错怎么读Room的一大特性是在编译期做SQL合法性检查。它的报错信息比运行时崩溃友好很多但新手刚开始看不太懂。最常见的报错是Entities and POJOs must have a usable public constructor这个意思是你的实体类要么是data class要么必须提供无参构造函数。还有一种是The query returns some columns which are not used by这是SQL查询返回的字段和实体类字段对不上比如你只select了name但实体类里还有phoneRoom就会警告你。我踩过一次很隐蔽的坑修改了Contact实体类给一个字段改了名但DAO里的SQL语句还写着旧字段名。编译直接报错no such column排查了半天才意识到是字段重命名忘了同步SQL。所以我的习惯是实体类字段名保持和数据库列名一致如果非要用ColumnInfo(name xxx)做映射那改字段名的时候一定全局搜索一遍所有SQL语句。Room虽然有编译期检查但它只能检查出列不存在检查不出你逻辑上用错了字段。4.4 权限回调不触发点击事件没反应权限回调不触发的情况多半是因为你把registerForActivityResult写在了一个函数里而不是直接写在Activity类的属性声明位置。这个API有一个限制register的调用必须在Activity创建之初完成也就是lifecycle的STARTED状态之前。如果你在按钮点击之后才调用register它虽然不报错但回调永远不执行。这是ActivityResult API和旧的onRequestPermissionsResult最大的区别我见过不少人从旧代码迁移过来后在这个问题上卡了好几天。还有一个在权限被拒绝后点击按钮没反应的情况。第一次拒绝后你还能再次申请但勾选了“不再询问”之后再次launch就相当于直接返回拒绝回调不会弹系统对话框。这时必须跳转设置页代码是Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, Uri.parse(package:$packageName))。这里有个细节从设置页返回App后应该在onResume里重新检测一次权限状态而不是靠回调因为从设置页回来的结果不会触发PermissionResult回调。5. 非功能性优化与后续扩展方向5.1 App启动速度和列表滑动优化通讯录功能本身简单但简单的东西要做到流畅反而更考验基本功。我第一次写完列表后在低端测试机上滑动时肉眼可见地掉帧用Android Studio自带的Profiler一查发现问题出在onBindViewHolder里做了一次文件读取操作——加载联系人头像时直接从磁盘读了Bitmap。解决办法就是加了一层内存缓存用LruCache把头像Bitmap缓存起来滑动时缓存命中直接显示只有未命中才去读磁盘。同样的思路也可以用Glide或Coil来处理头像加载。Coil是Kotlin写的扩展函数风格很简洁一行代码搞定头像加载和缓存。如果不想引入第三方库就用我上面说的LruCache几十行代码写一个简单的缓存工具类对通讯录这种头像文件不大的场景也够用。还有一个很容易被忽略的点数据库查询的触发频率。通讯录App的列表页每次从后台切回来都会重新查询一次数据库如果数据量大这个开销不可忽视。我的优化方案是给列表页的ViewModel加一个SavedStateHandle只做一次全量查询后续靠Room的LiveData自动更新避免从后台回来时重复查询。实测下来从几百毫秒的加载降到几十毫秒。5.2 扩展方向从通讯录到完整通讯管理工具通讯录做到这个程度已经是一个能正常使用的App了。如果你还想继续往下深入我有几个方向可以给参考。一个是批量导入导出导入系统联系人时把AVAILABLE标签也迁移过来导出到vCard格式文件共享给别人。这个功能需要处理权限和文件格式实用性很强。另一个是联系人分组比如“家人”“同事”“朋友”这需要在数据库里加一个group_id字段然后列表页做分组展示正好可以练一练ConcatAdapter或者ListAdapter里多布局的用法。语音搜索也是现在通讯录App的标配功能之一用的SpeechRecognizer接口适配不同厂商ROM的时候要注意测试一下有的ROM对语音权限控制得比较严格。还有一个方向是做联系人去重按电话号码分组聚合通过GROUP BY phone HAVING COUNT(*) 1找出重复项这个SQL写一次就很有成就感。5.3 用Profiler定位性能问题的实战思路最后再分享一个排查问题的思路。Android Studio的Profiler工具其实没有那么高不可攀关键是要知道怎么看数据。打开Profiler的Memory面板操作App让列表反复滚动观察内存曲线的走势。正常情况是曲线稳定在一个区间内起伏如果看到阶梯式上升并且不回降八成是内存泄漏。结合LeakCanary库它会直接告诉你泄漏对象是哪个Activity、哪一行代码创建的。CPU面板可以看方法耗时我定位列表卡顿问题的时候就是用CPU Profiler录制了一段滚动操作发现BitmapFactory.decodeFile占了40%的时间。优化之后再看一下CPU曲线明显下了一个台阶。这种“先量化、再优化、再验证”的思路比凭感觉猜哪里慢要高效得多。我个人的体会是通讯录这个项目虽然小但正因为小你有精力去关注每个细节的实现质量。把它做到流畅、稳定、没有内存泄漏你对Android开发的理解会上一个台阶。这些经验迁移到任何大型项目里都是通用的底层能力。本文还有配套的精品资源点击获取