Android笔记APP开发实战：Kotlin+SQLite教程

1. 项目整体设计与思路拆解1.1 这个笔记APP到底要做到什么程度先说结论用Android Studio写一个笔记APP是新手入门移动开发最好的练手项目但前提是你得知道自己在做什么。很多教程一上来就教你搭个界面、存个字符串最后跑起来能打字就宣布“学会写APP了”这种项目做完跟没做没什么区别。我当初带过好几个从零开始的朋友做这个项目反复验证下来一个合格的笔记APP至少要包含这几个层次的能力第一层是界面能点能跳笔记列表、新建笔记、编辑笔记三个页面能顺畅切换第二层是数据能存能读你写下的内容关了APP再打开还在第三层是体验像个真正的APP比如列表能滑动、有删除和搜索、界面不卡顿、横竖屏切换数据不丢。如果这些你都能做到那这个项目才算真正“吃透”了。拿我自己来说我最早教别人写笔记APP时也犯过“只要功能能跑就行”的错。后来发现真正影响你技术提升的往往不是功能本身而是设计思路的清晰程度。比如你用的是SQLite还是MMKV你的列表是用ListView还是RecyclerView你的架构是直接在Activity里写逻辑还是简单拆一层ViewModel这些选择背后的理由比那一百行代码值钱得多。这个项目最适合两类人一类是完全没写过代码想通过一个完整项目搞清楚“一个APP是怎么从零诞生的”的新手另一类是写过一些Demo但想用项目把文件读写、UI适配、生命周期、打包上架这些散点知识串起来的人。前者能获得一条完整的学习路径后者能补上很多实操中才踩得着的地板坑。1.2 为什么选Android Studio而不是其他工具现在做一个APP可选的路其实很多原生Android、Flutter、React Native甚至是在线低代码平台。但如果你没有任何基础或者刚学完Java/Kotlin语法我强烈建议你从Android Studio原生开发入手而不是上来就跨平台。原因很简单Android Studio是官方IDE你遇到的所有报错、所有配置问题在网上几乎都能搜到答案这对新手是最大的利好。Flutter虽好但如果你连Android的项目结构、Gradle构建流程、Activity生命周期都不懂出了错你根本不知道是框架的锅还是Android环境的锅排查起来非常痛苦。再说实际一点的笔记APP核心就是“文字輸入 本地存储 列表展示”这三件事在原生Android里都有非常成熟的官方方案学习资料多、踩坑记录全你几乎不会孤立无援。等你把这个项目完整跑通再决定要不要学Flutter那时候你对整个移动开发的认识就不一样了学什么框架都很快。对了如果你在Android Studio里看到全英文界面觉得头大可以先设置中文语言包。新版Android Studio在Settings里有个“中文语言包”插件选项装上重启就有简体中文界面。不过我的建议是能用英文就尽量用英文因为编程环境里的很多术语翻译成中文反而别扭比如“Activity”你翻译成“活动”很多文档根本对不上。当然如果你实在觉得英文难受装中文包完全不影响学习自己舒服最重要。1.3 技术选型与项目结构的前期规划动手写代码之前先把技术方案定下来。我这里用一个稳妥保守的组合适合学习和确保能跑通开发语言Kotlin。现在Android Studio新建项目默认就是KotlinJava虽然也行但Kotlin的空安全特性对新手非常友好能帮你少写一堆if判空。界面构建XML布局 传统View体系不用Compose。Compose是趋势但资料相对新、概念更抽象新手期还是用XML更直观一个控件一个标签看得见摸得着。数据存储先用SharedPreferences存简单笔记标题等做到正文编辑时再用SQLite或Room。不要一开始就上Room因为你对SQL不熟的话很可能被抽象的数据库框架绕晕。顺序很重要。列表展示RecyclerView不要用ListView。RecyclerView更灵活性能更好是现在的主流而且它强制你理解Adapter和ViewHolder的机制这是Android应用开发的必考知识。项目结构上我的建议是不要搞复杂的MVVM架构但也不要全堆在一个MainActivity里。合理拆分一个MainActivity管笔记列表一个EditActivity管新建和编辑数据操作独立出一个DataManager类或者用一个简单的Repository这样逻辑清晰后面想升级成MVVM也容易。2. 核心细节解析与实操要点2.1 界面怎么搭三个页面一条主链路笔记APP的界面不需要花哨但要符合直觉。核心就是三个页面主页是列表点进去是笔记正文右下角一个加号用来新建。主页布局一个RecyclerView占满整个屏幕顶部可以放一个搜索框右上角菜单放“删除全部”之类的操作。如果你用了Material Components库可以用FloatingActionButton做加号按钮Material库自带这个控件不用自己画。新建/编辑页布局一个标题输入框一个正文输入框再加一个顶部的保存按钮。这里有一个实操重点标题用EditText的singleLine属性正文用gravitytop配合scrollbarsvertical这样用户输入长文时界面不会出现奇怪的滚动冲突。我在这个环节踩过一个坑Android的EditText默认是没有边框的很多新手放上去一片空白以为控件没生效。实际上Android的设计理念是“材质化界面”控件本身的边框要自己通过Background或TextInputLayout去定义。我的方案是使用com.google.android.material.textfield.TextInputLayout包一层它自带浮动标签效果输入内容后标签会浮起来视觉上非常清晰而且不用写一行背景代码。基础布局写完之后第二个重要细节是点击事件列表项怎么跳转到编辑页。这里建议用Intent携带笔记ID而不是直接把整个笔记对象传过去。因为对象涉及序列化新手很容易在传递大对象时触发FAILED BINDER TRANSACTION报错而传一个ID接收方再根据ID去查数据又稳又符合常规设计思路。2.2 记住这两件事数据就不会丢数据持久化是整个笔记项目里大家最容易翻车的地方。很多人把数据存在onPause或者某个按钮点击事件里一遇到进程被杀、应用切到后台数据就没了。正确的做法是理解Android的生命周期数据在什么时候必须落盘什么时候可以延迟。我的方案是编辑页的自动保存放在onPause里原因很简单只要用户离开这个页面按返回、切后台、跳转其他应用onPause一定会被调用这时候保存数据丢失概率降到了最低。而手动保存按钮只是提供一个“用户主动确认保存”的心理安全感。存储方式的选择我分两步走第一步存的单条笔记用SharedPreferences。它有KEY-VALUE结构轻量、用起来简单适合存“标题xxx内容yyy”这种结构。但它不适合存多条数据因为你需要管理数组的序列化与反序列化代码会很别扭。第二步要支持多笔记列表时用SQLite通过SQLiteOpenHelper。第一次上手数据库你会接触到CREATE TABLE、INSERT、QUERY、DELETE这些关键词。不要怕笔记APP的建表语句就几行CREATE TABLE notes ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, content TEXT, updated_at INTEGER );我明確说一句这里不要用Room做过度设计。Room是对SQLite的封装概念时髦但它要你理解注解、DAO、数据库迁移新手阶段很容易陷在框架概念里而不是业务逻辑里。先手动把SQL写明白你后面理解Room就是一句话的事Room就是帮你生成这些SQL代码的工具。2.3 列表刷新与数据更新最容易出现“改了但没生效”的地方想象一下这个场景你在列表页点开一条笔记改了内容按返回结果列表里的标题还是旧的。为什么因为你没有让列表页在重新可见时重新查询数据库。解决办法之一是在列表页的onResume里重新加载数据。onResume在每次从后台回到前台、从编辑页返回时都会调用。只要在onResume里执行“重新查数据库 - 更新数据源 - 刷新Adapter”这个问题就彻底死了。这里有个细节不要直接在onResume里无条件重新查询然后notifyDataSetChanged()。如果数据量小没问题但如果你给RecyclerView做了排序或动画无脑全量刷新会导致界面闪烁、滚动位置丢失。更好的做法是把查询结果拿出后比对数据源是否变化有变化才刷新。不过新手期不用关心这么多先保证功能正确数据量上来了再考虑性能。还有一个隐藏Bug你在编辑页删除了某条笔记返回列表页时这条笔记还在。原因是删除操作之后列表页持有的数据源还是旧数据你又只在onCreate查了一遍库。解决办法还是那条在onResume统一刷新。3. 实操过程从新建项目到跑起来3.1 环境准备和创建项目时的几个选项如果你还没装好Android Studio先去官网下载最新稳定版不要下Canary版本那个是尝鲜版新手用稳定版最省心。国内网络下载一般没问题SDK组件会自动拉取如果特别慢可以单独配置国内镜像源。新建项目的步骤是File - New - New Project选择Empty Views Activity注意不是Empty Activity那是Compose项目选项然后配置项目名、包名和保存位置。包名我强烈建议用带域名的正式写法比如com.myname.notes因为以后你发布应用、接入第三方SDK、配置签名都要用到这个包名。不要随意命名改起来极其麻烦。关于最低SDK版本我建议选API 24或者API 26。选得更低意味着兼容更多老设备但需要写更多适配代码选得过高又扔掉了较大比例的存量用户。API 26对应Android 8.0能覆盖绝大多数还在使用的设备而且对通知、存储权限的处理方式比较现代不会被系统的姿势坑到。3.2 手写核心代码列表Adapter 数据库工具类现在说代码这也是所有人最关心的部分。别怕我们一块一块来。第一步创建一个数据模型类——就是“笔记”这个东西长什么样data class Note( val id: Long, val title: String, val content: String, val updatedAt: Long )第二步创建数据库帮助类。这里用SQLite自带的方式写一个NotesDbHelperclass NotesDbHelper(context: Context) : SQLiteOpenHelper(context, notes.db, null, 1) { override fun onCreate(db: SQLiteDatabase) { db.execSQL( CREATE TABLE notes ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, content TEXT, updated_at INTEGER ) ) } override fun onUpgrade(db: SQLiteDatabase, oldVersion: Int, newVersion: Int) { db.execSQL(DROP TABLE IF EXISTS notes) onCreate(db) } }这里有个很容易踩的坑onUpgrade里的写法是“删表重建”这在开发调试阶段没问题但用户安装了你后来的升级包时他原来的数据就会被清掉。生产环境要写迁移逻辑比如ALTER TABLE新增列而不是删表。新手先把开发跑通后面发布时一定要回来改这个。第三步写一个查询所有笔记的方法fun getAllNotes(): ListNote { val list mutableListOfNote() val cursor db.query(notes, null, null, null, null, null, updated_at DESC) cursor.use { while (it.moveToNext()) { val note Note( id it.getLong(it.getColumnIndexOrThrow(id)), title it.getString(it.getColumnIndexOrThrow(title)), content it.getString(it.getColumnIndexOrThrow(content)), updatedAt it.getLong(it.getColumnIndexOrThrow(updated_at)) ) list.add(note) } } return list }注意cursor必须用use块或者finally关闭否则长时间操作会“内存泄漏”被ICS警告——这是很常见又很基础的问题。getColumnIndexOrThrow也比getColumnIndex好因为列不存在时直接抛出异常方便你在写错表名或列名时第一时间发现。第四步写Adapter。这个类理解起来需要一点耐心但它就是“把数据变成列表界面”的翻译官class NotesAdapter(private val notes: ListNote) : RecyclerView.AdapterNotesAdapter.ViewHolder() { class ViewHolder(val binding: ItemNoteBinding) : RecyclerView.ViewHolder(binding.root) override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): ViewHolder { val binding ItemNoteBinding.inflate(LayoutInflater.from(parent.context), parent, false) return ViewHolder(binding) } override fun onBindViewHolder(holder: ViewHolder, position: Int) { val note notes[position] holder.binding.tvTitle.text note.title holder.binding.tvContent.text note.content holder.itemView.setOnClickListener { val intent Intent(holder.itemView.context, EditActivity::class.java) intent.putExtra(note_id, note.id) holder.itemView.context.startActivity(intent) } } override fun getItemCount() notes.size }别被名字吓住逻辑就是一个萝卜一个坑onCreateViewHolder创建“坑”onBindViewHolder把“萝卜”数据填进去。列表滚动时RecyclerView只关心“你看到的这几个坑”这个机制就是RecyclerView高效的核心。3.3 编辑页的保存逻辑与返回刷新闭环编辑页最重要的动作是“进入时加载旧数据退出时保存新数据”。override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) binding ActivityEditBinding.inflate(layoutInflater) setContentView(binding.root) noteId intent.getLongExtra(note_id, -1) if (noteId ! -1L) { // 编辑已有笔记加载数据 val note dbHelper.getNoteById(noteId) binding.etTitle.setText(note.title) binding.etContent.setText(note.content) } } override fun onPause() { super.onPause() val title binding.etTitle.text.toString() val content binding.etContent.text.toString() if (title.isNotEmpty() || content.isNotEmpty()) { if (noteId -1L) { dbHelper.insertNote(title, content) } else { dbHelper.updateNote(noteId, title, content) } } }这套逻辑的关键在onPause用户无论点返回、跳系统设置、还是切到其他应用都会走到这一步并保存数据。不需要手动触发保存按钮的操作实现了“随写随存”的体验。返回列表页后列表页的onResume会重新刷新。这是闭环的最后一环前面的章节已提过。写到这里你完成了一个笔记APP的80%剩下的就是各种打磨。3.4 打包APK从Debug到Release的完整流程写完代码想装到自己手机上不能直接插个数据线就完事你需要打包。Android Studio中Build菜单下有Build APK(s)和Generate Signed Bundle / APK两个选项前者生成的Debug包只能自己调试用后者才是可以给别人安装、上架的“签名包”。Android要求所有安装包必须签名就像快递要有发件人盖章一样。Debug包用的是开发者的签名书设备也默认信任Release包则需要你自己创建一个签名证书。在Generate Signed Bundle / APK向导里选择Create new...填几个名字和密码这个证书要务必保存好因为你的应用一旦以这个证书发布下次更新必须用同一个证书签名。还有一个隐藏大坑打包完的APK体积如果超过10MB其实不用太担心。笔记APP核心代码加依赖库通常在3到6MB之间如果你发现APK非常大多半是把无用的so库或大图片资源打包进去了。可以使用Build - Analyze APK看看是什么占空间不要盲目加混淆配置。如果你想发布到应用商店先别急着花钱。国内常见的应用市场比如几个手机厂商的应用商店都有免费的个人开发者注册通道但要求提供身份认证和App隐私说明。先把自己的APP在模拟器上跑稳定再到真机上测试然后才上传审核。审核被拒最常见的两个理由是不给用户隐私政策和软件功能与描述不符。4. 常见问题与排查技巧实录4.1 从报错信息里快速定位问题新手上路报错是家常便饭。我帮你把最常见的几种情况总结成了一张速查表直接照着排查就行报错现象可能原因解决办法Finished with non-zero exit value 2构建脚本配置冲突或依赖下载失败清Gradle缓存Build - Clean Project再Sync ProjectUnable to resolve dependency网络问题导致依赖拉不下来检查网络代理设置换用国内镜像源阿里云镜像AAPT: error: resource string/xxx not found在代码里引用了不存在的字符串资源确认res/values/strings.xml里是否有对应条目注意大小写ClassNotFoundException包名或类名不一致或开启了混淆但配置不对检查AndroidManifest.xml里的Activity路径看proguard-rules.pro是否缺keep规则点击列表项没有反应不崩溃没给itemView设置点击事件在onBindViewHolder里加holder.itemView.setOnClickListener并检查该View是否被其他控件局部覆盖遇到报错我给你的建议是先读第一行和最后一个Cause by中间的长日志大多是堆栈辅助信息。看到Caused by后面的异常类型基本就能定位问题。不要急着复制整个日志去百度很多时候你自己读一遍就能发现低级错误。4.2 断点和日志新手必学的调试三板斧调试中最推荐的组合是Log断点。Log.d这行代码很适合新手快速观察数据比如Log.d(NoteDebug, 点击了笔记$noteId)然后打开Logcat窗口过滤NoteDebug标签就能看到自己的输入输出。但如果你想搞清“为什么这个变量是null”“为什么这段代码没被执行”光看日志不够建议用断点。在代码行左侧点一下生成红点运行到那里就会暂停这时你可以在调试窗口看到所有变量的当前值。新手用断点最大的好处是可以单步执行一行一行看数据怎么变这个理解过程胜过看十篇教程。我当时带的一个学生写了一个列表永远只显示一条笔记。他搞了很久没找到原因。我让他直接断点到getAllNotes的返回值一执行发现查出来的列表本来就只有一条数据——问题出在插入数据时insertNote每次都覆盖了同一条ID。断点一查就破案非常典型的案例。4.3 模拟器与真机我推荐直接上真机调试很多人图省事用Android Studio自带模拟器跑项目体验一阵子就不想用了。我坦诚告诉你模拟器启动慢、吃内存、触摸手感差很多传感器也没有做什么都别扭。如果你手边有一台安卓手机强烈建议直接用真机调试。开启真机调试的方法在手机“设置 - 关于手机”里连点7次“版本号”打开“开发者选项”在里面打开“USB调试”再用数据线连电脑手机上弹窗点允许。如果连接后Android Studio不认识设备多半是没装驱动或者USB模式不对换成“传输文件”模式再来。真机调试还有个好处跑起来卡不卡、布局有没有被刘海屏遮挡、按键有没有误触这些问题模拟器上是看不出来的。笔记类APP虽然简单但真机体验和模拟器差异非常大比如软键盘弹起时布局会不会被顶上去这个问题只有真机才表现得真实。我的经验是Android Studio里给AndroidManifest的Activity加上android:windowSoftInputModeadjustResize大多数键盘遮挡问题都能解决。5. 几个值得一做的进阶打磨5.1 搜索、排序与UI细节让APP更像成品笔记APP的基础功能做完后想让它更像一个“正式的东西”有几个性价比很高的改进方向。首先是搜索。你可以在主页顶部加一个SearchView或普通的EditText在用户输入时监听文本变化然后重新查询数据库用一个WHERE title LIKE %关键词% OR content LIKE %关键词%过滤数据。别管性能笔记APP的量级根本不会卡但搜索功能有了整个产品的完整度立刻不一样。其次是排序。默认按updated_at DESC也就是最近修改的在前这是对的。但你还可以加一个“只显示有内容的笔记”或“按标题字母排序”的切换代码就是在getAllNotes里改一个ORDER BY参数。用Spinner或Material的Chip去切换UI会很现代。然后是UI细节列表项的间距itemDecoration加padding、点击时的水波纹效果ripple、空数据时的“暂无笔记”提示页。这些零碎内容加起来是“能跑”和“能用”的分水岭。很多人觉得这些是美工的活真不是一个认真做产品的人自己就会把这些细节抠到位。5.2 主题切换与图标“换个配色”比想象中简单Android的深浅色模式适配如果你用Material Components库非常简单定义主题时用Theme.Material3.DayNight.NoActionBar系统切深色模式时你的APP自动切换不用写任何代码。如果你想做“白天/夜间”手动切换用一个AppCompatDelegate.setDefaultNightMode()就够了。图标也值得讲一句。新手很容易忽略图标生成随便放几张图到mipmap文件夹结果安装后图标糊成一团。我建议用Android Studio自带工具右键res文件夹New - Image Asset它会引导你生成所有尺寸的图标mdpi、hdpi、xhdpi、xxhdpi、xxxhdpi一次搞定。上传一张512x512的方形图工具会帮你裁出圆角、加适配间距。5.3 数据备份与导出从“笔记”到“生产力工具”的关键一步最后说一个提升技术含量和实用价值的事数据不能永久锁在应用里用户得多想把自己的笔记导出。两个轻量实现一种是“导出为文本文件”把笔记列表拼成纯文本用MediaStore写到一个公共下载目录再用系统分享功能传出去另一种是做“分享单条笔记”直接调Intent.createChooser把标题和内容拼成一段文字发给微信或邮件。都不用第三方SDK两个方法加起来不到100行代码。我做这个功能的时候发现了一个值得记下的坑Android 10以上直接往公共目录写文件不能再用Environment.getExternalStorageDirectory()加FileOutputStream的老套路会报权限异常。正确做法是用MediaStore.Downloads的ContentResolver接口。确实是多了一步但对用户来说笔记能导出价值和信任感完全不一样了。6. 写在最后的一点经验如果你问我在整个手把手写笔记APP的过程中最想分享给别人的是什么我会说是“渐进式构建”的心态。不要一开始就想着做出一个类似成熟笔记产品那样又好看又流畅的APP那是两三周之后的目标第一周先做出能记录、能列表展示、能删除的版本哪怕界面朴素、操作不顺手只要数据不丢骨架就是健康的。在此基础上再一个功能一个功能加每加一个功能都确保不破坏原有功能你的信心和技术栈都会非常扎实。另外开发笔记APP这种小型应用的过程真正锻炼人的不是某个API的用法而是“把一个想法拆成界面、数据、交互三块再把三块拼起来”的能力。这种拆解能力比你会背一百个API都重要。最后分享一个小技巧写代码的过程中每次都在MainActivity里随手留一个TODO注释比如“TODO: 支持笔记置顶”。这个小习惯能帮你持续保持对项目的掌控感也让你清楚地看到自己离“完整产品”还差几步。项目不怕小怕的是你写了两周代码问你“你现在做到哪一步了”自己都说不清楚。