文件与持久化存储

// === 使用 getFilesDir() 进行文件读写的完整示例 ===
 
// 获取 files/ 目录的 File 对象
// 返回路径通常为: /data/data/com.example.myapp/files
val filesDir: File = context.filesDir
 
// 在 files/ 目录下创建一个子目录 "logs"
// mkdirs() 会递归创建所有缺失的父目录
val logsDir = File(filesDir, "logs")
logsDir.mkdirs()  // 如果目录已存在则什么都不做，返回 false
 
// 在 logs/ 子目录下创建一个日志文件
val logFile = File(logsDir, "app.log")
 
// --- 写入操作 ---
// 使用 Kotlin 扩展函数 writeText()，内部基于 OutputStreamWriter
// 默认使用 UTF-8 编码，会覆盖文件原有内容
logFile.writeText("2025-01-01 12:00:00 App started\n")
 
// 追加写入：appendText() 不会清空原有内容
logFile.appendText("2025-01-01 12:00:05 User logged in\n")
 
// --- 读取操作 ---
// readText() 一次性将文件全部内容读入内存（适合小文件）
val content: String = logFile.readText()
 
// 对于大文件，推荐使用 bufferedReader 逐行读取，避免 OOM
logFile.bufferedReader().useLines { lines ->
    // useLines 会在 lambda 结束后自动关闭流
    lines.forEach { line ->
        // 逐行处理，内存中只保留当前行
        println(line)
    }
}

// 通常在 Application.onCreate() 中开启，仅限 Debug 构建
StrictMode.setThreadPolicy(
    StrictMode.ThreadPolicy.Builder()
        .detectDiskReads()    // 检测主线程磁盘读取
        .detectDiskWrites()   // 检测主线程磁盘写入
        .penaltyLog()         // 违规时输出日志（也可用 penaltyDeath() 直接崩溃）
        .build()
)

// === getCacheDir() 使用示例：带容量检查的缓存写入 ===
 
// 获取 cache/ 目录
val cacheDir: File = context.cacheDir
 
// 定义最大缓存容量（示例为 5MB）
val maxCacheSize = 5L * 1024 * 1024
 
/**
 * 计算指定目录及其子目录下所有文件的总大小（递归）。
 * walkTopDown() 会按深度优先遍历整棵文件树。
 */
fun directorySize(dir: File): Long =
    dir.walkTopDown()                 // 创建一个从 dir 开始的深度优先文件遍历序列
        .filter { it.isFile }         // 只保留文件，跳过目录本身
        .sumOf { it.length() }        // 累加每个文件的字节大小
 
/**
 * 当缓存超出容量上限时，按最后修改时间淘汰最旧的文件。
 * 这是一种简易的 LRU 淘汰策略。
 */
fun trimCacheIfNeeded(dir: File, maxSize: Long) {
    var currentSize = directorySize(dir)  // 计算当前缓存总大小
    if (currentSize <= maxSize) return     // 未超限，直接返回
 
    // 获取所有文件，按最后修改时间升序排列（最旧的排在前面）
    val files = dir.walkTopDown()
        .filter { it.isFile }
        .sortedBy { it.lastModified() }
        .toList()
 
    // 逐个删除最旧的文件，直到总大小降到阈值以下
    for (file in files) {
        val fileSize = file.length()  // 记录删除前的文件大小
        if (file.delete()) {          // 尝试删除
            currentSize -= fileSize   // 成功则减去对应大小
        }
        if (currentSize <= maxSize) break  // 达标则停止删除
    }
}
 
// --- 实际使用 ---
// 先清理，再写入新缓存
trimCacheIfNeeded(cacheDir, maxCacheSize)
 
// 写入一个临时缓存文件
val tempFile = File(cacheDir, "api_response_cache.json")
tempFile.writeText("""{"data": "cached content"}""")
 
// 读取缓存时必须先检查存在性
if (tempFile.exists()) {
    val cached = tempFile.readText()
    // 使用缓存数据...
} else {
    // 缓存已被系统或用户清除，需要重新获取数据
}

// name: 文件名（不能包含路径分隔符 "/"）
// mode: 文件打开模式
fun openFileOutput(name: String, mode: Int): FileOutputStream

// === openFileOutput() 与 openFileInput() 配对使用 ===
 
// --- 写入文件 ---
// openFileOutput 在 files/ 目录下创建文件 "note.txt"
// MODE_PRIVATE: 文件仅本应用可访问，若文件已存在则覆盖
context.openFileOutput("note.txt", Context.MODE_PRIVATE).use { fos ->
    // use {} 扩展函数确保 lambda 结束后自动调用 close()
    // 即使发生异常也会正确关闭流（等同于 try-with-resources）
 
    // 将字符串转为 UTF-8 字节数组后写入
    fos.write("Hello, Internal Storage!".toByteArray())
 
    // 也可以包装为 BufferedWriter 进行更高效的文本写入
    // fos.bufferedWriter().use { writer -> writer.write("...") }
}
 
// --- 追加写入 ---
// MODE_APPEND: 不清空文件，在末尾追加内容
context.openFileOutput("note.txt", Context.MODE_APPEND).use { fos ->
    fos.write("\nThis line is appended.".toByteArray())
}
 
// --- 读取文件 ---
// openFileInput 打开 files/ 目录下的 "note.txt"，返回 FileInputStream
context.openFileInput("note.txt").use { fis ->
    // bufferedReader() 包装为带缓冲的字符读取器
    val content = fis.bufferedReader().readText()
    // content = "Hello, Internal Storage!\nThis line is appended."
}
 
// --- 列举 files/ 目录下的所有文件 ---
// fileList() 返回 files/ 目录下的文件名数组（不含子目录中的文件）
val allFiles: Array<String> = context.fileList()
allFiles.forEach { fileName ->
    // 输出每个文件名，例如 "note.txt"
    println("Found file: $fileName")
}
 
// --- 删除文件 ---
// deleteFile() 删除 files/ 目录下的指定文件
// 返回 true 表示删除成功，false 表示文件不存在或删除失败
val deleted: Boolean = context.deleteFile("note.txt")

// 获取外部存储根目录，通常为 /storage/emulated/0
val externalRoot: File = Environment.getExternalStorageDirectory()
 
// 获取外部存储中某个标准公有子目录
// 例如获取 Pictures 目录：/storage/emulated/0/Pictures
val picturesDir: File = Environment.getExternalStoragePublicDirectory(
    Environment.DIRECTORY_PICTURES  // 传入目录类型常量
)

/**
 * 检查外部存储是否可以进行读写操作
 * 只有状态为 MEDIA_MOUNTED 时，存储才同时支持读和写
 */
