实例习惯打卡日历Habit Check-in技术日期范围查询、连续天数统计、双表设计一、业务需求分析打卡应用的五个核心诉求打卡类应用习惯养成、健身记录、学习打卡在市场上经久不衰其数据模型也高度一致。把需求拆解开来我们得到五个核心诉求创建习惯用户新建一个习惯包含名称晨跑、图标、主题色、每月目标天数每日打卡 / 取消打卡今天做了就点一下做错了要能取消——注意「取消」也是需求因为手滑打卡很常见月历热力图本月哪些天打了卡用日历网格可视化展示一眼看到自律程度连续打卡天数统计「已连续坚持 15 天」是打卡应用最核心的激励文案必须算得准确习惯列表 各自进度多个习惯并行展示每个习惯有自己的进度条。这五个需求里2、3、4 都围绕一个核心概念——「某习惯 × 某一天」的打卡记录。这决定了数据模型必须是一对多的双表结构一张习惯表存元数据一张打卡表存每天的行为记录。二、双表字段设计习惯表与打卡表习惯表 habit字段名类型约束说明idINTEGERPRIMARY KEY AUTOINCREMENT自增主键nameTEXTNOT NULL习惯名称晨跑/阅读…iconTEXTDEFAULT ‘’图标 emojicolorTEXTDEFAULT ‘#6366F1’主题色 HEXtargetINTEGERDEFAULT 30每月目标天数created_timeINTEGERNOT NULL创建时间戳打卡记录表 habit_check字段名类型约束说明idINTEGERPRIMARY KEY AUTOINCREMENT自增主键habit_idINTEGERNOT NULL关联习惯逻辑外键dateTEXTNOT NULL打卡日期YYYY-MM-DDcheck_timeINTEGERNOT NULL打卡时间戳毫秒设计要点逐条拆解1.checkin.date用 TEXT 存YYYY-MM-DD。这是与前面实例时间戳 INTEGER最关键的不同。为什么日历场景用字符串日期三个理由可读性‘2025-06-15’ 一眼看懂调试友好有序性字符串日期按字典序排列 按时间序排列ORDER BY date天然正确无需转换区间比较BETWEEN 2025-06-01 AND 2025-06-30直接可用字符串比较在定长格式下等价于时间比较。2.habit_id date联合唯一约束。一个习惯一天最多打一次卡这个业务规则必须由数据库强制保证而不是靠前端判断。落地版用唯一索引实现CREATEUNIQUEINDEXIFNOTEXISTSidx_check_uniqueONhabit_check(habit_id,date);3. 一张 habit_check 表存所有习惯的打卡记录。不按习惯拆表——所有习惯的打卡都在这张表里用habit_id过滤。这是「一对多」关系的标准建模一habit对多habit_check外键指向主表。4. 逻辑外键 vs 物理外键。落地版没有声明FOREIGN KEY物理约束而是用habit_id INTEGER NOT NULL 应用层级联删除。原因RDBrelationalStore对物理外键的支持需要额外配置PRAGMA foreign_keysON且物理外键在级联删除、批量操作时行为更复杂。个人 App 场景用逻辑外键 代码级联更可控——删除习惯时先删打卡记录再删习惯见 deleteHabit 方法。三、建表 SQL双表 三索引CREATETABLEIFNOTEXISTShabit(idINTEGERPRIMARYKEYAUTOINCREMENT,nameTEXTNOTNULL,iconTEXTDEFAULT,colorTEXTDEFAULT#6366F1,targetINTEGERDEFAULT30,created_timeINTEGERNOTNULL);CREATETABLEIFNOTEXISTShabit_check(idINTEGERPRIMARYKEYAUTOINCREMENT,habit_idINTEGERNOTNULL,dateTEXTNOTNULL,check_timeINTEGERNOTNULL);CREATEUNIQUEINDEXIFNOTEXISTSidx_check_uniqueONhabit_check(habit_id,date);注意落地版与文章版的两个差异表名文章版叫checkin落地版叫habit_check——更清晰地表达「习惯的打卡」避免与系统保留字混淆索引文章版建普通索引idx_checkin_habit、idx_checkin_date两个落地版只建一个联合唯一索引idx_check_unique ON (habit_id, date)。一个索引同时完成三件事强制唯一、按 habit 过滤、按 habitdate 定位。SQLite 的多列索引最左前缀原则下(habit_id, date)索引能同时服务「按 habit_id 查全部」和「按 habit_id date 查单天」两种查询——索引更少能力更全。四、HabitDao 封装单例复用 ResultSet 映射数据层核心HabitDao与前面实例相同的架构模式。实体接口exportinterfaceHabit{id:number;name:string;icon:string;// emoji 图标color:string;// 主题色 HEXtarget:number;// 每月目标天数createdTime:number;}exportinterfaceCheckIn{id:number;habitId:number;date:string;// YYYY-MM-DDcheckTime:number;// 打卡时间戳}getStore单例复用 双表初始化staticasyncgetStore(context:common.Context):PromiserelationalStore.RdbStore{if(HabitDao.store){returnHabitDao.store;}constconfig:relationalStore.StoreConfig{name:habit.db,securityLevel:relationalStore.SecurityLevel.S1,};HabitDao.storeawaitrelationalStore.getRdbStore(context,config);awaitHabitDao.store.executeSql(CREATE TABLE IF NOT EXISTS${HabitDao.TABLE}(...)// 习惯表);awaitHabitDao.store.executeSql(CREATE TABLE IF NOT EXISTS${HabitDao.CHECK_TABLE}(...)// 打卡表);awaitHabitDao.store.executeSql(CREATE UNIQUE INDEX IF NOT EXISTS idx_check_unique ON${HabitDao.CHECK_TABLE}(habit_id, date));hilog.info(DOMAIN,TAG,习惯表与打卡表初始化成功);returnHabitDao.store;}ArkTS 语法红线静态方法里引用静态字段必须写HabitDao.store不能写this.store——arkts-no-this-in-static是 ArkTS 编译器的强制规则文章版代码里的this.store全部是编译错误落地版已修正。行映射方法ResultSet 模式而非文章版的 getRow 强转privatestaticrowToHabit(result:relationalStore.ResultSet):Habit{return{id:result.getLong(result.getColumnIndex(id)),name:result.getString(result.getColumnIndex(name)),icon:result.getString(result.getColumnIndex(icon))||,color:result.getString(result.getColumnIndex(color))||#6366F1,target:result.getLong(result.getColumnIndex(target)),createdTime:result.getLong(result.getColumnIndex(created_time)),};}五、习惯的增删查一对多级联删除习惯 CRUD 中deleteHabit是最有讲究的——它演示了逻辑外键下的级联删除staticasyncdeleteHabit(context:common.Context,id:number):Promisevoid{conststoreawaitHabitDao.getStore(context);constcheckPrednewrelationalStore.RdbPredicates(HabitDao.CHECK_TABLE);checkPred.equalTo(habit_id,id);awaitstore.delete(checkPred);// 先删打卡记录consthabitPrednewrelationalStore.RdbPredicates(HabitDao.TABLE);habitPred.equalTo(id,id);awaitstore.delete(habitPred);// 再删习惯本体}顺序为什么重要如果先删习惯再删打卡就会出现「孤儿记录」——打卡记录指向一个不存在的习惯热力图查询会拿到脏数据。先删子表再删主表保证数据库永远干净。生产环境若数据量大这一步应包在事务里beginTransaction/commit后续实例库存进销存会演示事务写法。六、打卡与取消打卡toggle 语义的实现打卡按钮的交互是「再点一次取消」——toggle 切换语义。落地版实现staticasynctoggleCheck(context:common.Context,habitId:number,date:string):Promisevoid{conststoreawaitHabitDao.getStore(context);constprednewrelationalStore.RdbPredicates(HabitDao.CHECK_TABLE);pred.equalTo(habit_id,habitId).equalTo(date,date);constresultawaitstore.query(pred);consthasresult.goToNextRow();result.close();if(has){awaitstore.delete(pred);// 已打卡 → 取消}else{constvalues:relationalStore.ValuesBucket{habit_id:habitId,date:date,check_time:Date.now(),};awaitstore.insert(HabitDao.CHECK_TABLE,values);// 未打卡 → 打卡}}为什么不用INSERT OR REPLACE因为 toggle 需要「有则删、无则插」的对称语义而INSERT OR REPLACE只能覆盖不能删除。先查后插/删虽然多一次查询但逻辑清晰、零歧义。唯一索引idx_check_unique在这里是最后防线——即使前端并发点了两次数据库也会拒绝重复打卡保证数据一致性。hasCheckIn判断某天是否已打卡与toggleCheck前半段逻辑一致是热力图渲染的查询基础staticasynchasCheckIn(context:common.Context,habitId:number,date:string):Promiseboolean{conststoreawaitHabitDao.getStore(context);constpredicatesnewrelationalStore.RdbPredicates(HabitDao.CHECK_TABLE);predicates.equalTo(habit_id,habitId).equalTo(date,date);constresultawaitstore.query(predicates);consthasresult.goToNextRow();result.close();returnhas;}七、打卡日期集合热力图的数据源热力图需要「某习惯最近 N 天打了哪些卡」的日期集合staticasynccheckDates(context:common.Context,habitId:number,days:number):Promisestring[]{conststoreawaitHabitDao.getStore(context);constpredicatesnewrelationalStore.RdbPredicates(HabitDao.CHECK_TABLE);predicates.equalTo(habit_id,habitId).orderByAsc(date);constresultawaitstore.query(predicates);constlist:string[][];while(result.goToNextRow()){list.push(result.getString(result.getColumnIndex(date)));}result.close();returnlist;}返回的是string[]日期数组如[2025-06-01, 2025-06-02, ...]。页面把它转成Set判断某天是否打卡就是 O(1) 的set.has(dateStr)——热力图渲染几十个格子性能毫无压力。关于 days 参数方法签名接收 days 但当前实现没在 SQL 里过滤简单起见拉全量。生产版本可以加WHERE date date(now, -90 days)只取近 90 天减少传输量。读者可以自行优化。八、连续天数统计Set 回溯算法「已连续坚持 N 天」是最重要的激励文案统计逻辑要严谨——从今天或昨天往前数中断即停staticasynccurrentStreak(context:common.Context,habitId:number):Promisenumber{conststoreawaitHabitDao.getStore(context);constpredicatesnewrelationalStore.RdbPredicates(HabitDao.CHECK_TABLE);predicates.equalTo(habit_id,habitId).orderByDesc(date);constresultawaitstore.query(predicates);constdates:string[][];while(result.goToNextRow()){dates.push(result.getString(result.getColumnIndex(date)));}result.close();if(dates.length0){return0;}// 今天格式constnownewDate();consttoday${now.getFullYear()}-${String(now.getMonth()1).padStart(2,0)}-${String(now.getDate()).padStart(2,0)};constsetnewSetstring(dates);letstreak0;// 若今天没打卡从昨天开始算letcursornewDate(now.getTime());if(!set.has(today)){cursornewDate(now.getTime()-86400000);}while(true){constkey${cursor.getFullYear()}-${String(cursor.getMonth()1).padStart(2,0)}-${String(cursor.getDate()).padStart(2,0)};if(set.has(key)){streak;cursornewDate(cursor.getTime()-86400000);}else{break;}}returnstreak;}算法三步走拉取该习惯全部打卡日期转成Set去重 O(1) 查找确定起点今天打卡了就从今天起算今天没打卡就从昨天起算——这样「昨天打了今天还没打」不会误判为断签用户体验更友好毕竟今天还没过完逐日回溯往前一天一天数遇到集合里没有的日期就停返回连续天数。为什么不用 SQL 做连续统计连续性的本质是「日期序列的连续性」——SQL 做这种「找最长连续子序列」需要窗口函数LAG/ROW_NUMBERRDB 的 querySql 支持有限。而拉出全部日期后在前端用 Set 回溯逻辑直观、代码量少、几十上百条数据性能毫无问题。数据量小时把复杂逻辑放内存比硬怼 SQL 更明智——这是本实例反复出现的务实原则。九、本月打卡次数月历进度「本月 X/30 天」进度展示的查询staticasyncmonthCount(context:common.Context,habitId:number):Promisenumber{conststoreawaitHabitDao.getStore(context);constnownewDate();constfirstDay${now.getFullYear()}-${String(now.getMonth()1).padStart(2,0)}-01;constpredicatesnewrelationalStore.RdbPredicates(HabitDao.CHECK_TABLE);predicates.equalTo(habit_id,habitId).greaterThanOrEqualTo(date,firstDay);constresultawaitstore.query(predicates);letcount0;while(result.goToNextRow()){count;}result.close();returncount;}greaterThanOrEqualTo(date, firstDay)等价于WHERE date 2025-06-01——字符串日期比较在这里完美工作 2025-06-01天然排除了上月记录。这就是日期字符串存储的回报范围查询零转换。十、技术要点对照表技术点实现方式生产价值日期字符串YYYY-MM-DDTEXT排序/比较/区间天然有序双表设计habit habit_check 一对多习惯与打卡解耦联合唯一索引UNIQUE (habit_id, date)数据库级防重复打卡打卡切换先查后插/删 toggle有则删无则插语义对称日期范围 2025-06-01字符串比较月历热力图数据源连续天数日期集合 Set 回溯激励文案算法清晰级联删除先删 checkin 再删 habit避免孤儿记录十一、文章小结打卡实例展示了一对多双表 日期字符串存储的设计habit 表存习惯元数据habit_check 表存每日打卡UNIQUE(habit_id, date)联合索引保证一天最多一次。连续天数统计用「日期集合 Set 回溯」实现比逐日 SQL 更简洁。这是日历类、打卡类、签到类应用的通用数据模型——本实例的建模经验可以直接迁移到任何「主体 × 时间行为」的场景。