Skip to content

Commit

Permalink
update
Browse files Browse the repository at this point in the history
  • Loading branch information
dapeng committed Jun 22, 2024
1 parent 83be57b commit 0b99f58
Show file tree
Hide file tree
Showing 32 changed files with 945 additions and 688 deletions.
84 changes: 49 additions & 35 deletions docs/.vuepress/config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,12 @@ module.exports = {
themeConfig: {
repo: 'gone-io/gone',
docsDir: 'docs',
docsRepo: 'gone-io/docs-static',

editLinks: true,

// 默认为 "Edit this page"
editLinkText: '帮助我们改善此页面！',

logo: '/assets/img/logo.png',

Expand Down Expand Up @@ -141,17 +147,22 @@ module.exports = {
text: '极简例子',
link: '/zh/quick-start/simple.md',
}, {
text: 'Web项目',
link: '/zh/quick-start/web.md',
}, {
text: 'Web + MySQL',
link: '/zh/quick-start/mysql.md',
text: "使用",
items: [
{
text: 'Web项目',
link: '/zh/quick-start/web.md',
}, {
text: 'Web + MySQL',
link: '/zh/quick-start/mysql.md',
}
],
}, {
text: '封装一个Goner调用GPT',
link: '/zh/quick-start/gpt.md',
// }, {
// text: 'JWT + MySQL + Redis + Schedule',
// link: '/zh/quick-start/jwt+mysql+redis+schedule.md',
text: "扩展",
items: [{
text: '封装一个Goner调用GPT',
link: '/zh/quick-start/gpt.md',
}]
}]
},
{
Expand All @@ -164,55 +175,58 @@ module.exports = {
text: "依赖注入",
items: [{
text: 'Goner和依赖注入',
link: '/zh/guide/gone-and-inject.md',
link: '/zh/guide/inject-1-goner-and-inject.md',
}, {
text: '支持哪些方式注入？',
link: '/zh/guide/goner-inject.md',
text: '依赖注入方式',
link: '/zh/guide/inject-2-goner.md',
}, {
text: 'Gone vs Spring',
link: '/zh/guide/gone-vs-spring.md',
text: '函数参数的依赖注入',
link: '/zh/guide/inject-3-func.md',
}],
}, {
text: "内置模块使用",
items: [{
text: '内置Goners',
link: '/zh/guide/inner-goner.md',
link: '/zh/guide/goner-a-use.md',
}, {
text: '配置读取',
link: '/zh/guide/config.md',
link: '/zh/guide/goner-config.md',
}, {
text: '日志输出',
link: '/zh/guide/logrus.md',
text: '提供Web服务',
link: '/zh/guide/goner-gin.md',
}, {
text: '链路追踪',
link: '/zh/guide/tracer.md',
text: '提供gRPC服务',
link: '/zh/guide/goner-grpc.md',
}, {
text: '操作数据库',
link: '/zh/guide/xorm.md',
text: '日志输出',
link: '/zh/guide/goner-logger.md',
}, {
text: '分布式锁 + 分布式缓存',
link: '/zh/guide/redis',
text: '使用Redis',
link: '/zh/guide/goner-redis.md',
}, {
text: '配置定时任务',
link: '/zh/guide/schedule.md',
link: '/zh/guide/goner-schedule.md',
}, {
text: '链路追踪',
link: '/zh/guide/goner-tracer.md',
}, {
text: '使用gRPC通信',
link: '/zh/guide/grpc.md',
text: '使用数据库',
link: '/zh/guide/goner-xorm.md',
}],
}, {
text: "效率提升",
items: [{
text: '自动生成 Priest',
link: '/zh/guide/auto-gen-priest.md',
}, {
text: 'Hook 函数',
link: '/zh/guide/hooks.md',
text: '生成 Priest',
link: '/zh/guide/x-1-gen-priest.md',
}, {
text: '错误处理',
link: '/zh/guide/error.md',
link: '/zh/guide/x-2-error.md',
}, {
text: '单元测试',
link: '/zh/guide/unit-test.md',
link: '/zh/guide/x-3-unit-test.md',
}, {
text: 'Hook 函数',
link: '/zh/guide/x-4-hooks.md',
}]
}],
},
Expand Down
8 changes: 4 additions & 4 deletions docs/zh/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,9 @@ func main() {
// 调用框架内置组件，加载gin框架
_ = goner.GinPriest(cemetery)

//将 一个controller类型的Goner埋葬到墓园
//埋葬是什么意思？ => https://goner.fun/zh/guide/core-concept.html#bury-%E5%9F%8B%E8%91%AC
//墓园是什么意思？ => https://goner.fun/zh/guide/core-concept.html#cemetery-%E5%A2%93%E5%9B%AD
//将 一个controller类型的Goner注册到Gone
//关于Bury => https://goner.fun/zh/guide/core-concept.html#bury-%E5%9F%8B%E8%91%AC
//关于cemetery => https://goner.fun/zh/guide/core-concept.html#cemetery-%E5%A2%93%E5%9B%AD
cemetery.Bury(&controller{})
return nil
})
Expand All @@ -103,7 +103,7 @@ curl -X POST 'http://localhost:8080/hello' \
### 鬼话版本
> 我们编写的代码终究只是死物，除非他们被运行起来。
在Gone中，组件被抽象为 Goner（逝者），Goner 属性可以注入其他的 Goner 。Gone启动前，需要将所有 Goners 埋葬 到 墓园；Gone启动后，会 复活 所有 Goners，建立一个 天国，“天国的所有人都不再残缺，他们想要的必定得到满足”。
在Gone中，组件被抽象为 Goner（逝者），Goner 属性可以注入其他的 Goner 。Gone启动前，需要将所有 Goners 注册 到 墓园；Gone启动后，会 复活 所有 Goners，建立一个 天国，“天国的所有人都不再残缺，他们想要的必定得到满足”。