fun isExternalStorageWritable(): Boolean {
    // 获取当前外部存储挂载状态
    val state = Environment.getExternalStorageState()
    // 与 MEDIA_MOUNTED 常量比较，仅此状态支持读写
    return state == Environment.MEDIA_MOUNTED
}
 
/**
 * 检查外部存储是否至少可以读取
 * MEDIA_MOUNTED 和 MEDIA_MOUNTED_READ_ONLY 两种状态都支持读
 */
fun isExternalStorageReadable(): Boolean {
    // 获取当前外部存储挂载状态
    val state = Environment.getExternalStorageState()
    // 可读的条件：已挂载（读写）或 已挂载（只读）
    return state == Environment.MEDIA_MOUNTED ||
           state == Environment.MEDIA_MOUNTED_READ_ONLY
}

fun saveImageToExternal(bitmap: Bitmap) {
    // 写入操作前，先确认外部存储可写
    if (!isExternalStorageWritable()) {
        // 存储不可用时应给出用户提示或降级处理
        Log.w("Storage", "External storage is not writable")
        return
    }
    // ... 执行写入逻辑
}

// 获取应用在第二张 SD 卡上的外部目录（如果存在）
val externalDirs: Array<File> = context.getExternalFilesDirs(null)
// externalDirs[0] -> 主外部存储（通常是模拟的）
// externalDirs[1] -> 第二块外部存储（物理 SD 卡，如存在）
 
if (externalDirs.size > 1 && externalDirs[1] != null) {
    // 检查第二块存储的挂载状态
    val sdCardState = Environment.getExternalStorageState(externalDirs[1])
    // 根据状态决定是否使用该存储卷
    if (sdCardState == Environment.MEDIA_MOUNTED) {
        // 可以安全写入 SD 卡
    }
}

<!-- 声明写入外部存储权限 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<!-- 读取外部存储也需要权限了（API 19+） -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<!-- 写入权限隐含读取权限 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

// 检查是否已获得写入权限
val hasPermission = ContextCompat.checkSelfPermission(
    this,  // Context
    Manifest.permission.WRITE_EXTERNAL_STORAGE  // 目标权限
) == PackageManager.PERMISSION_GRANTED  // 判断是否已授权
 
if (!hasPermission) {
    // 向用户请求权限，触发系统权限弹窗
    ActivityCompat.requestPermissions(
        this,  // 当前 Activity
        arrayOf(Manifest.permission.WRITE_EXTERNAL_STORAGE),  // 权限数组
        REQUEST_CODE_STORAGE  // 自定义请求码，用于回调识别
    )
}

<application
    android:requestLegacyExternalStorage="true"
    ... >
    <!-- 此标志在 Android 10 上恢复传统存储行为 -->
    <!-- 但在 Android 11+ 上此标志被完全忽略 -->
</application>

<!-- 请求管理所有文件的特殊权限（Android 11+） -->
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />

// 检查是否拥有"管理所有文件"权限
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
    // 使用 Environment 的专用方法检查
    val isManager = Environment.isExternalStorageManager()
    if (!isManager) {
        // 引导用户前往系统设置页手动开启
        val intent = Intent(Settings.ACTION_MANAGE_ALL_FILES_ACCESS_PERMISSION)
        startActivity(intent)
    }
}

<!-- Android 13+ 细粒度媒体权限 -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
 
<!-- 兼容 Android 12 及以下，声明 maxSdkVersion 限制其生效范围 -->
<uses-permission
    android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />

// 获取应用专属外部目录根路径
// 路径：/storage/emulated/0/Android/data/<pkg>/files/
val rootDir: File? = context.getExternalFilesDir(null)
 
// 获取应用专属的 Pictures 子目录
// 路径：/storage/emulated/0/Android/data/<pkg>/files/Pictures/
val picturesDir: File? = context.getExternalFilesDir(Environment.DIRECTORY_PICTURES)
 
// 获取应用专属的 Movies 子目录
// 路径：/storage/emulated/0/Android/data/<pkg>/files/Movies/
val moviesDir: File? = context.getExternalFilesDir(Environment.DIRECTORY_MOVIES)
 
// 也可以传入自定义字符串创建自定义子目录
// 路径：/storage/emulated/0/Android/data/<pkg>/files/MyCustomDir/
val customDir: File? = context.getExternalFilesDir("MyCustomDir")

// 获取应用专属外部缓存目录
// 路径：/storage/emulated/0/Android/data/<pkg>/cache/
val externalCacheDir: File? = context.externalCacheDir

// 获取所有存储卷上的应用专属 Pictures 目录
// 返回数组，索引 0 是主存储，后续是附加存储卷
val allPictureDirs: Array<File> = context.getExternalFilesDirs(
    Environment.DIRECTORY_PICTURES  // 子目录类型
)
 
// 遍历所有可用的存储卷
allPictureDirs.forEachIndexed { index, dir ->
    // 检查该存储卷的挂载状态
    val state = Environment.getExternalStorageState(dir)
    if (state == Environment.MEDIA_MOUNTED) {
        // 该存储卷可用，可以写入
        Log.d("Storage", "Volume $index path: ${dir.absolutePath}")
        Log.d("Storage", "Volume $index free: ${dir.freeSpace / 1024 / 1024} MB")
    }
}

/**
 * 将 Bitmap 保存到应用专属外部目录的 Pictures 子目录
 * @param context   应用上下文
 * @param bitmap    要保存的图片
 * @param fileName  文件名（如 "photo_001.jpg"）
 * @return 保存成功的文件路径，失败返回 null
 */
fun saveBitmapToExternalFiles(
    context: Context,
    bitmap: Bitmap,
    fileName: String
): String? {
    // 第一步：检查外部存储是否可写
    if (Environment.getExternalStorageState() != Environment.MEDIA_MOUNTED) {
        Log.e("Storage", "External storage is not mounted")
        return null  // 存储不可用，提前返回
    }
 
    // 第二步：获取应用专属外部 Pictures 目录
    val picturesDir: File = context.getExternalFilesDir(
        Environment.DIRECTORY_PICTURES  // 标准图片目录
    ) ?: run {
        Log.e("Storage", "Failed to get external files dir")
        return null  // 目录获取失败，提前返回
    }
 
    // 第三步：确保目录存在（通常系统会自动创建，但防御性编程）
    if (!picturesDir.exists()) {
        picturesDir.mkdirs()  // 递归创建目录结构
    }
 
    // 第四步：创建目标文件并写入
    val targetFile = File(picturesDir, fileName)
    return try {
        // 使用 FileOutputStream 写入 JPEG 格式
        FileOutputStream(targetFile).use { fos ->
            // compress() 将 Bitmap 压缩为 JPEG 并写入流
            // 参数：格式、质量(0-100)、输出流
            bitmap.compress(Bitmap.CompressFormat.JPEG, 90, fos)
            // use{} 会在 lambda 结束后自动调用 fos.close()
        }
        Log.d("Storage", "Saved: ${targetFile.absolutePath}")
        targetFile.absolutePath  // 返回保存路径
    } catch (e: IOException) {
        Log.e("Storage", "Failed to save bitmap", e)
        null  // 写入失败返回 null
    }
}

