up

gogf · Oct 31, 2024 · 0c38fd5 · 0c38fd5
1 parent 2e5c5e9
commit 0c38fd5
Show file tree

Hide file tree

Showing 35 changed files with 105 additions and 131 deletions.
diff --git a/docs/开发工具/交叉编译-build.md b/docs/开发工具/交叉编译-build.md
@@ -55,9 +55,9 @@ gfcli:
 | `varMap` |  | 自定义的内置变量键值对，构建的二进制中可以通过 `gbuild` 包获取编译信息。 | ```<br />gfcli:<br />  build:<br />    name:     "gf"<br />    arch:     "all"<br />    system:   "all"<br />    mod:      "none"<br />    cgo:      0<br />    varMap:<br />      k1: v1<br />      k2: v2<br />``` |
 | `exitWhenError` | `false` | 当编译发生错误时，立即停止后续执行，并退出编译流程（使用 `os.Exit(1)`） |  |
 | `dumpEnv` | `false` | 每次编译之前在终端打印当前编译环境的环境变量信息 |  |
-
+:::tip
 编译时的内置变量可以在运行时通过 `gbuild` 包 [构建信息-gbuild](../组件列表/系统相关/构建信息-gbuild.md) 获取。
-
+:::
 ## 使用示例
 
 ```bash

diff --git a/docs/开发工具/代码生成-gen/代码生成-gen.md b/docs/开发工具/代码生成-gen/代码生成-gen.md
@@ -4,9 +4,9 @@ title: '代码生成-gen(🔥重点🔥)'
 sidebar_position: 5
 hide_title: true
 ---
-
+:::info
 从 `v2` 版本开始，最新的 `CLI` 工具版本功能会随着 `GoFrame` 框架的最新版本编译，引入如果本地的 `CLI` 工具自动化生成的代码与项目的 `GoFrame` 框架版本出现兼容性问题时，建议升级项目框架版本，或者自定义安装旧版本的 `CLI` 工具。旧版本CLI工具安装方式参考仓库首页介绍： [https://github.com/gogf/gf-cli](https://github.com/gogf/gf-cli)
-
+:::
 ## 重要说明🔥
 
 - `CLI` 工具提供的代码生成功能，目的是 **规范化项目代码编写**、 **简化项目开发复杂度**， **让开发者能够把精力聚焦于业务逻辑本身**。

diff --git a/docs/开发工具/代码生成-gen/协议编译-gen pb.md b/docs/开发工具/代码生成-gen/协议编译-gen pb.md
@@ -4,9 +4,9 @@ title: '协议编译-gen pb'
 sidebar_position: 4
 hide_title: true
 ---
-
+:::tip
 该功能特性从 `v2.4` 版本开始提供。
-
+:::
 ## 基本介绍
 
 该命令用于编译 `proto` 文件，生成对应的 `protobuf go` 文件以及对应的控制器文件。
@@ -28,9 +28,9 @@ EXAMPLE
     gf gen pb
     gf gen pb -p . -a . -p .
 ```
-
+:::tip
 如果使用框架推荐的项目工程脚手架，并且系统安装了 `make` 工具，也可以使用 `make pb` 快捷指令。
-
+:::
 参数说明：
 
 | 名称 | 必须 | 默认值 | 含义 |

diff --git a/docs/开发工具/代码生成-gen/接口规范-gen ctrl.md b/docs/开发工具/代码生成-gen/接口规范-gen ctrl.md
@@ -4,9 +4,9 @@ title: '接口规范-gen ctrl'
 sidebar_position: 0
 hide_title: true
 ---
-
+:::tip
 该功能特性从 `v2.5` 版本开始提供。该命令目前仅支持 `HTTP` 接口开发， `GRPC` 部分请参考 `gen pb` 命令。未来会考虑 `HTTP` 及 `GRPC` 统一使用该命令生成控制器及 `SDK` 源代码。
-
+:::
 ## 基本介绍
 
 ### 解决痛点
