feat: 用户配置项增加 bPersistImmediatelyOnChange 标记用于延迟存储

Author: tinymins

Boilerplate_!Base/src/lib/Storage.UserSettings.lua

@@ -138,6 +138,50 @@ local function DeleteInstanceInfoData(inst, info)
 	end
 end
 
+-- 统一处理配置项存盘逻辑
+---@param inst table 数据库实例
+---@param info table 配置项信息
+---@param szDataSetKey string|number DataSet 键值（可选，仅当配置项为 DataSet 类型时使用）
+---@param xValue any 要保存的值
+---@param bDelete boolean 是否为删除操作
+local function FlushSettingsData(inst, info, szDataSetKey, xValue, bDelete)
+	if info.bDataSet then
+		-- 处理 DataSet 类型的数据
+		if bDelete then
+			-- 删除 DataSet 中的某个键
+			local res = GetInstanceInfoData(inst, info)
+			if X.IsTable(res) and res.v == info.szVersion and X.IsTable(res.d) then
+				res.d[szDataSetKey] = nil
+				if X.IsEmpty(res.d) then
+					DeleteInstanceInfoData(inst, info)
+				else
+					SetInstanceInfoData(inst, info, res.d, info.szVersion)
+				end
+			else
+				DeleteInstanceInfoData(inst, info)
+			end
+		else
+			-- 设置 DataSet 中的某个键
+			local res = GetInstanceInfoData(inst, info)
+			local dataToSave
+			if X.IsTable(res) and res.v == info.szVersion and X.IsTable(res.d) then
+				res.d[szDataSetKey] = xValue
+				dataToSave = res.d
+			else
+				dataToSave = { [szDataSetKey] = xValue }
+			end
+			SetInstanceInfoData(inst, info, dataToSave, info.szVersion)
+		end
+	else
+		-- 处理普通数据
+		if bDelete then
+			DeleteInstanceInfoData(inst, info)
+		else
+			SetInstanceInfoData(inst, info, xValue, info.szVersion)
+		end
+	end
+end
+
 function X.IsUserSettingsAvailable()
 	return DATABASE_CONNECTION_ESTABLISHED
 end
@@ -229,6 +273,32 @@ function X.ReleaseUserSettingsDB()
 end
 
 function X.FlushUserSettingsDB()
+	-- 遍历 DATA_CACHE 查找需要 flush 的数据
+	for szKey, cache in pairs(DATA_CACHE) do
+		local info = USER_SETTINGS_INFO[szKey]
+		if info then
+			local inst = DATABASE_INSTANCE[info.ePathType]
+			if inst then
+				if cache.bDataSet then
+					-- 处理 DataSet 类型的数据
+					for szDataSetKey, dataSetCache in pairs(cache.tDataSet) do
+						if dataSetCache.bFlushRequired then
+							FlushSettingsData(inst, info, szDataSetKey, dataSetCache.xValue, dataSetCache.bDeleted)
+							-- 清除 flush 标记
+							dataSetCache.bFlushRequired = nil
+						end
+					end
+				else
+					-- 处理普通数据
+					if cache.bFlushRequired then
+						FlushSettingsData(inst, info, nil, cache.xValue, cache.bDeleted)
+						-- 清除 flush 标记
+						cache.bFlushRequired = nil
+					end
+				end
+			end
+		end
+	end
 	-- for _, ePathType in ipairs(DATABASE_TYPE_LIST) do
 	-- 	local inst = DATABASE_INSTANCE[ePathType]
 	-- 	if inst then
@@ -349,8 +419,9 @@ end
 --   {schema} tOption.xSchema 数据类型约束对象，通过 Schema 库生成
 --   {boolean} tOption.bDataSet 是否为配置项组（如用户多套自定义偏好），配置项组在读写时需要额外传入一个组下配置项唯一键值（即多套自定义偏好中某一项的名字）
 --   {table} tOption.tDataSetDefaultValue 数据默认值（仅当 bDataSet 为真时生效，用于设置配置项组不同默认值）
+--   {boolean} tOption.bPersistImmediatelyOnChange 是否在变更时立即持久化到文件，默认为 true，为 false 时变更会缓存在内存中等待系统空闲时写入
 function X.RegisterUserSettings(szKey, tOption)
-	local ePathType, szDataKey, bUserData, bNoExport, szGroup, szLabel, szDescription, szVersion, szRestriction, xDefaultValue, xSchema, bDataSet, tDataSetDefaultValue, eDefaultLocationOverride
+	local ePathType, szDataKey, bUserData, bNoExport, szGroup, szLabel, szDescription, szVersion, szRestriction, xDefaultValue, xSchema, bDataSet, tDataSetDefaultValue, eDefaultLocationOverride, bPersistImmediatelyOnChange
 	if X.IsTable(tOption) then
 		ePathType = tOption.ePathType
 		szDataKey = tOption.szDataKey
@@ -366,6 +437,7 @@ function X.RegisterUserSettings(szKey, tOption)
 		bDataSet = tOption.bDataSet
 		tDataSetDefaultValue = tOption.tDataSetDefaultValue
 		eDefaultLocationOverride = tOption.eDefaultLocationOverride
+		bPersistImmediatelyOnChange = tOption.bPersistImmediatelyOnChange
 	end
 	if not ePathType then
 		ePathType = X.PATH_TYPE.ROLE
@@ -376,6 +448,9 @@ function X.RegisterUserSettings(szKey, tOption)
 	if not szVersion then
 		szVersion = ''
 	end
+	if X.IsNil(bPersistImmediatelyOnChange) then
+		bPersistImmediatelyOnChange = true
+	end
 	if not X.IsString(szKey) or szKey == '' then
 		assert(false, 'RegisterUserSettings KEY(' .. X.EncodeLUAData(szKey) .. '): `Key` should be a non-empty string value.')
 	end