### 代码版本
Expand Down
4 changes: 2 additions & 2 deletions docs/zh/guide/gone-vs-spring.md → docs/zh/blogs/0_gone-vs-spring.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
sidebar: auto
sidebarDepth: 4
prev: ./goner-inject
next: ./inner-goner
prev: ../blogs/
next: ./1_v1.x_release
---

# 对比 Gone 和 Spring 的依赖注入
Expand Down
5 changes: 4 additions & 1 deletion docs/zh/blogs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,7 @@ next: ../
时间：2024-06-18

## [v1.x版本 正式发布](https://goner.fun/zh/blogs/1_v1.x_release.html)
时间：2024-06-16
时间：2024-06-16

## [对比 Gone 和 Spring 的依赖注入](./0_gone-vs-spring.md)
时间：2024-05-28
4 changes: 2 additions & 2 deletions docs/zh/goners/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,13 @@ next: ../
|接口名 | 实现| GoneId|功能介绍|
|---|---|---|--|
|[Heaven](https://pkg.go.dev/github.com/gone-io/gone#Heaven)|[heaven](https://github.com/gone-io/gone/blob/12ea8e3577fbed493766f522ab002136edf3805d/heaven.go#L65)|gone-heaven|负责将Goner从cemetery中复活，执行安装的Hook函数，管理框架的启停流程和状态。|
|[Cemetery](https://pkg.go.dev/github.com/gone-io/gone#Cemetery)|[cemetery](https://github.com/gone-io/gone/blob/12ea8e3577fbed493766f522ab002136edf3805d/cemetery.go#L17)|gone-cemetery|管理Goners，提供将Goner埋葬的Bury方法；依赖注入的逻辑主要在该结构体中实现。|
|[Cemetery](https://pkg.go.dev/github.com/gone-io/gone#Cemetery)|[cemetery](https://github.com/gone-io/gone/blob/12ea8e3577fbed493766f522ab002136edf3805d/cemetery.go#L17)|gone-cemetery|管理Goners，提供将Goner注册的Bury方法；依赖注入的逻辑主要在该结构体中实现。|

## 框架内置Goners
框架内置Goners，是为丰富Gone的功能而开发的，比如支持Web开发、支持数据库连接、支持Redis等…
代码实现在 [goner目录](https://github.com/gone-io/gone/tree/v0.1.4/goner)，该目录下的每个子目录分别实现了一个gone的特性，每个特性包含一个或多个Goner的定义和实现。

为了方便使用，我们在 [goner/priest.go](https://github.com/gone-io/gone/blob/v0.1.4/goner/priest.go) 中定义了`Priest`函数，可以按功能直接批量埋葬相关Goners。
为了方便使用，我们在 [goner/priest.go](https://github.com/gone-io/gone/blob/v0.1.4/goner/priest.go) 中定义了`Priest`函数，可以按功能直接批量注册相关Goners。



Expand Down
86 changes: 50 additions & 36 deletions docs/zh/guide/core-concept.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
---
sidebar: auto
prev: false
next: ./gone-and-inject
prev: ./
next: ./inject-1-goner-and-inject.md
---

# Gone的核心概念
“我们编写的代码，终究只是死物，除非他在 **天国（程序）** 被 **复活（对Goners完成依赖的装配）**，为此我们需要将他 **埋葬（注册）** 在 **墓园（Gone内部的Goners仓库）**。”
> “我们编写的代码，终究只是死物，除非他在 **天国（程序）** 被 **复活（对Goners完成依赖的装配）**，为此我们需要将他 **埋葬（注册）** 在 **墓园（Gone内部的Goners仓库）**。”
[[toc]]

## Goner（Gone中的组件，只有实现了Goner接口才能被注册到Gone中）
## Goner

在Gone框架中，最核心的概念就是 **Goner**，是指通过匿名嵌入了 `gone.Flag` 而实现**Goner**接口的结构体实例指针。
**Goner** 是指实现了 `gone.Goner` 接口的结构体实例指针；只有实现了`gone.Goner`接口的实例才能被注册到Gone中；实现`Goner`接口 有且只有 通过嵌入 **`gone.Flag`** 来实现。

举个例子，下面的worker就是一个goner：
```go
Expand All @@ -22,14 +22,14 @@ type Worker struct {
worker := &Worker{}
```

Goner是Gone框架中的组件，是实现依赖注入的关键：
1. Goner可以作为属性注入到其Goner
2. Goner的属性可以被其Goners注入
Goner是Gone的组件，是实现依赖注入的关键：
1. Goner可以作为值被注入到其Goner的属性；
2. Goner的属性可以被其Goners注入。


为什么需要内嵌一个 `gone.Flag`，能通过其他方式实现**Goner**接口吗？

::: tip

::: tip 为什么只能内嵌 `gone.Flag`实现**Goner**接口？
下面是Goner和gone.Flag的源代码：
```go
type Flag struct{}
Expand All @@ -51,23 +51,26 @@ Goner作为接口，要求实现它的“对象”拥有一个私有的方法`go
多个**Goner**，我们使用其复数形式（**Goners**）表示。
:::

在Gone框架中，还包含了三类特殊的Goner，定义如下：


### 🔮Prophet（先知，率先知道复活已经完成）

## 特殊Goners


### 🔮Prophet（先知，率先知道装配完成）
一种特殊的 **Goner**，在普通 **Goner** 上实现了 **`AfterRevive() AfterReviveError`** 方法就是 **Prophet（先知）**；**AfterRevive** 会在所有 **Goners** 都完成依赖注入装配流程后被执行。

Prophet接口定义如下：
```go
// Prophet 先知
type Prophet interface {
Goner
//AfterRevive 在Goner复活后会被执行
//AfterRevive 在所有Goners装配完后会被执行
AfterRevive() error
}
```

### 😇Angel（天使，看护服务的开启和结束）
### 😇Angel（天使，看护开始和结束）
一种特殊的 **Goner**，拥有天使左翼`Start(Cemetery) error` 和 天使右翼`Stop(Cemetery) error`，左翼负责开始（用于分配资源，启动某项服务），右翼负责结束（用于终止某项服务，回收资源）。

Angel接口定义如下：
Expand All @@ -79,8 +82,9 @@ type Angel interface {
}
```

### 🧛🏻‍♀️Vampire（吸血鬼，一个可以用于扩展依赖注入的强大工具）
一种特殊的 **Goner**，拥有特殊能力——吸血`Suck(conf string, v reflect.Value) SuckError`。**Suck**可以将不是**Goner**的值赋予注入给Goner属性。
### 🧛🏻‍♀️Vampire（吸血鬼，扩展注入类型）

一种特殊的 **Goner**，拥有特殊能力——“吸血”`Suck(conf string, v reflect.Value) SuckError`。**Suck**可以将不是**Goner**的值赋予注入给Goner属性。

Vampire接口定义如下：
```go
Expand All @@ -92,44 +96,47 @@ type Vampire interface {
```


## Cemetery（墓园，goners仓库）
Cemetery用于管理Goners，主要提供Bury（埋葬）和 revive（复活）的方法，其接口定义如下：
## Cemetery（Goners仓库）

Cemetery用于管理Goners，主要提供Bury（注册）和 revive（装配）的方法，其接口定义如下：
```go
type Cemetery interface {
// ... 其他方法
Goner
Bury(Goner, ...GonerId) Cemetery // 埋葬，将逝者埋葬到墓园
Bury(Goner, ...GonerId) Cemetery // 将Goner注册到框架



//ReviveAllFromTombs 复活所有Goner
//ReviveAllFromTombs 装配所有Goner
ReviveAllFromTombs() error

//...
}
```
从代码上可以看到Cemetery本身也是一个Goner，在Gone框架启动时他会被自动埋葬和复活。
从代码上可以看到Cemetery本身也是一个Goner，在Gone框架启动时他自己也注册到Cemetery中。

### Bury（埋葬，完成Goner注册）
将Goner **埋葬（注册）** 到 **Cemetery（goners仓库）** 就是将Goner注册到框架，以待装配流程完成属性的注入；在代码实现上，**Bury**是**Cemetery**上的公开方法，一般在通过 **Priest** 函数调用该方法。
### Bury（注册）

### Revive（复活，Goners依赖的属性的自动装配）
Revive（复活）指的是Goner所有需要注入的属性完成依赖装配的过程。在函数`ReviveAllFromTombs() error`中，尝试复活所有被注册的Goners，如果存在属性不能正常注入，程序将抛出panic。
将Goner **注册** 到 **Cemetery（goners仓库）** 就是将Goner注册到框架，以待装配流程完成属性的注入；在代码实现上，**Bury**是**Cemetery**上的公开方法，一般在通过 **Priest** 函数调用该方法。

### Revive（装配）
Revive（装配）指的是Goner所有需要注入的属性完成依赖装配的过程。在函数`ReviveAllFromTombs() error`中，尝试装配所有被注册的Goners，如果存在属性不能正常注入，程序将抛出panic。

::: tip
**ReviveAllFromTombs**在完成了复活所有的**Goners**后，会调用所有**Prophet**的 **AfterRevive**方法。
**ReviveAllFromTombs**在完成了装配所有的**Goners**后，会调用所有**Prophet**的 **AfterRevive**方法。
:::


## Heaven（天国，代表程序本身）
Heaven（天国）代表了一个Gone程序，用于管理程序的启动、停止等状态和流程（复活在启动前完成），用于在启动前后以及程序停止前执行一些hook任务。Heaven接收一个牧师函数开始运行，例如：
## Heaven
Heaven（天国）代表了一个Gone程序，用于管理程序的启动、停止等状态和流程（装配在启动前完成），用于在启动前后以及程序停止前执行一些hook任务。Heaven接收一个牧师函数开始运行，例如：

```go
package main

import "github.com/gone-io/gone"

func Priest(cemetery gone.Cemetery) error {
// 调用 cemetery.Bury 埋葬 Goner
// 调用 cemetery.Bury 注册 Goner
// 或者 调用其他 Priest 函数
// TODO
return nil
Expand All @@ -147,7 +154,7 @@ package main
import "github.com/gone-io/gone"

func Priest(cemetery gone.Cemetery) error {
// 调用 cemetery.Bury 埋葬 Goner
// 调用 cemetery.Bury 注册 Goner
// 或者 调用其他 Priest 函数
// TODO
return nil
Expand All @@ -163,8 +170,9 @@ func main(){
}
```

## Priest (牧师，一个用于完成goners注册的加载函数)
Priest (牧师)是负责将**Goner**埋葬到**Cemetery**的函数，他的定义如下：
## Priest (批量注册Goners)

Priest (牧师)是负责将**Goner**注册到Gone的函数，他的定义如下：
```go
type Priest func(cemetery Cemetery) error
```
Expand All @@ -186,7 +194,7 @@ func aPriest(cemetery gone.Cemetery) error {
cemetery.Bury(&Boss{Name: "Jim"}, "boss-jim")
cemetery.Bury(&Worker{Name: "Bob"}, "worker-bob")

//匿名埋葬，不指定被埋葬Goner的GonerId
//匿名注册，不指定被注册Goner的GonerId
cemetery.Bury(&Worker{Name: "X"})
return nil
}
Expand Down Expand Up @@ -214,8 +222,14 @@ func aPriest(cemetery gone.Cemetery) error {
return nil
}
```
如果我们开发了一个组件包，其中使用了多个**Goners**来完成响应的功能，使用时需要同时**埋葬**这些**Goners**，那么我们可以编写一个**Priest**函数方便业务代码批量**埋葬**这些**Goners**。

框架内置的组件包，我们就是这样干的，[代码](https://github.com/gone-io/gone/blob/main/goner/priest.go) 和 [文档](https://goner.fun/zh/goners/#%E6%A1%86%E6%9E%B6%E5%86%85%E7%BD%AEgoners)。
如果开发了一个组件包使用了多个**Goners**来实现相应的功能；使用时需要同时注册多个Goners，可能不是那么方便；为了方便用户使用我们开发的包，可以编写一个**Priest**函数批量注册Goners。

Gone内置的组件包，我们就是这样做的，可以参考[代码](https://github.com/gone-io/gone/blob/main/goner/priest.go) 和 [文档](https://goner.fun/zh/goners/#%E6%A1%86%E6%9E%B6%E5%86%85%E7%BD%AEgoners)。

另外，我们开发了一个命令行辅助工具 **[gone](https://goner.fun/zh/references/gone-tool.html)**，用于扫描特殊注释`//go:gone`自动生成牧师函数，参考 [自动生成Priest](./auto-gen-priest.md)。

## 总结
在Gone中，组件叫`Goner`（逝者），称为Goner需要嵌入`gone.Flag`（死亡标记），Goner被注册（埋在）到 `Cemetery`（墓园）中；Gone启动时，自动装配（Revive）所有Goners，建立一个天国（Gone程序），在天国中有先知、天使和吸血鬼。

另外，我们开发了一个命令行辅助工具**gone**，用于扫描特殊注释`//go:gone`自动生成牧师函数，参考[自动生成Priest](./auto-gen-priest.md)。
是不是很有意思呢？
Loading

0 comments on commit 0b99f58

Please sign in to comment.