// 检查是否拥有「所有文件访问」权限（Android 11+）
// Environment.isExternalStorageManager() 返回 true 表示已授权
val hasAllFilesAccess = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
    Environment.isExternalStorageManager()  // 调用系统 API 检查
} else {
    true  // Android 11 以下不需要此权限，直接视为拥有
}
 
// 如果没有权限，跳转到系统设置页让用户手动开启
if (!hasAllFilesAccess) {
    val intent = Intent(Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION)
    // 将 Intent 的 data 设置为当前应用的包名 URI
    intent.data = Uri.fromParts("package", packageName, null)
    startActivity(intent)  // 打开系统设置页面
}

/**
 * 将 Bitmap 保存到公共 Pictures 目录
 * @param context  上下文，用于获取 ContentResolver
 * @param bitmap   要保存的位图对象
 * @param fileName 保存的文件名（不含扩展名）
 * @return 成功写入后的 content:// URI，失败返回 null
 */
fun saveBitmapToGallery(
    context: Context,
    bitmap: Bitmap,
    fileName: String
): Uri? {
    // 1. 构建媒体文件的元信息（ContentValues 类似 Map<String, Object>）
    val contentValues = ContentValues().apply {
        // 文件显示名称（含扩展名）
        put(MediaStore.Images.Media.DISPLAY_NAME, "$fileName.jpg")
        // MIME 类型，系统据此决定存储位置和索引方式
        put(MediaStore.Images.Media.MIME_TYPE, "image/jpeg")
        // 指定存储的相对路径（基于 Pictures 目录）
        // Android 10+ 才支持 RELATIVE_PATH 列
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            // 文件将存储在 Pictures/MyApp/ 子目录下
            put(MediaStore.Images.Media.RELATIVE_PATH, "Pictures/MyApp")
            // IS_PENDING = 1 表示文件正在写入中
            // 设为 pending 后，其他应用通过 MediaStore 查询不到这条记录
            // 避免用户在图库中看到写了一半的"损坏"图片
            put(MediaStore.Images.Media.IS_PENDING, 1)
        }
    }
 
    // 2. 向 MediaStore 的 Images 集合插入一条记录
    //    系统会在对应目录创建空文件，并返回 content:// URI
    val resolver = context.contentResolver
    val uri = resolver.insert(
        MediaStore.Images.Media.EXTERNAL_CONTENT_URI,  // 目标集合的 URI
        contentValues  // 元数据
    ) ?: return null  // 插入失败（如存储空间不足）返回 null
 
    // 3. 通过返回的 URI 打开输出流，写入实际的图片字节数据
    resolver.openOutputStream(uri)?.use { outputStream ->
        // 将 bitmap 压缩为 JPEG 格式，质量 90%，写入输出流
        bitmap.compress(Bitmap.CompressFormat.JPEG, 90, outputStream)
    }
 
    // 4. 写入完成，清除 IS_PENDING 标记
    //    此时其他应用才能通过 MediaStore 查询到这张图片
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        contentValues.clear()  // 清空旧值
        contentValues.put(MediaStore.Images.Media.IS_PENDING, 0)  // 标记为完成
        resolver.update(uri, contentValues, null, null)  // 更新记录
    }
 
    return uri  // 返回写入成功的 URI
}

/**
 * 查询设备上所有 JPEG 图片，按修改时间降序排列
 * @param context 上下文
 * @return 图片信息列表（URI + 文件名 + 大小）
 */
fun queryAllJpegImages(context: Context): List<Triple<Uri, String, Long>> {
    val result = mutableListOf<Triple<Uri, String, Long>>()
 
    // 定义需要查询的列（类似 SQL 的 SELECT 子句）
    val projection = arrayOf(
        MediaStore.Images.Media._ID,           // 主键 ID，用于构造完整 URI
        MediaStore.Images.Media.DISPLAY_NAME,  // 文件显示名称
        MediaStore.Images.Media.SIZE           // 文件大小（字节）
    )
 
    // 定义筛选条件（类似 SQL 的 WHERE 子句）
    val selection = "${MediaStore.Images.Media.MIME_TYPE} = ?"
    // 条件参数：只查 JPEG 类型
    val selectionArgs = arrayOf("image/jpeg")
    // 排序方式（类似 SQL 的 ORDER BY）：按修改日期降序
    val sortOrder = "${MediaStore.Images.Media.DATE_MODIFIED} DESC"
 
    // 执行查询，返回 Cursor（类似数据库游标）
    context.contentResolver.query(
        MediaStore.Images.Media.EXTERNAL_CONTENT_URI,  // 查询目标：外部存储的图片集合
        projection,      // 返回哪些列
        selection,       // 过滤条件
        selectionArgs,   // 条件参数
        sortOrder        // 排序规则
    )?.use { cursor ->  // use 确保 Cursor 自动关闭，防止资源泄漏
        // 预先获取各列的索引（比在循环内获取更高效）
        val idColumn = cursor.getColumnIndexOrThrow(MediaStore.Images.Media._ID)
        val nameColumn = cursor.getColumnIndexOrThrow(MediaStore.Images.Media.DISPLAY_NAME)
        val sizeColumn = cursor.getColumnIndexOrThrow(MediaStore.Images.Media.SIZE)
 
        // 遍历查询结果的每一行
        while (cursor.moveToNext()) {
            val id = cursor.getLong(idColumn)           // 获取文件的唯一 ID
            val name = cursor.getString(nameColumn)     // 获取文件名
            val size = cursor.getLong(sizeColumn)        // 获取文件大小
 
            // 用 ID 拼接出完整的 content:// URI
            // 例如：content://media/external/images/media/42
            val contentUri = ContentUris.withAppendedId(
                MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
                id
            )
            result.add(Triple(contentUri, name, size))
        }
    }
    return result
}

/**
 * 删除指定 URI 的媒体文件
 * 如果文件属于其他应用，会请求用户确认
 */
