{"id":29901634,"url":"https://github.com/BillyWei01/FastKV","last_synced_at":"2025-08-01T15:02:29.120Z","repository":{"id":40613246,"uuid":"416593131","full_name":"BillyWei01/FastKV","owner":"BillyWei01","description":"An efficient key-value storage library.","archived":false,"fork":false,"pushed_at":"2025-07-27T12:54:00.000Z","size":2990,"stargazers_count":381,"open_issues_count":0,"forks_count":42,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-07-27T14:51:55.647Z","etag":null,"topics":["android","java","key-value","storage"],"latest_commit_sha":null,"homepage":"https://juejin.cn/post/7018522454171582500","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BillyWei01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-13T04:50:27.000Z","updated_at":"2025-07-27T12:54:04.000Z","dependencies_parsed_at":"2023-02-19T06:00:42.747Z","dependency_job_id":"507854e2-4cd5-4780-bd19-bac75060fe01","html_url":"https://github.com/BillyWei01/FastKV","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/BillyWei01/FastKV","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BillyWei01%2FFastKV","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BillyWei01%2FFastKV/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BillyWei01%2FFastKV/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BillyWei01%2FFastKV/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BillyWei01","download_url":"https://codeload.github.com/BillyWei01/FastKV/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BillyWei01%2FFastKV/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267376337,"owners_count":24077298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","java","key-value","storage"],"created_at":"2025-08-01T15:01:38.745Z","updated_at":"2025-08-01T15:02:29.111Z","avatar_url":"https://github.com/BillyWei01.png","language":"Java","funding_links":[],"categories":["Java","数据库"],"sub_categories":[],"readme":"# FastKV\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.billywei01/fastkv)](https://search.maven.org/artifact/io.github.billywei01/fastkv) | [English](README_EN.md) | [架构设计](ARCHITECTURE.md)\n\n## 1. 概述\nFastKV是用Java编写的高效可靠的key-value存储库，专为Android平台优化。\n\n###  核心特性\n\n#### 1. 高性能读写\n- **二进制编码**：采用紧凑的二进制格式，相比XML等文本编码体积更小\n- **增量更新**：记录key-value的精确偏移量，支持原地更新，避免全量重写\n- **mmap内存映射**：默认使用mmap技术，写入数据直接映射到内存\n- **垃圾回收**：自动清理无效数据，保持存储空间紧凑\n\n#### 2. 多种写入模式\n- **NON_BLOCKING**：非阻塞模式，通过mmap直接写入内存，性能最高\n- **ASYNC_BLOCKING**：异步阻塞模式，后台线程写入磁盘，类似SharedPreferences.apply()\n- **SYNC_BLOCKING**：同步阻塞模式，立即写入磁盘，类似SharedPreferences.commit()\n\n#### 3. 丰富的数据类型支持\n- **基础类型**：boolean, int, float, long, double, String\n- **字节数组**：byte[]，支持二进制数据存储\n- **字符串集合**：Set\u003cString\u003e，完全兼容SharedPreferences\n- **自定义对象**：通过FastEncoder接口支持任意对象序列化\n\n\n#### 4. 数据安全保障\n- **双文件备份**：A/B文件互为备份，确保数据不丢失\n- **校验和保护**：每次读取都验证数据完整性\n- **原子操作**：写入操作具有原子性，避免数据损坏\n- **自动降级**：mmap失败时自动切换到阻塞模式\n\n#### 5. 数据加密支持\n- **可插拔加密**：支持注入自定义加密实现\n- **透明加解密**：加密在数据写入前执行，解密在数据解析时执行\n- **加密迁移**：支持从明文到密文的平滑迁移\n- **性能优化**：缓存解密后的数据，不影响读取性能\n\n#### 6. 开发友好\n- **兼容性好**：实现SharedPreferences接口，便于迁移\n- **迁移工具**：提供adapt()方法自动迁移SharedPreferences数据\n- **丰富API**：支持批量操作、监听器等\n- **类型安全**：编译时类型检查，避免运行时类型错误\n\n#### 7. 稳定可靠\n- **容错机制**：基本的错误检测和自动恢复\n- **向前兼容**：新版本可读取旧版本数据\n- **异常处理**：基本的异常处理和日志记录\n\n#### 8. 轻量高效\n- **体积小**：纯Java实现，编译后仅数十KB\n- **内存友好**：减少不必要的对象创建\n- **启动快**：异步加载，支持多文件并发加载\n\n\n## 2. 使用方法\n\n### 2.1 导入\n\n```gradle\ndependencies {\n    implementation 'io.github.billywei01:fastkv:3.0.1'\n}\n```\n\n备注：\u003cbr\u003e\n在2.x版本，FastKV支持多进程存储，但3.x版本开始不再支持多进程。\u003cbr\u003e\n如需多进程存储，请使用[MPFastKV](https://github.com/BillyWei01/FastKV/tree/mpfastkv) \u003cbr\u003e\n\n### 2.2 初始化\n```kotlin\n// 可选：设置全局配置\nFastKVConfig.setLogger(FastKVLogger)\nFastKVConfig.setExecutor(Dispatchers.IO.asExecutor())\n```\n\n初始化可以按需设置日志接口和Executor：\n- 如果不传入Executor，FastKV会自己构建一个CachedThreadPool\n- 如果传入用户自己的Executor，需要确保Executor的并发调度能力\n\n### 2.3 基本用法\n\n```java\n// 使用Context构造（推荐）\nFastKV kv = new FastKV.Builder(context, \"user_data\").build();\n\n// 或使用自定义路径\nFastKV kv = new FastKV.Builder(path, \"user_data\").build();\n\n// 基本读写操作\nif (!kv.getBoolean(\"first_launch\")) {\n    kv.putBoolean(\"first_launch\", true);\n}\n\nint count = kv.getInt(\"launch_count\");\nkv.putInt(\"launch_count\", count + 1);\n\n// 支持链式调用\nkv.putString(\"user_name\", \"张三\")\n  .putInt(\"user_age\", 25)\n  .putFloat(\"user_score\", 89.5f);\n```\n\n### 2.4 可选配置\n\n```java\nFastKV kv = new FastKV.Builder(context, \"secure_data\")\n    .encoder(new FastEncoder[]{CustomObjectEncoder.INSTANCE})  // 自定义编码器\n    .cipher(new AESCipher())                                   // 数据加密\n    .blocking()                                                // 同步阻塞模式\n    .build();\n```\n\n### 2.5 存储自定义对象\n\n```java\n// 1. 实现FastEncoder接口\npublic class UserEncoder implements FastEncoder\u003cUser\u003e {\n    @Override\n    public String tag() {\n        return \"User\";\n    }\n    \n    @Override\n    public byte[] encode(User user) {\n        // 序列化逻辑\n        return userToBytes(user);\n    }\n    \n    @Override\n    public User decode(byte[] bytes, int offset, int length) {\n        // 反序列化逻辑\n        return bytesToUser(bytes, offset, length);\n    }\n}\n\n// 2. 注册编码器并使用\nFastEncoder\u003c?\u003e[] encoders = {new UserEncoder()};\nFastKV kv = new FastKV.Builder(context, \"user_data\")\n    .encoder(encoders)\n    .build();\n\n// 3. 存储和读取对象\nUser user = new User(\"张三\", 25);\nkv.putObject(\"current_user\", user, new UserEncoder());\nUser savedUser = kv.getObject(\"current_user\");\n```\n\n推荐使用[Packable](https://github.com/BillyWei01/Packable)框架进行对象序列化。\n\n### 2.6 数据加密\n\n```java\n// 实现FastCipher接口\npublic class AESCipher implements FastCipher {\n    @Override\n    public byte[] encrypt(byte[] src) {\n        // 加密实现\n        return encryptWithAES(src);\n    }\n    \n    @Override\n    public byte[] decrypt(byte[] dst) {\n        // 解密实现\n        return decryptWithAES(dst);\n    }\n    \n    // 其他加密方法...\n}\n\n// 使用加密\nFastKV kv = new FastKV.Builder(context, \"secure_data\")\n    .cipher(new AESCipher())\n    .build();\n```\n\n### 2.7 批量操作\n\n```java\n// 批量写入\nMap\u003cString, Object\u003e data = new HashMap\u003c\u003e();\ndata.put(\"name\", \"张三\");\ndata.put(\"age\", 25);\ndata.put(\"score\", 89.5f);\ndata.put(\"active\", true);\n\nkv.putAll(data);\n\n// 批量读取\nMap\u003cString, Object\u003e allData = kv.getAll();\n\n// 事务控制（阻塞模式）\nkv.disableAutoCommit();\nkv.putString(\"key1\", \"value1\");\nkv.putString(\"key2\", \"value2\");\nkv.commit(); // 一次性提交所有更改\n```\n\n### 2.8 迁移SharedPreferences\n\n```java\npublic class SpCase {\n    public static final String NAME = \"common_store\";\n    \n    // 替换原有的SharedPreferences获取方式\n    // public static final SharedPreferences preferences = context.getSharedPreferences(NAME, Context.MODE_PRIVATE);\n    \n    // 使用FastKV并自动迁移数据\n    public static final SharedPreferences preferences = FastKV.adapt(context, NAME);\n}\n```\n\n### 2.9 监听数据变化\n\n```java\nkv.registerOnSharedPreferenceChangeListener(new SharedPreferences.OnSharedPreferenceChangeListener() {\n    @Override\n    public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) {\n        // 处理数据变化\n        System.out.println(\"Key changed: \" + key);\n    }\n});\n```\n\n### 2.10 Kotlin委托属性\n\nKotlin是兼容Java的，所以Kotlin下也可以直接用FastKV或者SharedPreferences的API。\u003cbr\u003e\n此外，Kotlin还提供了“委托属性”这一语法糖，可以用于改进key-value API访问。\u003cbr\u003e\n可参考：[KVData](https://github.com/BillyWei01/FastKV/blob/main/app/src/main/java/io/fastkv/fastkvdemo/fastkv/kvdelegate/KVData.kt) \u003cbr\u003e\n具体细节可参考: [一种好用的KV存储封装方案](https://juejin.cn/post/7323449163420303370)\n\n### 2.11 注意事项\n\n1. **路径和名称一致性**：不同版本之间不要改变路径和名字，否则会打开不同的文件\n2. **加密器一致性**：如果使用了Cipher，不要更换，否则无法解析数据（从无加密到加密是可以的）\n3. **类型一致性**：同一个key对应的value类型应保持一致\n\n## 3. 性能测试\n\n### 测试环境\n- **测试数据**：600+个真实key-value数据（经过随机混淆）\n- **测试设备**：华为P30 Pro\n- **测试方法**：正态分布输入序列，多次测试取平均值\n\n### 测试结果\n\n**写入性能（毫秒）**：\n\n| 数据量 | 25 | 50 | 100 | 200 | 400 | 600 |\n|--------|----|----|-----|-----|-----|-----|\n| SP-commit | 114 | 172 | 411 | 666 | 2556 | 5344 |\n| DataStore | 231 | 625 | 1717 | 4421 | 7629 | 13639 |\n| SQLiteKV | 192 | 382 | 1025 | 1565 | 4279 | 5034 |\n| SP-apply | 3 | 9 | 35 | 118 | 344 | 516 |\n| MMKV | 4 | 8 | 5 | 8 | 10 | 9 |\n| **FastKV** | **3** | **6** | **4** | **6** | **8** | **10** |\n\n**读取性能（毫秒）**：\n\n| 数据量 | 25 | 50 | 100 | 200 | 400 | 600 |\n|--------|----|----|-----|-----|-----|-----|\n| SP-commit | 1 | 3 | 2 | 1 | 2 | 3 |\n| DataStore | 57 | 76 | 115 | 117 | 170 | 216 |\n| SQLiteKV | 96 | 161 | 265 | 417 | 767 | 1038 |\n| SP-apply | 0 | 1 | 0 | 1 | 3 | 3 |\n| MMKV | 0 | 1 | 1 | 5 | 8 | 11 |\n| **FastKV** | **0** | **1** | **1** | **3** | **3** | **1** |\n\n### 性能优势\n- **写入速度**：与MMKV相当，比SharedPreferences显著更快\n- **读取速度**：与SharedPreferences相当，比DataStore更快\n- **启动速度**：异步加载，不阻塞应用启动\n\n## 4. 架构设计\n\n如果对 FastKV 的实现原理感兴趣，可参考[ARCHITECTURE.md](ARCHITECTURE.md)。\n\n## 5. 相关链接\n\n- **技术博客**：https://juejin.cn/post/7018522454171582500\n- **纯Java版本**：https://github.com/BillyWei01/FastKV-Java\n- **序列化框架**：https://github.com/BillyWei01/Packable\n\n## License\nSee the [LICENSE](LICENSE) file for license rights and limitations.\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBillyWei01%2FFastKV","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBillyWei01%2FFastKV","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBillyWei01%2FFastKV/lists"}