Skip to content

Commit

Permalink
chore: move framework doc file to core developer dir (#445)
Browse files Browse the repository at this point in the history
### What this PR does?
将 Halo 架构概览移动到系统开发章节

```release-note
None
```
  • Loading branch information
guqing authored Oct 25, 2024
1 parent 717ee40 commit c28767a
Show file tree
Hide file tree
Showing 12 changed files with 23 additions and 19 deletions.
File renamed without changes.
8 changes: 4 additions & 4 deletions docs/developer-guide/plugin/api-reference/server/extension.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}

Expand Down Expand Up @@ -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 用于查询自定义模型对象,它支持以下参数:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: 编写控制器
description: 了解如何为自定义模型编写控制器
---

控制器是 Halo 的关键组件,它们负责对每个自定义模型对象进行操作,协调所需状态和当前状态,参考: [控制器概述](../../basics/framework.md#controller)
控制器是 Halo 的关键组件,它们负责对每个自定义模型对象进行操作,协调所需状态和当前状态,参考: [控制器概述](../../../core/framework.md#controller)

控制器通常在具有一般事件序列的控制循环中运行:

Expand All @@ -17,7 +17,7 @@ description: 了解如何为自定义模型编写控制器
当你设置了温度,告诉了温度自动调节器你的期望状态(Desired State)。
房间的实际温度是当前状态(Current State)。 通过对设备的开关控制,温度自动调节器让其当前状态接近期望状态,未到达期望状态则继续调节,直到达到期望状态。

在 Halo 中控制器的运行部分已经有一个默认实现,你只需要编写控制器的调谐的逻辑也就是 [控制器概述](../../basics/framework.md#controller) 中的所说的 Reconciler 即可。
在 Halo 中控制器的运行部分已经有一个默认实现,你只需要编写控制器的调谐的逻辑也就是 [控制器概述](../../../core/framework.md#controller) 中的所说的 Reconciler 即可。

## 编写 Reconciler

Expand Down Expand Up @@ -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` 对象记录的日志,你可以根据自己的业务需求来实现,如清理外部资源等。

Expand Down
2 changes: 2 additions & 0 deletions docs/developer-guide/plugin/prepare.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,5 @@ description: 插件开发的准备工作
- 你熟悉 Vue 和 TypeScript。
- 你应该熟悉使用 Node.js 包管理器。
- Git 是一个版本控制系统,用于跟踪代码的更改,您需要 Git 来下载示例插件并发布插件。

同时需要先阅读 [Halo 架构概览](../core/framework.md) 以了解 Halo 的核心概念和技术栈。
2 changes: 1 addition & 1 deletion docs/developer-guide/plugin/security/role-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: 了解如何对插件中的 API 定义角色模板以接入权限
---

插件中的 APIs 无论是自定义模型自动生成的 APIs 或者是通过 `@Controller` 自定义的 APIs 都只有超级管理员能够访问,如果想将这些 APIs 授权给其他用户访问,
则需要定义一些[角色模板](../basics/framework.md#rbac)的资源以便可以在用户界面上将其分配给其他角色使用。
则需要定义一些[角色模板](../../core/framework.md#rbac)的资源以便可以在用户界面上将其分配给其他角色使用。

## 角色模板定义

Expand Down
2 changes: 1 addition & 1 deletion sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -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",
],
},
Expand All @@ -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",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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}

Expand Down Expand Up @@ -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 用于查询自定义模型对象,它支持以下参数:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: 编写控制器
description: 了解如何为自定义模型编写控制器
---

控制器是 Halo 的关键组件,它们负责对每个自定义模型对象进行操作,协调所需状态和当前状态,参考: [控制器概述](../../basics/framework.md#controller)
控制器是 Halo 的关键组件,它们负责对每个自定义模型对象进行操作,协调所需状态和当前状态,参考: [控制器概述](../../../core/framework.md#controller)

控制器通常在具有一般事件序列的控制循环中运行:

Expand All @@ -17,7 +17,7 @@ description: 了解如何为自定义模型编写控制器
当你设置了温度,告诉了温度自动调节器你的期望状态(Desired State)。
房间的实际温度是当前状态(Current State)。 通过对设备的开关控制,温度自动调节器让其当前状态接近期望状态,未到达期望状态则继续调节,直到达到期望状态。

在 Halo 中控制器的运行部分已经有一个默认实现,你只需要编写控制器的调谐的逻辑也就是 [控制器概述](../../basics/framework.md#controller) 中的所说的 Reconciler 即可。
在 Halo 中控制器的运行部分已经有一个默认实现,你只需要编写控制器的调谐的逻辑也就是 [控制器概述](../../../core/framework.md#controller) 中的所说的 Reconciler 即可。

## 编写 Reconciler

Expand Down Expand Up @@ -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` 对象记录的日志,你可以根据自己的业务需求来实现,如清理外部资源等。

Expand Down
2 changes: 2 additions & 0 deletions versioned_docs/version-2.20/developer-guide/plugin/prepare.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,5 @@ description: 插件开发的准备工作
- 你熟悉 Vue 和 TypeScript。
- 你应该熟悉使用 Node.js 包管理器。
- Git 是一个版本控制系统,用于跟踪代码的更改,您需要 Git 来下载示例插件并发布插件。

同时需要先阅读 [Halo 架构概览](../core/framework.md) 以了解 Halo 的核心概念和技术栈。
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: 了解如何对插件中的 API 定义角色模板以接入权限
---

插件中的 APIs 无论是自定义模型自动生成的 APIs 或者是通过 `@Controller` 自定义的 APIs 都只有超级管理员能够访问,如果想将这些 APIs 授权给其他用户访问,
则需要定义一些[角色模板](../basics/framework.md#rbac)的资源以便可以在用户界面上将其分配给其他角色使用。
则需要定义一些[角色模板](../../core/framework.md#rbac)的资源以便可以在用户界面上将其分配给其他角色使用。

## 角色模板定义

Expand Down
4 changes: 2 additions & 2 deletions versioned_sidebars/version-2.20-sidebars.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
},
{
Expand All @@ -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",
Expand Down

0 comments on commit c28767a

Please sign in to comment.