fun deleteMediaFile(activity: Activity, uri: Uri) {
    try {
        // 直接尝试删除——如果是自己创建的文件，会立即成功
        activity.contentResolver.delete(uri, null, null)
    } catch (e: RecoverableSecurityException) {
        // 文件属于其他应用，系统抛出可恢复的安全异常
        // 从异常中获取 IntentSender，用于弹出系统确认对话框
        val intentSender = e.userAction.actionIntent.intentSender
        // 启动系统对话框，请求用户确认"是否允许删除此文件"
        // REQUEST_CODE_DELETE 是自定义的请求码，用于在 onActivityResult 中识别
        activity.startIntentSenderForResult(
            intentSender,          // 系统提供的 IntentSender
            REQUEST_CODE_DELETE,   // 自定义请求码
            null, 0, 0, 0         // 其余参数通常为默认值
        )
    }
}

// 根据系统版本决定请求哪个权限
// Android 13+ 使用细粒度的 READ_MEDIA_IMAGES
// Android 13 以下仍然使用 READ_EXTERNAL_STORAGE
val permission = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    android.Manifest.permission.READ_MEDIA_IMAGES   // Android 13+: 仅图片权限
} else {
    android.Manifest.permission.READ_EXTERNAL_STORAGE  // 旧版本: 通用读取权限
}
 
// 使用 ActivityResultContracts 请求权限（推荐方式，替代旧的 onRequestPermissionsResult）
val launcher = registerForActivityResult(
    ActivityResultContracts.RequestPermission()  // 单个权限请求合约
) { isGranted: Boolean ->
    if (isGranted) {
        // 用户授权成功，执行加载图片逻辑
        loadImages()
    } else {
        // 用户拒绝，展示说明为何需要此权限的 UI
        showPermissionRationale()
    }
}
 
// 发起权限请求（会弹出系统权限对话框）
launcher.launch(permission)

// 1. 定义 ActivityResultLauncher（在 Activity/Fragment 初始化时注册）
//    使用 OpenDocument 合约，返回用户选择的文件 URI
val openDocumentLauncher = registerForActivityResult(
    ActivityResultContracts.OpenDocument()  // 系统提供的 SAF 打开文件合约
) { uri: Uri? ->
    // 回调：用户选择文件后触发（按返回键取消时 uri 为 null）
    uri?.let { selectedUri ->
        // 通过 ContentResolver 打开输入流，读取文件内容
        contentResolver.openInputStream(selectedUri)?.use { inputStream ->
            // bufferedReader() 包装为带缓冲的字符流
            val content = inputStream.bufferedReader().readText()  // 一次性读取全部文本
            // 在此处理文件内容，如显示到 TextView
            textView.text = content
        }
    }
}
 
// 2. 在需要时触发文件选择（如按钮点击事件）
//    参数是 MIME 类型数组，限制用户可选的文件类型
openDocumentLauncher.launch(
    arrayOf("application/pdf", "text/plain")  // 只允许选择 PDF 和纯文本文件
)

// 1. 注册 CreateDocument 合约的 Launcher
//    泛型参数 "text/plain" 指定创建文件的 MIME 类型
val createDocumentLauncher = registerForActivityResult(
    ActivityResultContracts.CreateDocument("text/plain")  // 创建纯文本文件
) { uri: Uri? ->
    // 用户选好保存位置后回调
    uri?.let { targetUri ->
        // 打开输出流，将内容写入用户选择的位置
        contentResolver.openOutputStream(targetUri)?.use { outputStream ->
            // 将字符串转为字节数组写入
            outputStream.write("Hello Scoped Storage!".toByteArray())
        }
    }
}
 
// 2. 发起创建文件请求
//    参数为建议的文件名（用户可在选择器中修改）
createDocumentLauncher.launch("my_export.txt")

// 在收到 SAF 返回的 URI 后，立即持久化读写权限
val takeFlags = Intent.FLAG_GRANT_READ_URI_PERMISSION or  // 读权限
                Intent.FLAG_GRANT_WRITE_URI_PERMISSION     // 写权限（如需要）
 
// takePersistableUriPermission 将临时权限转为持久权限
// 持久权限在设备重启后依然有效，直到用户手动撤销或应用卸载
contentResolver.takePersistableUriPermission(uri, takeFlags)
 
// 之后可以将 URI 的字符串形式保存到 SharedPreferences 或数据库
// 下次应用启动时直接使用，无需再次弹出选择器
val uriString = uri.toString()
preferences.edit().putString("last_opened_file", uriString).apply()
 
// 恢复 URI：从字符串解析回 Uri 对象
val savedUri = Uri.parse(preferences.getString("last_opened_file", null))
// 直接使用 contentResolver.openInputStream(savedUri) 即可访问

// 从 SAF 返回的目录 URI 构造 DocumentFile
// fromTreeUri 用于 ACTION_OPEN_DOCUMENT_TREE 返回的目录 URI
val directory = DocumentFile.fromTreeUri(context, treeUri)
 
// 列出目录下所有文件（类似 File.listFiles()）
directory?.listFiles()?.forEach { docFile ->
    // getName() 获取文件名
    val name = docFile.name
    // getType() 获取 MIME 类型
    val mimeType = docFile.type
    // isDirectory() 判断是否为子目录
    val isDir = docFile.isDirectory
    // length() 获取文件大小
    val size = docFile.length()
}
 
// 在目录中创建新文件（类似 File("dir", "name").createNewFile()）
val newFile = directory?.createFile("text/plain", "notes")
// 创建子目录（类似 File("dir", "subdir").mkdir()）
val subDir = directory?.createDirectory("backup")
 
// 读取文件内容：仍然需要通过 ContentResolver
newFile?.uri?.let { fileUri ->
    contentResolver.openInputStream(fileUri)?.use { /* 读取 */ }
}

<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
<map>
    <!-- String 类型：标签为 string，name 属性为 key，文本内容为 value -->
    <string name="username">Alice</string>
    <!-- int 类型：标签为 int，value 属性直接存储数值 -->
    <int name="login_count" value="5" />
    <!-- boolean 类型：标签为 boolean，value 属性为 true/false -->
    <boolean name="is_vip" value="true" />
    <!-- long 类型 -->
    <long name="last_login_ts" value="1717200000000" />
    <!-- float 类型 -->
    <float name="score" value="95.5" />
    <!-- StringSet 类型：外层为 set 标签，内层为多个 string 子标签 -->
    <set name="tags">
        <string>android</string>
        <string>kotlin</string>
    </set>
</map>

// ContextImpl.java 核心结构（简化）
 
// 第一级缓存：packageName -> (fileName -> SharedPreferencesImpl)
// 静态变量，所有 ContextImpl 实例共享
private static ArrayMap<String, ArrayMap<String, SharedPreferencesImpl>>
        sSharedPrefsCache;
 