@@ -83,9 +83,9 @@ EXAMPLE
     gf gen ctrl
 
 ```
-
+:::tip
 如果使用框架推荐的项目工程脚手架，并且系统安装了 `make` 工具，也可以使用 `make ctrl` 快捷指令。
-
+:::
 参数说明：
 
 | 名称 | 必须 | 默认值 | 含义 |

diff --git a/docs/开发工具/代码生成-gen/数据表PB-gen pbentity.md b/docs/开发工具/代码生成-gen/数据表PB-gen pbentity.md
@@ -4,9 +4,9 @@ title: '数据表PB-gen pbentity'
 sidebar_position: 5
 hide_title: true
 ---
-
+:::tip
 该功能特性从 `v2.4` 版本开始提供。
-
+:::
 ## 基本介绍
 
 该命令用于读取配置的数据库，根据数据表生成对应的 `proto` 数据结构文件。
@@ -70,9 +70,9 @@ CONFIGURATION SUPPORT
               option java_package  = "protobuf/demos";
               option php_namespace = "protobuf/demos";
 ```
-
+:::tip
 如果使用框架推荐的项目工程脚手架，并且系统安装了 `make` 工具，也可以使用 `make pbentity` 快捷指令。
-
+:::
 参数说明：
 
 | 名称 | 默认值 | 含义 | 示例 |

diff --git a/docs/开发工具/代码生成-gen/数据规范-gen dao.md b/docs/开发工具/代码生成-gen/数据规范-gen dao.md
@@ -6,9 +6,9 @@ hide_title: true
 ---
 
 `gen dao` 命令是 `CLI` 中最频繁使用、也是框架设计的工程规范能否准确落地的关键命令。该命令用于生成 `dao` 数据访问对象、 `do` 数据转化模型及 `entity` 实例数据模型 `Go` 代码文件。由于该命令的参数、选项较多，我们推荐使用配置文件来管理生成规则。
-
+:::tip
 关于框架项目工程规范介绍请查看 [代码分层设计](../../框架设计/工程开发设计/代码分层设计.md) 章节。
-
+:::
 ## 使用方式
 
 大部分场景下，进入项目根目录执行 `gf gen dao` 即可。以下为命令行帮助信息。