@@ -441,6 +516,7 @@ function X.RegisterUserSettings(szKey, tOption)
 		bDataSet = bDataSet,
 		tDataSetDefaultValue = tDataSetDefaultValue,
 		eDefaultLocationOverride = eDefaultLocationOverride,
+		bPersistImmediatelyOnChange = bPersistImmediatelyOnChange,
 	}
 	setmetatable(tInfo, {
 		__index = function(t, k)
@@ -533,7 +609,13 @@ function X.GetUserSettings(szKey, ...)
 			or nil
 	end
 	if X.IsTable(cache) and cache.bValue then
-		res, bData, bCache = cache.xValue, true, true
+		-- 从缓存获取数据，如果标记为删除则返回默认值
+		if cache.bDeleted then
+			-- 数据被删除但还没有 flush，直接返回默认值
+			bData, bCache = false, true
+		else
+			res, bData, bCache = cache.xValue, true, true
+		end
 	end
 	-- 未命中缓存，从数据库读取
 	if not bCache then
@@ -581,12 +663,14 @@ function X.GetUserSettings(szKey, ...)
 				bValue = true,
 				xValue = res,
 				xRawValue = X.Clone(res),
+				bDeleted = false,
 			}
 		else
 			DATA_CACHE[szKey] = {
 				bValue = true,
 				xValue = res,
 				xRawValue = X.Clone(res),
+				bDeleted = false,
 			}
 		end
 	end
@@ -645,20 +729,33 @@ function X.SetUserSettings(szKey, ...)
 	end
 	-- 写数据库
 	if info.bDataSet then
-		local res = GetInstanceInfoData(inst, info)
-		if X.IsTable(res) and res.v == info.szVersion and X.IsTable(res.d) then
-			res.d[szDataSetKey] = xValue
-			xValue = res.d
-		else
-			xValue = { [szDataSetKey] = xValue }
-		end
-		if X.IsTable(DATA_CACHE[szKey]) and DATA_CACHE[szKey].bDataSet then
-			DATA_CACHE[szKey].tDataSet[szDataSetKey] = nil
+		-- 更新缓存
+		if not DATA_CACHE[szKey] then
+			DATA_CACHE[szKey] = { bDataSet = true, tDataSet = {} }
+		end
+		DATA_CACHE[szKey].tDataSet[szDataSetKey] = {
+			bValue = true,
+			xValue = X.Clone(xValue),
+			xRawValue = X.Clone(xValue),
+			bFlushRequired = not info.bPersistImmediatelyOnChange,
+			bDeleted = false,
+		}
+		if info.bPersistImmediatelyOnChange then
+			FlushSettingsData(inst, info, szDataSetKey, xValue, false)
 		end
 	else
-		DATA_CACHE[szKey] = nil
+		-- 更新缓存
+		DATA_CACHE[szKey] = {
+			bValue = true,
+			xValue = X.Clone(xValue),
+			xRawValue = X.Clone(xValue),
+			bFlushRequired = not info.bPersistImmediatelyOnChange,
+			bDeleted = false,
+		}
+		if info.bPersistImmediatelyOnChange then
+			FlushSettingsData(inst, info, nil, xValue, false)
+		end
 	end
-	SetInstanceInfoData(inst, info, xValue, info.szVersion)
 	-- if info.bUserData then
 	-- 	inst.bUserDataDBCommit = true
 	-- else
@@ -715,24 +812,40 @@ function X.ResetUserSettings(szKey, ...)
 	end
 	-- 写数据库
 	if info.bDataSet then
-		local res = GetInstanceInfoData(inst, info)
-		if X.IsTable(res) and res.v == info.szVersion and X.IsTable(res.d) and szDataSetKey then
-			res.d[szDataSetKey] = nil
-			if X.IsEmpty(res.d) then
-				DeleteInstanceInfoData(inst, info)
-			else
-				SetInstanceInfoData(inst, info, res.d, info.szVersion)
-			end
-			if DATA_CACHE[szKey] and DATA_CACHE[szKey].bDataSet then
-				DATA_CACHE[szKey].tDataSet[szDataSetKey] = nil
+		-- 更新缓存
+		if not DATA_CACHE[szKey] then
+			DATA_CACHE[szKey] = { bDataSet = true, tDataSet = {} }
+		end
+		if szDataSetKey then
+			DATA_CACHE[szKey].tDataSet[szDataSetKey] = {
+				bValue = true,
+				xValue = nil,
+				xRawValue = nil,
+				bFlushRequired = not info.bPersistImmediatelyOnChange,
+				bDeleted = true,
+			}
+			if info.bPersistImmediatelyOnChange then
+				FlushSettingsData(inst, info, szDataSetKey, nil, true)
 			end
 		else
-			DeleteInstanceInfoData(inst, info)
+			-- 重置整个 DataSet
 			DATA_CACHE[szKey] = nil
+			if info.bPersistImmediatelyOnChange then
+				FlushSettingsData(inst, info, nil, nil, true)
+			end
 		end
 	else
-		DeleteInstanceInfoData(inst, info)
-		DATA_CACHE[szKey] = nil
+		-- 更新缓存
+		DATA_CACHE[szKey] = {
+			bValue = true,
+			xValue = nil,
+			xRawValue = nil,
+			bFlushRequired = not info.bPersistImmediatelyOnChange,
+			bDeleted = true,
+		}
+		if info.bPersistImmediatelyOnChange then
+			FlushSettingsData(inst, info, nil, nil, true)
+		end
 	end
 	-- if info.bUserData then
 	-- 	inst.bUserDataDBCommit = true