@Override
public SharedPreferences getSharedPreferences(String name, int mode) {
    // 先从缓存中查找
    synchronized (ContextImpl.class) {
        // 获取当前包名对应的内层 Map
        ArrayMap<String, SharedPreferencesImpl> packagePrefs =
                sSharedPrefsCache.get(getPackageName());
        if (packagePrefs == null) {
            // 首次访问该包名，创建内层 Map
            packagePrefs = new ArrayMap<>();
            sSharedPrefsCache.put(getPackageName(), packagePrefs);
        }
        // 以文件名为 key 查找已有实例
        SharedPreferencesImpl sp = packagePrefs.get(name);
        if (sp == null) {
            // 缓存未命中：创建新实例，触发磁盘文件加载
            File prefsFile = getSharedPreferencesPath(name);
            sp = new SharedPreferencesImpl(prefsFile, mode);
            packagePrefs.put(name, sp);
        }
        return sp;
    }
}

// SharedPreferencesImpl.java（简化）
 
// 内存中保存全部键值对的 Map
private Map<String, Object> mMap;
// 标记磁盘文件是否已加载完成
private boolean mLoaded = false;
 
SharedPreferencesImpl(File file, int mode) {
    mFile = file;               // 指向 shared_prefs/xxx.xml
    mBackupFile = makeBackupFile(file); // 备份文件 xxx.xml.bak
    mMode = mode;
    mLoaded = false;
    mMap = null;
    startLoadFromDisk();        // 立即启动异步加载
}
 
private void startLoadFromDisk() {
    synchronized (mLock) {
        mLoaded = false;        // 标记"尚未加载完成"
    }
    // 在子线程中执行真正的磁盘读取
    new Thread("SharedPreferencesImpl-load") {
        public void run() {
            loadFromDisk();     // 核心：解析 XML -> mMap
        }
    }.start();
}
 
private void loadFromDisk() {
    synchronized (mLock) {
        if (mLoaded) return;    // 防止重复加载
    }
    Map<String, Object> map = null;
    // ... 文件存在性检查、备份恢复等逻辑 ...
    // 使用 XmlUtils.readMapXml() 将整个 XML 文件解析为 HashMap
    map = (Map<String, Object>) XmlUtils.readMapXml(str);
 
    synchronized (mLock) {
        mLoaded = true;         // 标记加载完成
        mMap = map;             // 将解析结果赋给内存缓存
        mLock.notifyAll();      // 唤醒所有因 getXxx() 而阻塞的线程
    }
}

@Override
public String getString(String key, @Nullable String defValue) {
    synchronized (mLock) {
        awaitLoadedLocked();    // 如果还没加载完，阻塞等待
        // 直接从内存 Map 中读取，无磁盘 I/O
        String v = (String) mMap.get(key);
        return v != null ? v : defValue;
    }
}
 
private void awaitLoadedLocked() {
    while (!mLoaded) {
        try {
            mLock.wait();       // 阻塞当前线程，等待 loadFromDisk 通知
        } catch (InterruptedException unused) {
        }
    }
}

// SharedPreferencesImpl.EditorImpl（简化）
public final class EditorImpl implements SharedPreferences.Editor {
    // Editor 内部维护的"待修改"集合
    private final Map<String, Object> mModified = new HashMap<>();
    private boolean mClear = false; // 是否标记了 clear()
 
    @Override
    public Editor putString(String key, String value) {
        synchronized (mEditorLock) {
            // 仅仅放入 mModified，尚未写入 mMap 或磁盘
            mModified.put(key, value);
            return this;
        }
    }
 
    @Override
    public Editor remove(String key) {
        synchronized (mEditorLock) {
            // 用特殊占位符 this 表示"删除"
            mModified.put(key, this);
            return this;
        }
    }
}

private MemoryCommitResult commitToMemory() {
    synchronized (mLock) {
        Map<String, Object> mapToWriteToDisk = mMap;
        // 如果调用了 clear()，先清空内存 Map
        if (mClear) {
            mMap.clear();
            mClear = false;
        }
        // 遍历 mModified，逐个合并到 mMap
        for (Map.Entry<String, Object> e : mModified.entrySet()) {
            String k = e.getKey();
            Object v = e.getValue();
            if (v == this) {     // 特殊占位符 -> 删除
                mMap.remove(k);
            } else {
                mMap.put(k, v);  // 新增或覆盖
            }
        }
        mModified.clear();
        // 返回的 mapToWriteToDisk 就是整个 mMap 的引用
        return new MemoryCommitResult(..., mapToWriteToDisk, ...);
    }
}

// ✅ 按模块拆分，各文件保持小体量
// 用户配置（登录态、昵称等），通常只有几个 key
val userPrefs = context.getSharedPreferences("user_prefs", Context.MODE_PRIVATE)
 
// 功能开关（A/B 实验、Feature Flag），独立管理
val featurePrefs = context.getSharedPreferences("feature_flags", Context.MODE_PRIVATE)
 
// 缓存类数据（上次刷新时间等），可随时清理
val cachePrefs = context.getSharedPreferences("cache_prefs", Context.MODE_PRIVATE)
 
// ❌ 反模式：所有数据塞进一个文件
val everything = context.getSharedPreferences("app_prefs", Context.MODE_PRIVATE)

// ❌ 反模式：在循环中多次 apply，每次都触发全量写入
for (item in itemList) {
    prefs.edit()                     // 每次循环都创建新 Editor
        .putString(item.key, item.value) // 只放入一个 kv
        .apply()                     // 触发一次完整的 XML 全量序列化
}
 
// ✅ 正确做法：批量操作，一次提交
prefs.edit().apply {                 // Kotlin 扩展函数，使用同一个 Editor
    for (item in itemList) {
        putString(item.key, item.value)  // 所有修改暂存到 mModified
    }
}.apply()                           // 只触发一次全量写入

@Override
public boolean commit() {
    // 第一步：将 mModified 合并到 mMap（内存操作，很快）
    MemoryCommitResult mcr = commitToMemory();
    // 第二步：在当前线程同步执行磁盘写入
    SharedPreferencesImpl.this.enqueueDiskWrite(mcr, null /* 传 null 表示同步 */);
    try {
        // 阻塞等待写入完成（对于同步写入，这里其实立即返回）
        mcr.writtenToDiskLatch.await();
    } catch (InterruptedException e) {
        return false;
    }
    // 通知已注册的 OnSharedPreferenceChangeListener
    notifyListeners(mcr);
    // 返回写入是否成功
    return mcr.writeToDiskResult;
}