@@ -85,9 +85,9 @@ CONFIGURATION SUPPORT
             numeric:
               type: string
 ```
-
+:::tip
 如果使用框架推荐的项目工程脚手架，并且系统安装了 `make` 工具，也可以使用 `make dao` 快捷指令。
-
+:::
 ## 配置示例
 
 `/hack/config.yaml`

diff --git a/docs/开发工具/代码生成-gen/枚举维护-gen enums.md b/docs/开发工具/代码生成-gen/枚举维护-gen enums.md
@@ -4,9 +4,9 @@ title: '枚举维护-gen enums'
 sidebar_position: 3
 hide_title: true
 ---
-
+:::tip
 该功能特性为 **实验性特性**，从 `v2.4` 版本开始提供。
-
+:::
 ## 基本介绍
 
 该命令用于分析指定代码目录源码，按照规范生成枚举值信息以及 `Go` 代码文件， **主要用以完善 `OpenAPIv3` 文档中的枚举值维护**。

diff --git a/docs/开发工具/代码生成-gen/模块规范-gen service.md b/docs/开发工具/代码生成-gen/模块规范-gen service.md
@@ -4,12 +4,13 @@ title: '模块规范-gen service'
 sidebar_position: 2
 hide_title: true
 ---
-
-该功能特性从 `v2.1` 版本开始提供。
-
 :::warning
 该功能特性为 **实验性特性**。建议开发者以 `logic` 下的模块划分为主，梳理模块间关联关系，避免循环依赖，充分利用 `Golang` 编译器的循环依赖检测特性编写更高质量的项目代码。
 :::
+:::tip
+该功能特性从 `v2.1` 版本开始提供。
+:::
+
 
 ## 基本介绍
 
@@ -31,22 +32,22 @@ hide_title: true
 3. 可以按照一定的编码规范，从 `logic` 业务逻辑代码生成 `service` 接口定义代码。同时，也允许人工维护这部分 `service` 接口。
 
 ## 注意事项
-
+:::warning
 再次提醒，通过 `logic` 实现去生成 `service` 接口 **并不是一个代码管理的标准化做法**，只是提供另一个 **可供选择的**、便捷的代码管理方式。这种管理方式有优点也有缺点，优点是针对微服务场景的业务模块的接口自动生成比较方便；缺点是无法识别语法继承关系、无法生成父级嵌套类型的方法、抛弃了 `Golang` 编译时检测循环依赖的特性。
-
+:::
 **框架的工程管理当然也支持标准的接口代码管理方式**，即支持先定义 `service` 接口，再编码 `logic` 具体实现。需要注意的是，这个 `service` 的源代码中不能出现顶部工具的注释信息（工具依靠这个注释来判断该文件是否可覆盖😈），很多同学复制粘贴的时候把文件顶部注释保留了，就会引起手动维护接口文件失效。具体见截图注释：
 
 ![](/markdown/f4b70fc856dfcb17c4680839e32bb78b.png)
 
 ## 命令使用
 
 该命令通过分析给定的 `logic` 业务逻辑模块目录下的代码，自动生成 `service` 目录接口代码。
-
+:::info
 需要注意：
 
 1. 由于该命令是根据业务模块生成 `service` 接口，因此只会解析二级目录下的 `go` 代码文件，并不会无限递归分析代码文件。以 `logic` 目录为例，该命令只会解析 `logic/xxx/*.go` 文件。因此，需要 `logic` 层代码结构满足一定规范。
 2. 不同业务模块中定义的结构体名称在生成的 `service` 接口名称时可能会重复覆盖，因此需要在设计业务模块时保证名称不能冲突。
-
+:::
 该命令的示例项目请参考： [https://github.com/gogf/gf-demo-user](https://github.com/gogf/gf-demo-user)
 
 ### 手动模式
@@ -84,9 +85,9 @@ EXAMPLE
     gf gen service
     gf gen service -f Snake
 ```
-
+:::tip
 如果使用框架推荐的项目工程脚手架，并且系统安装了 `make` 工具，也可以使用 `make service` 快捷指令。
-
+:::
 参数说明：
 
 | 名称 | 必须 | 默认值 | 含义 |

diff --git a/docs/开发工具/兼容修复-fix.md b/docs/开发工具/兼容修复-fix.md
@@ -4,9 +4,9 @@ title: '兼容修复-fix'
 sidebar_position: 9
 hide_title: true
 ---
-
+:::tip
 该命令从框架 `v2.3` 版本开始提供。
-
+:::
 ## 使用场景
 
 当官方框架版本在升级过程中，会尽最大可能保证向下兼容性。但确实遇到十分困难的场景，难以保证完全向下兼容性的时候，并且是较小的兼容性问题，考虑到新增大版本号的成本较高，那么官方会通过该命令提供自动修正兼容问题。并且官方会保证该指令可重复执行，无副作用。

diff --git a/docs/开发工具/工具安装-install.md b/docs/开发工具/工具安装-install.md
@@ -57,9 +57,11 @@ go install github.com/gogf/gf/cmd/gf/[email protected] # 指定版本(版本需要 >= v2
 
 该命令往往是在 `gf` 命令行工具下载到本地后执行（注意执行权限），用于将 `gf` 命令安装到系统环境变量默认支持的目录路径中，以便于在系统任何的地方直接可以使用 `gf` 工具。
 
+:::note
 部分系统需要管理员权限支持。
 
 如果是 `MacOS` 下使用 `zsh` 的小伙伴可能会遇到别名冲突问题，可以通过 `alias gf=gf` 来解决，运行一次之后 `gf` 工具会自动修改 `profile` 中的别名设置，用户重新登录（或者重开终端）就好了。
+:::
 
 ## 使用示例
 

diff --git a/docs/开发工具/本地文档-doc.md b/docs/开发工具/本地文档-doc.md
diff --git a/docs/开发工具/框架升级-up.md b/docs/开发工具/框架升级-up.md
@@ -4,9 +4,9 @@ title: '框架升级-up'
 sidebar_position: 2
 hide_title: true
 ---
-
+:::tip
 该命令从框架 `v2.3` 版本开始提供。
-
+:::
 ## 使用方式
 
 ```bash

diff --git a/docs/开发工具/版本查看-version.md b/docs/开发工具/版本查看-version.md
@@ -55,5 +55,6 @@ CLI Built Detail:
 在打印的版本信息中会自动检测当前项目使用的 `GoFrame` 版本（自动解析 `go.mod`），并以 `GoFrame Version` 的信息打印出来。
 
 在 `CLI Built Detail` 信息中展示的是当前二进制编译时使用的各种 `Golang` 版本以及 `GoFrame` 版本信息，编译时的 `Git` 提交版本、当前二进制文件的编译时间。
-
-大家请勿将 `GoFrame Version` 和 `CLI Built Detail` 中的 `GF Version` 混淆。
+:::warning
+大家请勿将 `GoFrame Version` 和 `CLI Built Detail` 中的 `GF Version` 混淆。
+:::
diff --git a/docs/开发工具/自动编译-run.md b/docs/开发工具/自动编译-run.md
@@ -8,9 +8,9 @@ hide_title: true
 ## 注意事项
 
 由于 `Go` 是不支持热编译特性的，每一次代码变更后都要重新手动停止、编译、运行代码文件。 `run` 命令也不是实现热编译功能，而是提供了自动编译功能，当开发者修改了项目中的 `go` 文件时，该命令将会自动编译当前程序，并停止原有程序，运行新版的程序。
-
+:::tip
 `run` 命令会递归监控 **当前运行目录** 的所有 `go` 文件变化来实现自动编译。
-
+:::
 ## 使用帮助
 
 ```bash

diff --git a/docs/开发工具/镜像编译-docker.md b/docs/开发工具/镜像编译-docker.md
@@ -4,9 +4,9 @@ title: '镜像编译-docker'
 sidebar_position: 8
 hide_title: true
 ---
-
+:::tip
 从 `v2.5` 版本开始，考虑到各个工具命令的解耦性， `gf docker` 工具命令默认不再执行二进制构建编译，而是推荐大家通过 `Makefile` 构建脚本自行组织使用 `gf build, gf gen enums, gf docker` 等命令结合的方式来 **组合使用** 命令（工程项目中提供了对应的 `make build, make enums, make docker` 命令），组合使用更加灵活且易维护。
-
+:::
 ## 使用方式
 
 ```bash

diff --git a/docs/开发工具/项目创建-init.md b/docs/开发工具/项目创建-init.md
@@ -4,9 +4,9 @@ title: '项目创建-init'
 sidebar_position: 3
 hide_title: true
 ---
-
+:::tip
 从 `v2` 版本开始，项目的创建不再依赖远端获取，仓库模板已经通过 [资源管理](../核心组件/资源管理/资源管理.md) 的方式内置到了工具二进制文件中，因此项目创建速度非常迅速。
-
+:::
 ## 使用方式
 
 ```bash
@@ -30,10 +30,12 @@ EXAMPLE
 ```
 
 我们可以使用 `init` 命令在当前目录生成一个示例的 `GoFrame` 空框架项目，并可给定项目名称参数。生成的项目目录结构仅供参考，根据业务项目具体情况可自行调整。生成的目录结构请参考 [代码分层设计](../框架设计/工程开发设计/代码分层设计.md) 章节。
-
+:::note
 `GoFrame` 框架开发推荐统一使用官方的 `go module` 特性进行依赖包管理，因此空项目根目录下也有一个 `go.mod` 文件。
-
+:::
+:::tip
 工程目录采用了通用化的设计，实际项目中可以根据项目需要适当增减模板给定的目录。例如，没有 `kubernetes` 部署需求的场景，直接删除对应 `deploy` 目录即可。
+:::
 
 ## 使用示例
 

diff --git a/docs/核心组件/命令管理/命令管理-Parser解析.md b/docs/核心组件/命令管理/命令管理-Parser解析.md
@@ -8,9 +8,9 @@ hide_title: true
 ## 基本介绍
 
 命令行解析最主要的是针对于选项的解析， `gcmd` 组件提供了 `Parse` 方法，用于自定义解析选项，包括有哪些选项名称，每个选项是否带有数值。根据这一配置便可将所有的参数和选项进行解析归类。
-
+:::tip
 大部分场景下，我们并不需要显式创建 `Parser` 对象，因为我们有层级管理以及对象管理方式来管理多命令。但底层仍然是采用 `Parser` 方式实现，因此本章节大家了解原理即可。
-
+:::
 相关方法：
 
 更多 `Parser` 方法请参考接口文档： [https://pkg.go.dev/github.com/gogf/gf/v2/os/gcmd#Parser](https://pkg.go.dev/github.com/gogf/gf/v2/os/gcmd#Parser)

diff --git a/docs/核心组件/命令管理/命令管理-结构化参数.md b/docs/核心组件/命令管理/命令管理-结构化参数.md
@@ -174,9 +174,9 @@ arguments validation failed for command "http": The Name field is required
 ```
 
 执行后，报错了，这个错误来自于数据校验，表示必须参数（ `Name/Port`）必须传递。
-
+:::tip
 这里的报错打印了堆栈信息，因为 `GoFrame` 框架采用了全错误堆栈设计，所有组件错误都会带有自底向上的错误堆栈，以方便错误快速定位。当然我们可以通过 `RunWithError` 方法获取返回的错误对象关闭堆栈信息。
-
+:::
 我增加参数输入再试试：
 
 ```bash
@@ -225,9 +225,9 @@ $ main http my-http-server -p 8199
 ### 自动数据转换
 
 结构化的参数输入支持自动的数据类型转换，您只需要定义好数据类型，其他的事情交给框架组件即可。自动数据类型转换出现在框架的很多组件中，特别是 `HTTP/GRPC` 服务的参数输入中。底层数据转换组件使用的是： [类型转换](../类型转换/类型转换.md)
-
+:::tip
 命令行参数的数据转换采用 **不区分大小写、且忽略特殊字符** 的规则来匹配属性字段。例如，如果入参结构体中存在 `Name` 字段属性，无论命令行输入 `name` 还是 `NAME` 的命名参数，都将能被 `Name` 字段属性接收。
-
+:::
 ### 自动数据校验
 
 同样的，数据校验组件也是使用的统一的组件，具体请参考章节： [数据校验](../数据校验/数据校验.md)

diff --git a/docs/核心组件/对象管理.md b/docs/核心组件/对象管理.md
@@ -6,9 +6,9 @@ hide_title: true
 ---
 
 `GoFrame` 框架封装了一些常用的数据类型以及对象获取方法，通过 `g.*` 方法获取。
-
+:::tip
 `g` 是一个强耦合的模块，目的是为开发者在对频繁使用的类型/对象调用时提供便利。
-
+:::
 **使用方式**：
 
 ```go
@@ -75,9 +75,9 @@ type (
 ## 常用对象
 
 常用对象往往通过 `单例模式` 进行管理，可以根据不同的单例名称获取对应的对象实例，并在对象初始化时会自动检索获取配置文件中的对应配置项，具体配置项请查看对应对象的章节介绍。
-
+:::info
 注意事项：在运行时阶段，每一次通过 `g` 模块获取单例对象时都会有内部全局锁机制来保证操作和数据的并发安全性，原理性上来讲在并发量大的场景下会存在锁竞争的情况，但绝大部分的业务场景下开发者均不需要太在意锁竞争带来的性能损耗。此外，开发者也可以通过将获取到的单例对象保存到特定的模块下的内部变量重复使用，以此避免运行时锁竞争情况。
-
+:::
 ### `HTTP` 客户端对象
 
 ```go

diff --git a/docs/核心组件/日志组件/日志组件-Rotate特性.md b/docs/核心组件/日志组件/日志组件-Rotate特性.md
@@ -4,9 +4,9 @@ title: '日志组件-Rotate特性'
 sidebar_position: 13
 hide_title: true
 ---
-
+:::warning
 滚动切分目前属于实验性特性，如有问题请随时反馈。
-
+:::
 之前的章节中我们知道， `glog` 组件支持通过设置日志文件名称的方式，使得日志文件按照日期进行输出。从 `GF v1.12` 版本开始， `glog` 组件也支持对日志文件进行滚动切分的特性，该特性涉及到日志对象配置属性中的以下几个配置项：
 
 ```go