From 70d9c65698ff47891827ca666c81fe44d81370d0 Mon Sep 17 00:00:00 2001
From: guqing <38999863+guqing@users.noreply.github.com>
Date: Fri, 28 Jun 2024 15:04:58 +0800
Subject: [PATCH] docs: add detailed guide on how to use plugin settings (#375)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

### What this PR does?
新增关于如何使用插件配置的文档

see also https://github.com/halo-dev/halo/pull/6141

```release-note
None
```
---
 .../api-reference/server/setting-fetcher.md   | 139 ++++++++++++++++++
 sidebars.js                                   |   1 +
 2 files changed, 140 insertions(+)
 create mode 100644 docs/developer-guide/plugin/api-reference/server/setting-fetcher.md

diff --git a/docs/developer-guide/plugin/api-reference/server/setting-fetcher.md b/docs/developer-guide/plugin/api-reference/server/setting-fetcher.md
new file mode 100644
index 0000000..a572a39
--- /dev/null
+++ b/docs/developer-guide/plugin/api-reference/server/setting-fetcher.md
@@ -0,0 +1,139 @@
+---
+title: 获取插件配置
+description: 了解如何获取插件定义的设置表单对应的配置数据，以及如何在插件中使用配置数据。
+---
+
+插件的 `plugin.yaml` 中允许配置 `settingName` 和 `configMapName` 字段，用于定义插件的个性化设置。
+本文介绍如何获取插件定义的设置表单对应的配置数据，以及如何在插件中使用配置数据。
+
+## 概述
+
+Halo 提供了两个 Bean 用于获取插件配置数据：`SettingFetcher` 和 `ReactiveSettingFetcher`，分别用于同步和异步获取配置数据。
+
+以 `ReactiveSettingFetcher` 为例，提供了以下方法：
+
+```java
+public interface ReactiveSettingFetcher {
+
+    <T> Mono<T> fetch(String group, Class<T> clazz);
+
+    @NonNull
+    Mono<JsonNode> get(String group);
+
+    @NonNull
+    Mono<Map<String, JsonNode>> getValues();
+}
+```
+
+- `fetch` 方法用于获取指定分组的配置数据，并将其转换为指定的 Java 类型。
+- `get` 方法用于获取指定分组的配置数据，返回 `JsonNode` 类型。
+- `getValues` 方法用于获取所有配置数据，返回 `Map<String, JsonNode>` 类型，其中键为分组名称，值为配置对象。
+
+`ReactiveSettingFetcher` 和 `SettingFetcher` 底层都对配置数据进行了缓存，以提高性能，并且在配置变更时会自动刷新缓存，所以直接调用这些方法即可获取最新的配置数据。
+
+## 监听配置变更
+
+当用户修改插件配置时，可以通过监听 `PluginConfigUpdatedEvent` 事件，执行相应的操作。`PluginConfigUpdatedEvent` 包含了配置变更前后的数据，使插件能够对变化做出响应。
+
+```java
+public class PluginConfigUpdatedEvent extends ApplicationEvent {
+    private final Map<String, JsonNode> oldConfig;
+    private final Map<String, JsonNode> newConfig;
+
+    // ...
+}
+```
+
+## 使用示例
+
+### 定义设置表单
+
+假设插件定义了一个名为 `setting-seo` 的设置表单，其中包含了 `blockSpiders`、`keywords` 和 `description` 三个字段：
+
+```yaml
+apiVersion: v1alpha1
+kind: Setting
+metadata:
+  name: setting-seo
+spec:
+  forms:
+    - group: seo  
+      label: SEO 设置  
+      formSchema:  
+        - $formkit: checkbox  
+          name: blockSpiders  
+          label: "屏蔽搜索引擎"  
+          value: false  
+        - $formkit: textarea  
+          name: keywords  
+          label: "站点关键词"  
+        - $formkit: textarea  
+          name: description  
+          label: "站点描述"
+```
+
+### 配置 plugin.yaml
+
+在 `plugin.yaml` 中配置 `settingName` 和 `configMapName` 字段：
+
+```yaml
+apiVersion: plugin.halo.run/v1alpha1
+kind: Plugin
+metadata:
+  name: fake-plugin
+spec:
+  displayName: "Fake Plugin"
+  # ...
+  configMapName: setting-seo-configmap
+  settingName: setting-seo
+```
+
+### 定义值类
+
+为了方便使用，定义一个值类存储配置数据：
+
+```java
+public record SeoSetting(boolean blockSpiders, String keywords, String description) {
+  public static final String GROUP = "seo";
+}
+```
+
+### 获取配置数据
+
+通过依赖注入 `ReactiveSettingFetcher` 并使用 `fetch(group, type)` 方法查询配置：
+
+```java
+@Service
+@RequiredArgsConstructor
+public class SeoService {
+    private final ReactiveSettingFetcher settingFetcher;
+
+    public Mono<Void> checkSeo() {
+        return settingFetcher.fetch(SeoSetting.GROUP, SeoSetting.class)
+                .doOnNext(seoSetting -> {
+                    if (seoSetting.blockSpiders()) {
+                        // do something
+                    }
+                })
+                .then();
+    }
+}
+```
+
+### 监听配置变更
+
+通过监听 `PluginConfigUpdatedEvent` 事件来处理配置变更：
+
+```java
+@Component
+public class SeoConfigListener {
+    @EventListener
+    public void onConfigUpdated(PluginConfigUpdatedEvent event) {
+        if (event.getNewConfig().containsKey(SeoSetting.GROUP)) {
+            // do something
+        }
+    }
+}
+```
+
+通过以上示例，可以看到如何使用 `ReactiveSettingFetcher` 获取配置数据，并通过监听 `PluginConfigUpdatedEvent` 来处理配置变更事件，确保系统能及时响应配置的变化。
diff --git a/sidebars.js b/sidebars.js
index 994f59a..b7b7be5 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -178,6 +178,7 @@ module.exports = {
                 "developer-guide/plugin/api-reference/server/reconciler",
                 "developer-guide/plugin/api-reference/server/role-template",
                 "developer-guide/plugin/api-reference/server/extension-client",
+                "developer-guide/plugin/api-reference/server/setting-fetcher", 
                 "developer-guide/plugin/api-reference/server/reverseproxy",
                 "developer-guide/plugin/api-reference/server/finder-for-theme",
                 "developer-guide/plugin/api-reference/server/template-for-theme",