@Override
public void apply() {
    // 第一步：同样先将 mModified 合并到 mMap（内存操作）
    final MemoryCommitResult mcr = commitToMemory();
 
    // 创建一个 Runnable，执行后表示"等待写盘完成"
    final Runnable awaitCommit = new Runnable() {
        @Override
        public void run() {
            try {
                // 阻塞直到磁盘写入完成
                mcr.writtenToDiskLatch.await();
            } catch (InterruptedException ignored) {
            }
        }
    };
 
    // ⚠️ 关键：将 awaitCommit 加入 QueuedWork 的 finisher 队列
    QueuedWork.addFinisher(awaitCommit);
 
    // 第二步：将磁盘写入任务投递到 QueuedWork 的单线程池中异步执行
    SharedPreferencesImpl.this.enqueueDiskWrite(mcr, postWriteRunnable);
    // apply() 立即返回，不阻塞调用线程
}

// ActivityThread.java 中的调用路径
private void handleStopActivity(IBinder token, ...) {
    // ...
    // ⚠️ 在 onStop() 流程中强制等待所有未完成的 apply 写盘
    QueuedWork.waitToFinish();
    // ...
}

// QueuedWork.java（简化）
public static void waitToFinish() {
    // 在主线程上执行！
    try {
        // 先尝试直接处理所有排队的磁盘写入任务
        processPendingWork();
    } finally {
        // 然后逐个等待 finisher 完成
        for (Runnable finisher : sFinishers) {
            finisher.run(); // 阻塞主线程，直到对应的 apply 写盘完成
        }
        sFinishers.clear();
    }
}

class TrackingActivity : AppCompatActivity() {
 
    // ❌ 危险：在页面交互过程中频繁 apply
    private fun onUserScroll(position: Int) {
        // 用户每次滑动都记录位置，假设每秒触发 5-10 次
        getSharedPreferences("scroll_state", MODE_PRIVATE)
            .edit()
            .putInt("last_position", position)  // 只修改一个 int
            .apply()                            // 每次都触发全量写入排队
    }
 
    // 当用户按 Back 键或系统回收 Activity 时
    // handleStopActivity -> QueuedWork.waitToFinish()
    // 主线程需要等待之前积攒的几十次写盘任务全部完成
    // SP 文件越大，每次全量写入越慢，ANR 风险越高
}

class ScrollStateManager(context: Context) {
    // 获取 SharedPreferences 实例
    private val prefs = context.getSharedPreferences("scroll_state", Context.MODE_PRIVATE)
    // 使用 Handler 实现防抖，延迟 500ms 写入
    private val handler = Handler(Looper.getMainLooper())
    // 暂存最新的滚动位置
    private var pendingPosition: Int = -1
 
    // 防抖写入 Runnable
    private val writeRunnable = Runnable {
        prefs.edit()
            .putInt("last_position", pendingPosition)  // 只写入最新的位置
            .apply()                                   // 500ms 内只触发一次 apply
    }
 
    fun onUserScroll(position: Int) {
        pendingPosition = position          // 更新暂存值
        handler.removeCallbacks(writeRunnable)  // 移除之前的延迟任务
        handler.postDelayed(writeRunnable, 500) // 500ms 后再写入
    }
}

// DataStore 写入：完全异步，无 QueuedWork 依赖
viewModelScope.launch {
    // 在 Dispatchers.IO 上执行，不阻塞主线程
    context.dataStore.edit { preferences ->
        preferences[SCROLL_POSITION_KEY] = position  // 类型安全的写入
    }
}

// 在后台线程中同步写入，绕过 QueuedWork
lifecycleScope.launch(Dispatchers.IO) {
    prefs.edit()
        .putString("key", "value")
        .commit()   // 同步写盘，但因为在 IO 线程，不影响主线程
}

// build.gradle.kts
dependencies {
    // Preferences DataStore 核心依赖
    implementation("androidx.datastore:datastore-preferences:1.1.1")
}

// 在 Kotlin 文件顶层声明，确保全局唯一
// "user_settings" 是存储文件的名称（不需要加后缀）
// 底层会自动在 files/datastore/ 目录下创建 user_settings.preferences_pb
val Context.userSettingsDataStore: DataStore<Preferences> by preferencesDataStore(
    name = "user_settings"  // 存储文件名，映射为 user_settings.preferences_pb
)

// 定义各种类型的 Key
// 每个 Key 都绑定了特定的值类型，读取时无需强转
val DARK_MODE_KEY = booleanPreferencesKey("dark_mode")       // Boolean 类型
val FONT_SIZE_KEY = intPreferencesKey("font_size")           // Int 类型
val USERNAME_KEY = stringPreferencesKey("username")           // String 类型
val VOLUME_KEY = floatPreferencesKey("volume")               // Float 类型
val LAST_LOGIN_KEY = longPreferencesKey("last_login")        // Long 类型
val TAGS_KEY = stringSetPreferencesKey("tags")               // Set<String> 类型
val SCORE_KEY = doublePreferencesKey("score")                // Double 类型

// 在 ViewModel 中读取 DataStore 数据
class SettingsViewModel(application: Application) : AndroidViewModel(application) {
 
    // 通过 map 操作符，从完整的 Preferences 快照中提取单个字段
    // .data 属性返回 Flow<Preferences>，它是冷流（Cold Flow）
    val darkModeFlow: Flow<Boolean> = application.userSettingsDataStore.data
        .catch { exception ->
            // 读取文件时如果发生 IO 异常，发射默认的空 Preferences
            // 这是 DataStore 官方推荐的异常处理模式
            if (exception is IOException) {
                emit(emptyPreferences())  // 发射空的 Preferences 作为兜底
            } else {
                throw exception           // 非 IO 异常继续向上抛出
            }
        }
        .map { preferences ->
            // 使用类型化的 Key 读取，返回值自动推断为 Boolean?
            // 如果 key 不存在，返回 null，此处用 Elvis 运算符给默认值
            preferences[DARK_MODE_KEY] ?: false
        }
 
    // 也可以一次性提取多个字段，组合成一个数据类
    val settingsFlow: Flow<UserSettings> = application.userSettingsDataStore.data
        .catch { e ->
            if (e is IOException) emit(emptyPreferences())
            else throw e
        }
        .map { prefs ->
            // 将多个键值对映射为一个不可变的数据类
            UserSettings(
                darkMode = prefs[DARK_MODE_KEY] ?: false,    // 默认关闭暗黑模式
                fontSize = prefs[FONT_SIZE_KEY] ?: 14,       // 默认字号 14
                username = prefs[USERNAME_KEY] ?: "Guest"     // 默认用户名
            )
        }
}
 
// 用于承载设置状态的数据类
data class UserSettings(
    val darkMode: Boolean,  // 是否开启暗黑模式
    val fontSize: Int,      // 字体大小
    val username: String    // 用户名
)

