From dc8a9469758f82cb1d48eb8b60118d0e614fe71e Mon Sep 17 00:00:00 2001
From: sunxyw <31698606+sunxyw@users.noreply.github.com>
Date: Tue, 17 Jan 2023 17:16:00 +0800
Subject: [PATCH] add cache docs (#261)

* add cache docs

* change zmredis to kvredis and fix typo

Co-authored-by: crazywhalecc <jesse2061@outlook.com>
---
 docs/.vuepress/config.js       |  1 +
 docs/components/store/cache.md | 65 ++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)
 create mode 100644 docs/components/store/cache.md

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 24a53bb9..fb403de1 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -99,6 +99,7 @@ module.exports = {
                     sidebarDepth: 2,
                     children: [
                         'store/file-system',
+                        'store/cache',
                     ]
                 }
             ],
diff --git a/docs/components/store/cache.md b/docs/components/store/cache.md
new file mode 100644
index 00000000..38ebd704
--- /dev/null
+++ b/docs/components/store/cache.md
@@ -0,0 +1,65 @@
+# KV 缓存
+
+在部分场景中，我们会希望将一些数据缓存起来，以便后续使用，例如查询数据或处理任务的操作，通过缓存数据以避免反复查询，加速处理。
+
+这些缓存数据通常储存在极快的存储系统中，例如 Redis，Memcached 等。
+
+框架在 PSR-16 规范的基础上扩展出了 `KVInterface` 接口，提供使用特定缓存库的能力。
+
+## 配置
+
+你可以通过 `global.php` 中的 `kv` 配置项来配置缓存库。
+
+```php
+/* KV 数据库的配置 */
+$config['kv'] = [
+    'use' => \LightCache::class,                        // 默认在单进程模式下使用 LightCache，多进程需要使用 KVRedis
+    'light_cache_dir' => $config['data_dir'] . '/lc',   // 默认的 LightCache 保存持久化数据的位置
+    'light_cache_autosave_time' => 600,                 // LightCache 自动保存时间（秒）
+    'redis_config' => 'default',                        // 在使用 KVRedis 时使用的 redis 连接配置的名称
+];
+```
+
+## 支持驱动
+
+目前，框架内置了两种缓存库的驱动：
+
+- `LightCache`：单进程模式下默认使用的缓存库，使用文件系统作为存储介质，支持持久化。
+- `KVRedis`：多进程模式下使用的缓存库，使用 Redis 作为存储介质，不支持持久化（取决于 Redis 的配置）。
+
+你也可以通过实现 `KVInterface` 接口来自定义缓存库的驱动。
+
+## 使用
+
+你可以通过 `kv` 函数来获取缓存库的实例。
+
+```php
+kv()->set('key', 'value');
+```
+
+可以为 `kv` 函数传递一个参数来获取指定的缓存库。
+
+```php
+kv('user')->set('key', 'value');
+kv('user')->get('key', 'default_value'); // 返回 value
+```
+
+缓存组件完全遵循 PSR-16 规范，因此你可以参考 [PSR-16](https://www.php-fig.org/psr/psr-16/) 来使用缓存组件。
+
+## 使用场景
+
+KV 库常用于一些轻量级内容的存储，例如一些插件的配置项、运行状态、统计计数等场景。
+默认在单进程模式下使用的 `LightCache` 读写为全局变量模式，无任何 IO。
+多进程下如果选择 `KVRedis` 作为 KV 库驱动，则性能取决于和 Redis 服务器之间通信的性能。
+
+例如，在编写机器人插件时，需要初始化一个插件的配置项，假设是一个机器人管理员模块，需要设置当前的超级管理员 ID 号：
+
+```php
+#[\Init()]
+public function init()
+{
+    if (!kv('my-admin-plugin')->has('admin-id')) {
+        kv('my-admin-plugin')->set('admin-id', '456789');
+    }
+}
+```