diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 324d4e5..c5d4a5e 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -29,39 +29,39 @@ module.exports = { selectText: '选择语言', editLinkText: '在 GitHub 上编辑此页', - nav: [ - { - text: '指南', - link: '/zh/guide/' - }, + // nav: [ + // { + // text: '指南', + // link: '/zh/guide/' + // }, - { - text: '快速开始', - link: '/zh/quick-start/' - }, - { - text: 'Web开发', - link: '/zh/web/', - }, + // { + // text: '快速开始', + // link: '/zh/quick-start/' + // }, + // { + // text: 'Web开发', + // link: '/zh/web/', + // }, - { - text: 'API 参考', - link: '/zh/api/' - }, - { - text: '故事', - link: '/zh/story/' - }, { - text: 'Goner 组件库', - link: '/zh/goners/' - }, - ], + // { + // text: 'API 参考', + // link: '/zh/api/' + // }, + // { + // text: '故事', + // link: '/zh/story/' + // }, { + // text: 'Goner 组件库', + // link: '/zh/goners/' + // }, + // ], - sidebar: [ - ['/zh/', '介绍'], - '/zh/quick-start/', - '/zh/guide/', - ], + // sidebar: [ + // ['/zh/', '介绍'], + // '/zh/quick-start/', + // '/zh/guide/', + // ], }, '/en/': { diff --git a/docs/img/image1.png b/docs/img/image1.png new file mode 100644 index 0000000..7c1ce74 Binary files /dev/null and b/docs/img/image1.png differ diff --git a/docs/img/image2.png b/docs/img/image2.png new file mode 100644 index 0000000..ff1c825 Binary files /dev/null and b/docs/img/image2.png differ diff --git a/docs/zh/README.md b/docs/zh/README.md index 9a42dc5..8225c86 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -1,4 +1,8 @@ -# Gone 框架指南 +--- +sidebar: auto +--- + +# Gone 框架介绍 ## Gone是什么 Gone是一个为熟悉Spring的程序员设计的Golang框架，它整合了依赖注入和Web功能，使得在Golang中的应用程序管理和开发更加方便。该框架定义了像“Goners”（组件）、“Cemetery”（存储）和“Heaven”（运行状态）等概念，每一个都在生命周期管理和依赖处理中发挥着独特的作用。它支持依赖注入、服务生命周期管理和动态属性注入等功能，以改善开发体验。 @@ -61,3 +65,183 @@ func main() { 在上面的代码中，我们看到`gone.Run`可以接收形式如 **`func (cemetery gone.Cemetery) error`** 的函数；实际上这个函数，我们称之为 **Priest**，是牧师的意思，他专门负责将 **Goner** 埋葬到 墓地（**Cemetery**）。 +### 如何执行**Goner**中的业务代码？ + +在Gone中，我们做了一个有趣的定义：Goner所有属性都被注入后，我们称这个Goner被复活了（**Revive**）。如果你查看Gone的源代码，你会发现管理复活Goner状态的组件叫**Heaven**（**天堂**），这里灵感来源于各宗教神话中人死后会上天堂的传说。 + +为了执行**Goner**业务代码，我们可以在**Goner**上定义了方法 **`AfterRevive() gone.AfterReviveError`**，这个方法会在**Goner**被 **Revive** 后得到执行，并且我们将拥有该方法的 **Goner** 称之为 **Prophet**（也就是 **先知**）。实际上，一般情况我们只需要定义少量的先知来引导代码执行就可以了。 + + +下面是一个例子；代码可以在[这里](https://github.com/gone-io/gone/blob/main/example/after-revive/main.go)找到： + +```go +package main + +import "github.com/gone-io/gone" + +type Adder struct { + gone.Flag +} + +func (a *Adder) Add(a1, a2 int) int { + return a1 + a2 +} + +type Computer struct { + gone.Flag + adder Adder `gone:"*"` +} + +func (c *Computer) Compute() { + println("I want to compute!") + println("1000 add 2000 is", c.adder.Add(1000, 2000)) +} + +// AfterRevive 复活后执行的函数 +func (c *Computer) AfterRevive() gone.AfterReviveError { + // boot + c.Compute() + + return nil +} + +func main() { + gone.Run(func(cemetery gone.Cemetery) error { + cemetery.Bury(&Computer{}) + cemetery.Bury(&Adder{}) + return nil + }) +} +``` +执行上面代码，将得到结果： +![执行结果](../img/image1.png) + + +### gone命令，自动生成`Priest`函数 + +实际上，前面已经讲完了Gone框架的核心功能；然而由于Golang本身的问题，我们无法做到像Spring那么方便，需要手动把所有 **`Goner`** 加入（**`Bury`**）到 **`Cemetery`**。为了让Gone使用起来更方便，我们编写了一个辅助工具来自动生成 **`Priest`** 函数。下面介绍如何在一个项目中使用这个辅助工具。 + +> 完整代码可以在[这里](https://github.com/gone-io/gone/blob/main/example/gen-code)找到 + +#### 1. 安装辅助工具: gone + +辅助工具和Gone框架同名，也叫gone，可以使用`go install`进行安装，如下： + +```bash +go install github.com/gone-io/gone/tools/gone@latest +``` + +安装后，可以执行`gone -h`命令，如果看到如下结果就是正常安装了： +![alt text](../img/image2.png) + + +#### 2. 创建一个名为`gen-code`的新项目 +```bash +mkdir gen-code +cd gen-code +go mod init gen-code +``` + +#### 3. 创建Goner +文件名：goner.go +```go +package main + +import "github.com/gone-io/gone" + +//go:gone +func NewAdder() gone.Goner { + return &Adder{} +} + +//go:gone +func NewComputer() gone.Goner { + return &Computer{} +} + +type Adder struct { + gone.Flag +} + +func (a *Adder) Add(a1, a2 int) int { + return a1 + a2 +} + +type Computer struct { + gone.Flag + adder Adder `gone:"*"` +} + +func (c *Computer) Compute() { + println("I want to compute!") + println("1000 add 2000 is", c.adder.Add(1000, 2000)) +} + +// AfterRevive 复活后执行的函数 +func (c *Computer) AfterRevive() gone.AfterReviveError { + // boot + c.Compute() + + return nil +} +``` + +在上面代码中，请注意我们添加了两个工厂函数 `NewAdder() gone.Goner` 和 `func NewComputer() gone.Goner`，并且在函数前做了一个特殊的注释： +```go +//go:gone +``` + +请不要删除这个注释，这个注释的作用是告诉辅助工具如何生成代码的。 + +#### 4. 使用辅助工具 +请在`gen-code`目录下执行下面命令： +```bash +gone priest -s . -p main -f Priest -o priest.go +``` +这个命令的含义是，扫描当前目录生成一个 **牧师** 函数，它的函数名为 `Priest`，所在的包名为`main`，代码放到名为`priest.go`的文件中。 +代码执行完后，会在当前目录中生成一个文件`priest.go`，它的内容如下： + +```go +// Code generated by gone; DO NOT EDIT. +package main +import ( + "github.com/gone-io/gone" +) + +func Priest(cemetery gone.Cemetery) error { + cemetery.Bury(NewAdder()) + cemetery.Bury(NewComputer()) + return nil +} +``` +#### 5. 添加`main`函数 +文件名：main.go +```go +package main + +import "github.com/gone-io/gone" + +func main() { + gone.Run(Priest) +} +``` + +至此，我们就完成了整个小的Gone程序，它的文件结构如下： +```bash +. +├── go.mod +├── go.sum +├── goner.go # goner的定义 +├── main.go +└── priest.go # 生成的代码 +``` + +可以通过命令`go run .`来执行，程序将输出如下内容： +```code +Revive github.com/gone-io/gone/heaven +Revive github.com/gone-io/gone/cemetery +Revive main/Adder +Revive main/Computer +I want to compute! +1000 add 2000 is 3000 +``` \ No newline at end of file