@Composable
fun SettingsScreen(viewModel: SettingsViewModel = viewModel()) {
    // collectAsState 会自动管理协程的生命周期
    // 当 Composable 离开组合时，收集自动取消
    val darkMode by viewModel.darkModeFlow.collectAsStateWithLifecycle(
        initialValue = false  // Flow 尚未发射第一个值时的默认状态
    )
 
    // 根据 Flow 的最新值渲染 UI
    Switch(
        checked = darkMode,          // 响应式绑定
        onCheckedChange = { newValue ->
            viewModel.setDarkMode(newValue)  // 触发写入
        }
    )
}

class SettingsViewModel(application: Application) : AndroidViewModel(application) {
 
    private val dataStore = application.userSettingsDataStore
 
    // 修改单个值
    fun setDarkMode(enabled: Boolean) {
        viewModelScope.launch {
            // edit 是 suspend 函数，必须在协程中调用
            // 它内部会获取 Mutex 锁，保证同一时刻只有一个写操作
            dataStore.edit { mutablePreferences ->
                // 直接用类型化的 Key 赋值
                mutablePreferences[DARK_MODE_KEY] = enabled
            }
            // edit 返回时，数据已经持久化到磁盘
        }
    }
 
    // 批量修改多个值（同一个事务）
    fun updateProfile(name: String, fontSize: Int) {
        viewModelScope.launch {
            dataStore.edit { prefs ->
                // 同一个 edit lambda 中的所有修改是原子的
                // 要么全部成功写入，要么全部不写入
                prefs[USERNAME_KEY] = name        // 修改用户名
                prefs[FONT_SIZE_KEY] = fontSize   // 修改字号
            }
        }
    }
 
    // 删除特定键
    fun clearUsername() {
        viewModelScope.launch {
            dataStore.edit { prefs ->
                prefs.remove(USERNAME_KEY)  // 移除指定 key
            }
        }
    }
 
    // 清空所有数据
    fun clearAll() {
        viewModelScope.launch {
            dataStore.edit { prefs ->
                prefs.clear()  // 清空所有键值对
            }
        }
    }
}

// 在创建 DataStore 实例时传入 produceMigrations 参数
val Context.userSettingsDataStore: DataStore<Preferences> by preferencesDataStore(
    name = "user_settings",
    produceMigrations = { context ->
        // 返回一个 Migration 列表
        listOf(
            SharedPreferencesMigration(
                context = context,
                // 需要迁移的 SharedPreferences 文件名（不含 .xml 后缀）
                sharedPreferencesName = "old_user_prefs"
            )
        )
    }
)

// build.gradle.kts (模块级)
plugins {
    id("com.google.protobuf") version "0.9.4"  // Protobuf Gradle 插件
}
 
dependencies {
    // Proto DataStore 核心依赖（注意不是 datastore-preferences）
    implementation("androidx.datastore:datastore:1.1.1")
    // Protobuf 的 Java Lite 运行时（Android 推荐 Lite 版，体积更小）
    implementation("com.google.protobuf:protobuf-javalite:4.26.1")
}
 
// 配置 Protobuf 编译器
protobuf {
    protoc {
        // 指定 protoc 编译器版本
        artifact = "com.google.protobuf:protoc:4.26.1"
    }
    generateProtoTasks {
        all().forEach { task ->
            task.builtins {
                // 生成 Java Lite 代码（比标准 Java 代码体积小约 10 倍）
                create("java") {
                    option("lite")
                }
            }
        }
    }
}

// src/main/proto/user_settings.proto
// Proto3 语法版本，推荐使用 proto3（更简洁）
syntax = "proto3";
 
// 生成的 Java 类所在的包名
option java_package = "com.example.app.datastore";
// 生成的外部类名（Proto 会将所有 message 生成为此类的内部类）
option java_multiple_files = true;
 
// 定义通知配置（嵌套 message，映射为嵌套对象）
message NotificationConfig {
  bool push_enabled = 1;           // 字段编号 1：是否开启推送
  bool email_enabled = 2;          // 字段编号 2：是否开启邮件通知
  int32 quiet_hour_start = 3;      // 字段编号 3：免打扰开始时间（小时）
  int32 quiet_hour_end = 4;        // 字段编号 4：免打扰结束时间（小时）
}
 
// 定义主题模式枚举
enum ThemeMode {
  THEME_MODE_UNSPECIFIED = 0;      // Proto3 要求第一个枚举值必须为 0
  THEME_MODE_LIGHT = 1;            // 浅色模式
  THEME_MODE_DARK = 2;             // 深色模式
  THEME_MODE_SYSTEM = 3;           // 跟随系统
}
 
// 主 message：用户设置（这就是 DataStore 的存储单元）
message UserSettingsProto {
  string username = 1;                          // 用户名
  int32 font_size = 2;                          // 字号
  ThemeMode theme_mode = 3;                     // 主题模式（枚举）
  NotificationConfig notification = 4;          // 通知配置（嵌套对象）
  repeated string favorite_cities = 5;          // 收藏城市列表（repeated = 列表）
  int64 last_login_timestamp = 6;               // 上次登录时间戳
}

// UserSettingsSerializer.kt
// 实现 Serializer 接口，泛型为 Protobuf 生成的类
object UserSettingsSerializer : Serializer<UserSettingsProto> {
 
    // 定义默认值：当文件不存在或为空时，DataStore 返回此默认实例
    // getDefaultInstance() 是 Protobuf 生成类的方法，返回所有字段为默认值的实例
    override val defaultValue: UserSettingsProto =
        UserSettingsProto.getDefaultInstance()
 
    // 从 InputStream 读取并反序列化为 Protobuf 对象
    override suspend fun readFrom(input: InputStream): UserSettingsProto {
        try {
            // parseFrom 是 Protobuf Lite 生成的静态方法
            // 直接从字节流中高效反序列化
            return UserSettingsProto.parseFrom(input)
        } catch (exception: InvalidProtocolBufferException) {
            // 如果文件内容损坏，抛出 CorruptionException
            // DataStore 框架会捕获此异常并触发恢复机制
            throw CorruptionException("Cannot read proto.", exception)
        }
    }
 
    // 将 Protobuf 对象序列化后写入 OutputStream
    override suspend fun writeTo(t: UserSettingsProto, output: OutputStream) {
        // writeTo 是 Protobuf 生成类的方法
        // 直接将二进制编码写入输出流
        t.writeTo(output)
    }
}

// 文件顶层声明，确保单例
val Context.userSettingsProtoStore: DataStore<UserSettingsProto> by dataStore(
    fileName = "user_settings.pb",                    // 存储文件名
    serializer = UserSettingsSerializer,              // 序列化器
    corruptionHandler = ReplaceFileCorruptionHandler(
        // 文件损坏时的恢复策略：返回默认值（相当于重置设置）
        produceNewData = { UserSettingsProto.getDefaultInstance() }
    )
)

