From c28767ab09eee4632908ff227176ae17847b1e94 Mon Sep 17 00:00:00 2001 From: guqing <38999863+guqing@users.noreply.github.com> Date: Fri, 25 Oct 2024 21:33:55 +0800 Subject: [PATCH] chore: move framework doc file to core developer dir (#445) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ### What this PR does? 将 Halo 架构概览移动到系统开发章节 ```release-note None ``` --- docs/developer-guide/{plugin/basics => core}/framework.md | 0 .../plugin/api-reference/server/extension.md | 8 ++++---- .../plugin/api-reference/server/reconciler.md | 6 +++--- docs/developer-guide/plugin/prepare.md | 2 ++ docs/developer-guide/plugin/security/role-template.md | 2 +- sidebars.js | 2 +- .../developer-guide/{plugin/basics => core}/framework.md | 0 .../plugin/api-reference/server/extension.md | 8 ++++---- .../plugin/api-reference/server/reconciler.md | 6 +++--- .../version-2.20/developer-guide/plugin/prepare.md | 2 ++ .../developer-guide/plugin/security/role-template.md | 2 +- versioned_sidebars/version-2.20-sidebars.json | 4 ++-- 12 files changed, 23 insertions(+), 19 deletions(-) rename docs/developer-guide/{plugin/basics => core}/framework.md (100%) rename versioned_docs/version-2.20/developer-guide/{plugin/basics => core}/framework.md (100%) diff --git a/docs/developer-guide/plugin/basics/framework.md b/docs/developer-guide/core/framework.md similarity index 100% rename from docs/developer-guide/plugin/basics/framework.md rename to docs/developer-guide/core/framework.md diff --git a/docs/developer-guide/plugin/api-reference/server/extension.md b/docs/developer-guide/plugin/api-reference/server/extension.md index 7630931..511db3e 100644 --- a/docs/developer-guide/plugin/api-reference/server/extension.md +++ b/docs/developer-guide/plugin/api-reference/server/extension.md @@ -86,14 +86,14 @@ public void start() { - `name`: 用于标识自定义模型的名称。 - `creationTimestamp`: 用于标识自定义模型的创建时间，无法修改，只在创建时自动生成。 - `version`: 用于标识自定义模型的数据乐观锁版本，无法修改，由更新时自动填充，如果更新时指定了 `version` 且与当前 `version` 不一致则会更新失败。 - - `deletionTimestamp`: 用于标识自定义模型的删除时间，表示此自定义模型对象被声明为删除，此时仍然可以通过 API 访问到此对象，参考 [自定义模型对象生命周期](../../basics/framework.md#extension-lifecycle) - - `finalizers`: 用于标识终结器，它是一个字符串集合，用于标识自定义模型对象是否可回收，参考 [自定义模型对象生命周期](../../basics/framework.md#extension-lifecycle) + - `deletionTimestamp`: 用于标识自定义模型的删除时间，表示此自定义模型对象被声明为删除，此时仍然可以通过 API 访问到此对象，参考 [自定义模型对象生命周期](../../../core/framework.md#extension-lifecycle) + - `finalizers`: 用于标识终结器，它是一个字符串集合，用于标识自定义模型对象是否可回收，参考 [自定义模型对象生命周期](../../../core/framework.md#extension-lifecycle) - `labels`: 用于标识自定义模型的标签，它是一个字符串键值对集合，用于标识自定义模型对象的标签，可以通过标签来查询自定义模型对象。 - `annotations`: 用于存放扩展信息，它是一个字符串键值对集合，用于存放自定义模型对象的扩展信息。 - `spec`: 用于声明自定义模型对象的期望状态，它是声明式的，用户只需要声明期望状态，实际状态由具体的控制器来维护，最终达到用户期望的状态。 - `status`: 用于描述自定义模型对象资源状态的变化，和一些实际状态。 -其中 `apiVersion`、`kind`、`metadata`都包含在了 AbstractExtension 类中，所以我们只需要关注 `spec` 和 `status` 即可，参考：[Halo 架构概览之自定义模型](../../basics/framework.md#extension) +其中 `apiVersion`、`kind`、`metadata`都包含在了 AbstractExtension 类中，所以我们只需要关注 `spec` 和 `status` 即可，参考：[Halo 架构概览之自定义模型](../../../core/framework.md#extension) ## 声明自定义模型对象 {#declare-extension-object} @@ -216,7 +216,7 @@ POST /apis/my-plugin.halo.run/v1alpha1/persons DELETE /apis/my-plugin.halo.run/v1alpha1/persons/{name} ``` -对于这组自动生成的 `CRUD` APIs，你可以通过定义[控制器](../../basics/framework.md#controller)来完成对数据修改后的业务逻辑处理来满足大部分的场景需求。 +对于这组自动生成的 `CRUD` APIs，你可以通过定义[控制器](../../../core/framework.md#controller)来完成对数据修改后的业务逻辑处理来满足大部分的场景需求。 `GET /apis/my-plugin.halo.run/v1alpha1/persons` 这个 API 用于查询自定义模型对象，它支持以下参数： diff --git a/docs/developer-guide/plugin/api-reference/server/reconciler.md b/docs/developer-guide/plugin/api-reference/server/reconciler.md index 26ac36e..f16cc02 100644 --- a/docs/developer-guide/plugin/api-reference/server/reconciler.md +++ b/docs/developer-guide/plugin/api-reference/server/reconciler.md @@ -3,7 +3,7 @@ title: 编写控制器 description: 了解如何为自定义模型编写控制器 --- -控制器是 Halo 的关键组件，它们负责对每个自定义模型对象进行操作，协调所需状态和当前状态，参考： [控制器概述](../../basics/framework.md#controller)。 +控制器是 Halo 的关键组件，它们负责对每个自定义模型对象进行操作，协调所需状态和当前状态，参考： [控制器概述](../../../core/framework.md#controller)。 控制器通常在具有一般事件序列的控制循环中运行： @@ -17,7 +17,7 @@ description: 了解如何为自定义模型编写控制器 当你设置了温度，告诉了温度自动调节器你的期望状态（Desired State）。 房间的实际温度是当前状态（Current State）。 通过对设备的开关控制，温度自动调节器让其当前状态接近期望状态，未到达期望状态则继续调节，直到达到期望状态。 -在 Halo 中控制器的运行部分已经有一个默认实现，你只需要编写控制器的调谐的逻辑也就是 [控制器概述](../../basics/framework.md#controller) 中的所说的 Reconciler 即可。 +在 Halo 中控制器的运行部分已经有一个默认实现，你只需要编写控制器的调谐的逻辑也就是 [控制器概述](../../../core/framework.md#controller) 中的所说的 Reconciler 即可。 ## 编写 Reconciler @@ -339,7 +339,7 @@ public Result reconcile(Request request) { ``` 1. `ExtensionOperator.isDeleted` 方法是 Halo 提供的工具方法，用于判断对象是否被删除，它会判断 `metadata.deletionTimestamp` 是否存在，如果存在则表示对象被标记删除了。 -关于自定义模型对象的删除可以参考：[自定义模型对象生命周期](../../basics/framework.md#extension-lifecycle) +关于自定义模型对象的删除可以参考：[自定义模型对象生命周期](../../../core/framework.md#extension-lifecycle) 2. `ExtensionUtil.removeFinalizers` 方法是 Halo 提供的工具方法，用于移除对象的终结器，它接收两个参数，第一个参数是对象的元数据，第二个参数是要移除的终结器名称集合，它来自 `run.halo.app.extension.ExtensionUtil`。 3. `cleanUpLogsForTracker` 方法是我们自己实现的，这里的示例是用于清理 `EventTracker` 对象记录的日志，你可以根据自己的业务需求来实现，如清理外部资源等。 diff --git a/docs/developer-guide/plugin/prepare.md b/docs/developer-guide/plugin/prepare.md index 85a41fd..e8dae21 100644 --- a/docs/developer-guide/plugin/prepare.md +++ b/docs/developer-guide/plugin/prepare.md @@ -13,3 +13,5 @@ description: 插件开发的准备工作 - 你熟悉 Vue 和 TypeScript。 - 你应该熟悉使用 Node.js 包管理器。 - Git 是一个版本控制系统，用于跟踪代码的更改，您需要 Git 来下载示例插件并发布插件。 + +同时需要先阅读 [Halo 架构概览](../core/framework.md) 以了解 Halo 的核心概念和技术栈。 diff --git a/docs/developer-guide/plugin/security/role-template.md b/docs/developer-guide/plugin/security/role-template.md index 08b96f4..ff7aa65 100644 --- a/docs/developer-guide/plugin/security/role-template.md +++ b/docs/developer-guide/plugin/security/role-template.md @@ -4,7 +4,7 @@ description: 了解如何对插件中的 API 定义角色模板以接入权限 --- 插件中的 APIs 无论是自定义模型自动生成的 APIs 或者是通过 `@Controller` 自定义的 APIs 都只有超级管理员能够访问，如果想将这些 APIs 授权给其他用户访问， -则需要定义一些[角色模板](../basics/framework.md#rbac)的资源以便可以在用户界面上将其分配给其他角色使用。 +则需要定义一些[角色模板](../../core/framework.md#rbac)的资源以便可以在用户界面上将其分配给其他角色使用。 ## 角色模板定义 diff --git a/sidebars.js b/sidebars.js index 31841b2..971cf88 100644 --- a/sidebars.js +++ b/sidebars.js @@ -116,6 +116,7 @@ module.exports = { "developer-guide/core/prepare", "developer-guide/core/run", "developer-guide/core/build", + "developer-guide/core/framework", // "developer-guide/core/code-style", ], }, @@ -137,7 +138,6 @@ module.exports = { type: "generated-index", }, items: [ - "developer-guide/plugin/basics/framework", "developer-guide/plugin/basics/structure", "developer-guide/plugin/basics/manifest", "developer-guide/plugin/basics/devtools", diff --git a/versioned_docs/version-2.20/developer-guide/plugin/basics/framework.md b/versioned_docs/version-2.20/developer-guide/core/framework.md similarity index 100% rename from versioned_docs/version-2.20/developer-guide/plugin/basics/framework.md rename to versioned_docs/version-2.20/developer-guide/core/framework.md diff --git a/versioned_docs/version-2.20/developer-guide/plugin/api-reference/server/extension.md b/versioned_docs/version-2.20/developer-guide/plugin/api-reference/server/extension.md index 7630931..511db3e 100644 --- a/versioned_docs/version-2.20/developer-guide/plugin/api-reference/server/extension.md +++ b/versioned_docs/version-2.20/developer-guide/plugin/api-reference/server/extension.md @@ -86,14 +86,14 @@ public void start() { - `name`: 用于标识自定义模型的名称。 - `creationTimestamp`: 用于标识自定义模型的创建时间，无法修改，只在创建时自动生成。 - `version`: 用于标识自定义模型的数据乐观锁版本，无法修改，由更新时自动填充，如果更新时指定了 `version` 且与当前 `version` 不一致则会更新失败。 - - `deletionTimestamp`: 用于标识自定义模型的删除时间，表示此自定义模型对象被声明为删除，此时仍然可以通过 API 访问到此对象，参考 [自定义模型对象生命周期](../../basics/framework.md#extension-lifecycle) - - `finalizers`: 用于标识终结器，它是一个字符串集合，用于标识自定义模型对象是否可回收，参考 [自定义模型对象生命周期](../../basics/framework.md#extension-lifecycle) + - `deletionTimestamp`: 用于标识自定义模型的删除时间，表示此自定义模型对象被声明为删除，此时仍然可以通过 API 访问到此对象，参考 [自定义模型对象生命周期](../../../core/framework.md#extension-lifecycle) + - `finalizers`: 用于标识终结器，它是一个字符串集合，用于标识自定义模型对象是否可回收，参考 [自定义模型对象生命周期](../../../core/framework.md#extension-lifecycle) - `labels`: 用于标识自定义模型的标签，它是一个字符串键值对集合，用于标识自定义模型对象的标签，可以通过标签来查询自定义模型对象。 - `annotations`: 用于存放扩展信息，它是一个字符串键值对集合，用于存放自定义模型对象的扩展信息。 - `spec`: 用于声明自定义模型对象的期望状态，它是声明式的，用户只需要声明期望状态，实际状态由具体的控制器来维护，最终达到用户期望的状态。 - `status`: 用于描述自定义模型对象资源状态的变化，和一些实际状态。 -其中 `apiVersion`、`kind`、`metadata`都包含在了 AbstractExtension 类中，所以我们只需要关注 `spec` 和 `status` 即可，参考：[Halo 架构概览之自定义模型](../../basics/framework.md#extension) +其中 `apiVersion`、`kind`、`metadata`都包含在了 AbstractExtension 类中，所以我们只需要关注 `spec` 和 `status` 即可，参考：[Halo 架构概览之自定义模型](../../../core/framework.md#extension) ## 声明自定义模型对象 {#declare-extension-object} @@ -216,7 +216,7 @@ POST /apis/my-plugin.halo.run/v1alpha1/persons DELETE /apis/my-plugin.halo.run/v1alpha1/persons/{name} ``` -对于这组自动生成的 `CRUD` APIs，你可以通过定义[控制器](../../basics/framework.md#controller)来完成对数据修改后的业务逻辑处理来满足大部分的场景需求。 +对于这组自动生成的 `CRUD` APIs，你可以通过定义[控制器](../../../core/framework.md#controller)来完成对数据修改后的业务逻辑处理来满足大部分的场景需求。 `GET /apis/my-plugin.halo.run/v1alpha1/persons` 这个 API 用于查询自定义模型对象，它支持以下参数： diff --git a/versioned_docs/version-2.20/developer-guide/plugin/api-reference/server/reconciler.md b/versioned_docs/version-2.20/developer-guide/plugin/api-reference/server/reconciler.md index 26ac36e..f16cc02 100644 --- a/versioned_docs/version-2.20/developer-guide/plugin/api-reference/server/reconciler.md +++ b/versioned_docs/version-2.20/developer-guide/plugin/api-reference/server/reconciler.md @@ -3,7 +3,7 @@ title: 编写控制器 description: 了解如何为自定义模型编写控制器 --- -控制器是 Halo 的关键组件，它们负责对每个自定义模型对象进行操作，协调所需状态和当前状态，参考： [控制器概述](../../basics/framework.md#controller)。 +控制器是 Halo 的关键组件，它们负责对每个自定义模型对象进行操作，协调所需状态和当前状态，参考： [控制器概述](../../../core/framework.md#controller)。 控制器通常在具有一般事件序列的控制循环中运行： @@ -17,7 +17,7 @@ description: 了解如何为自定义模型编写控制器 当你设置了温度，告诉了温度自动调节器你的期望状态（Desired State）。 房间的实际温度是当前状态（Current State）。 通过对设备的开关控制，温度自动调节器让其当前状态接近期望状态，未到达期望状态则继续调节，直到达到期望状态。 -在 Halo 中控制器的运行部分已经有一个默认实现，你只需要编写控制器的调谐的逻辑也就是 [控制器概述](../../basics/framework.md#controller) 中的所说的 Reconciler 即可。 +在 Halo 中控制器的运行部分已经有一个默认实现，你只需要编写控制器的调谐的逻辑也就是 [控制器概述](../../../core/framework.md#controller) 中的所说的 Reconciler 即可。 ## 编写 Reconciler @@ -339,7 +339,7 @@ public Result reconcile(Request request) { ``` 1. `ExtensionOperator.isDeleted` 方法是 Halo 提供的工具方法，用于判断对象是否被删除，它会判断 `metadata.deletionTimestamp` 是否存在，如果存在则表示对象被标记删除了。 -关于自定义模型对象的删除可以参考：[自定义模型对象生命周期](../../basics/framework.md#extension-lifecycle) +关于自定义模型对象的删除可以参考：[自定义模型对象生命周期](../../../core/framework.md#extension-lifecycle) 2. `ExtensionUtil.removeFinalizers` 方法是 Halo 提供的工具方法，用于移除对象的终结器，它接收两个参数，第一个参数是对象的元数据，第二个参数是要移除的终结器名称集合，它来自 `run.halo.app.extension.ExtensionUtil`。 3. `cleanUpLogsForTracker` 方法是我们自己实现的，这里的示例是用于清理 `EventTracker` 对象记录的日志，你可以根据自己的业务需求来实现，如清理外部资源等。 diff --git a/versioned_docs/version-2.20/developer-guide/plugin/prepare.md b/versioned_docs/version-2.20/developer-guide/plugin/prepare.md index 85a41fd..e8dae21 100644 --- a/versioned_docs/version-2.20/developer-guide/plugin/prepare.md +++ b/versioned_docs/version-2.20/developer-guide/plugin/prepare.md @@ -13,3 +13,5 @@ description: 插件开发的准备工作 - 你熟悉 Vue 和 TypeScript。 - 你应该熟悉使用 Node.js 包管理器。 - Git 是一个版本控制系统，用于跟踪代码的更改，您需要 Git 来下载示例插件并发布插件。 + +同时需要先阅读 [Halo 架构概览](../core/framework.md) 以了解 Halo 的核心概念和技术栈。 diff --git a/versioned_docs/version-2.20/developer-guide/plugin/security/role-template.md b/versioned_docs/version-2.20/developer-guide/plugin/security/role-template.md index 08b96f4..ff7aa65 100644 --- a/versioned_docs/version-2.20/developer-guide/plugin/security/role-template.md +++ b/versioned_docs/version-2.20/developer-guide/plugin/security/role-template.md @@ -4,7 +4,7 @@ description: 了解如何对插件中的 API 定义角色模板以接入权限 --- 插件中的 APIs 无论是自定义模型自动生成的 APIs 或者是通过 `@Controller` 自定义的 APIs 都只有超级管理员能够访问，如果想将这些 APIs 授权给其他用户访问， -则需要定义一些[角色模板](../basics/framework.md#rbac)的资源以便可以在用户界面上将其分配给其他角色使用。 +则需要定义一些[角色模板](../../core/framework.md#rbac)的资源以便可以在用户界面上将其分配给其他角色使用。 ## 角色模板定义 diff --git a/versioned_sidebars/version-2.20-sidebars.json b/versioned_sidebars/version-2.20-sidebars.json index 0b7ea20..5dd329c 100644 --- a/versioned_sidebars/version-2.20-sidebars.json +++ b/versioned_sidebars/version-2.20-sidebars.json @@ -99,7 +99,8 @@ "items": [ "developer-guide/core/prepare", "developer-guide/core/run", - "developer-guide/core/build" + "developer-guide/core/build", + "developer-guide/core/framework" ] }, { @@ -120,7 +121,6 @@ "type": "generated-index" }, "items": [ - "developer-guide/plugin/basics/framework", "developer-guide/plugin/basics/structure", "developer-guide/plugin/basics/manifest", "developer-guide/plugin/basics/devtools",