class SettingsViewModel(application: Application) : AndroidViewModel(application) {
 
    private val protoStore = application.userSettingsProtoStore
 
    // 读取：通过 Flow 观察整个设置对象
    val settingsFlow: Flow<UserSettingsProto> = protoStore.data
        .catch { e ->
            if (e is IOException) {
                // IO 异常时发射默认实例
                emit(UserSettingsProto.getDefaultInstance())
            } else throw e
        }
 
    // 提取单个字段
    val themeModeFlow: Flow<ThemeMode> = settingsFlow.map { settings ->
        // 直接通过属性访问，完全类型安全，IDE 有自动补全
        settings.themeMode
    }
 
    // 写入：使用 updateData（对应 Preferences DataStore 的 edit）
    fun setThemeMode(mode: ThemeMode) {
        viewModelScope.launch {
            protoStore.updateData { currentSettings ->
                // toBuilder() 创建可变的 Builder
                // setThemeMode 设置新值
                // build() 返回新的不可变实例
                currentSettings.toBuilder()
                    .setThemeMode(mode)       // 设置主题模式
                    .build()                  // 构建新的不可变对象
            }
        }
    }
 
    // 修改嵌套对象
    fun updateNotificationConfig(pushEnabled: Boolean, emailEnabled: Boolean) {
        viewModelScope.launch {
            protoStore.updateData { current ->
                current.toBuilder()
                    .setNotification(
                        // 在已有通知配置基础上修改
                        current.notification.toBuilder()
                            .setPushEnabled(pushEnabled)      // 修改推送开关
                            .setEmailEnabled(emailEnabled)    // 修改邮件开关
                            .build()
                    )
                    .build()
            }
        }
    }
 
    // 向列表中添加元素
    fun addFavoriteCity(city: String) {
        viewModelScope.launch {
            protoStore.updateData { current ->
                current.toBuilder()
                    .addFavoriteCities(city)  // repeated 字段使用 addXxx 方法
                    .build()
            }
        }
    }
}

// SharedPreferences 的并发问题示例
// 假设当前 counter = 5
 
// 协程 A                          // 协程 B
val current = prefs.getInt(         val current = prefs.getInt(
    "counter", 0)  // 读到 5           "counter", 0)  // 也读到 5
prefs.edit()                        prefs.edit()
    .putInt("counter",                  .putInt("counter",
        current + 1)  // 写 6               current + 1)  // 也写 6
    .apply()                            .apply()
 
// 期望结果：7，实际结果：6 —— 经典的 Lost Update 问题！

// DataStore 的事务安全
// 假设当前 counter = 5
 
// 协程 A（先获取到 Mutex）
dataStore.edit { prefs ->
    // 在 Mutex 保护下读取当前值
    val current = prefs[COUNTER_KEY] ?: 0  // 读到 5
    prefs[COUNTER_KEY] = current + 1       // 写 6
}
// Mutex 释放，数据已持久化
 
// 协程 B（等待 Mutex 后执行）
dataStore.edit { prefs ->
    // 此时读到的是协程 A 写入后的最新值
    val current = prefs[COUNTER_KEY] ?: 0  // 读到 6
    prefs[COUNTER_KEY] = current + 1       // 写 7
}
 
// 最终结果：7 ✓

// ❌ 错误：在 edit lambda 中执行有副作用的操作
dataStore.edit { prefs ->
    prefs[COUNTER_KEY] = (prefs[COUNTER_KEY] ?: 0) + 1
    sendAnalyticsEvent("counter_incremented")  // 可能被执行多次！
}
 
// ✅ 正确：将副作用移到 edit 之外
dataStore.edit { prefs ->
    prefs[COUNTER_KEY] = (prefs[COUNTER_KEY] ?: 0) + 1
}
sendAnalyticsEvent("counter_incremented")  // edit 成功后执行一次

// DataStore 内部默认使用的协程作用域
// 这是 DataStore 源码中的简化表示
internal val scope: CoroutineScope = CoroutineScope(
    Dispatchers.IO                   // IO 调度器：适合磁盘/网络操作
        + SupervisorJob()            // SupervisorJob：子协程失败不影响其他
)

val Context.customDataStore: DataStore<Preferences> by preferencesDataStore(
    name = "custom_settings",
    // 自定义协程作用域
    scope = CoroutineScope(
        Dispatchers.IO                // 仍然使用 IO 调度器
            + SupervisorJob()         // SupervisorJob 是推荐实践
    )
)

// ❌ 危险：在主线程的 runBlocking 中读取 DataStore
// 这会阻塞主线程，等同于退回到 SharedPreferences 的同步读取模式
val value = runBlocking {
    context.userSettingsDataStore.data.first()
}
 
// ✅ 正确：在协程作用域中异步读取
lifecycleScope.launch {
    val value = context.userSettingsDataStore.data.first()
    // 使用 value 更新 UI
}

// ❌ 严重错误：两个不同的 DataStore 实例指向同一个文件
val store1 = context.createDataStore("settings")  // 实例 1
val store2 = context.createDataStore("settings")  // 实例 2
 
// 它们各自有独立的内存缓存和 Mutex，但共享同一个磁盘文件
// 这会导致数据竞争、缓存不一致、潜在的文件损坏

// 多进程 DataStore 创建（DataStore 1.1.0+）
val multiProcessStore: DataStore<Preferences> = MultiProcessDataStoreFactory.create(
    serializer = PreferencesSerializer,          // 序列化器
    produceFile = {
        // 必须使用所有进程都能访问的路径
        File(context.filesDir, "datastore/multi_process_settings.preferences_pb")
    }
)

dataStore.edit { prefs ->
    val count = prefs[VIEW_COUNT_KEY] ?: 0
    prefs[VIEW_COUNT_KEY] = count + 1
    analyticsService.trackEvent("page_viewed")  // 发送统计事件
}

// ❌ 旧写法：直接使用 file:// URI（Android 7.0+ 会崩溃）
// 创建一个指向应用私有目录下照片文件的 File 对象
val photoFile = File(getExternalFilesDir(Environment.DIRECTORY_PICTURES), "photo.jpg")
// 直接将文件绝对路径转换为 file:// URI
val photoUri = Uri.fromFile(photoFile)
// 构造一个 Intent，把 file:// URI 传递给系统相机
val intent = Intent(MediaStore.ACTION_IMAGE_CAPTURE)
// 相机 App 拿到的是类似 file:///storage/emulated/0/Android/data/com.example/files/Pictures/photo.jpg
intent.putExtra(MediaStore.EXTRA_OUTPUT, photoUri)
// 启动相机 Activity
startActivityForResult(intent, REQUEST_TAKE_PHOTO)