@colin4k1024/tsp 2.4.0

package/skills/goframe-v2/references//346/240/270/345/277/203/347/273/204/344/273/266//351/224/231/350/257/257/345/244/204/347/220/206//351/224/231/350/257/257/345/244/204/347/220/206-/351/224/231/350/257/257/347/240/201/347/211/271/346/200/247//351/224/231/350/257/257/345/244/204/347/220/206-/351/224/231/350/257/257/347/240/201/346/226/271/346/263/225.md

@@ -0,0 +1,162 @@
+## 创建带错误码的`error`
+
+### `NewCode/NewCodef`
+
+- 说明：功能同`New/Newf`方法，用于创建一个自定义错误信息的`error`对象，并包含堆栈信息，并增加错误码对象的输入。
+- 格式：
+
+    ```go
+    // NewCode creates and returns an error that has error code and given text.
+    NewCode(code gcode.Code, text ...string) error
+
+    // NewCodef returns an error that has error code and formats as the given format and args.
+    NewCodef(code gcode.Code, format string, args ...interface{}) error
+    ```
+
+- 实例：
+
+    ```go
+    func ExampleNewCode() {
+        err := gerror.NewCode(gcode.New(10000, "", nil), "My Error")
+        fmt.Println(err.Error())
+        fmt.Println(gerror.Code(err))
+
+        // Output:
+        // My Error
+        // 10000
+    }
+
+    func ExampleNewCodef() {
+        err := gerror.NewCodef(gcode.New(10000, "", nil), "It's %s", "My Error")
+        fmt.Println(err.Error())
+        fmt.Println(gerror.Code(err).Code())
+
+        // Output:
+        // It's My Error
+        // 10000
+    }
+    ```
+
+### `WrapCode/WrapCodef`
+
+- 说明：功能同`Wrap/Wrapf`方法，用于包裹其他错误`error`对象，构造成多级的错误信息，包含堆栈信息，并增加错误码参数的输入。
+- 格式：
+
+    ```go
+    // WrapCode wraps error with code and text.
+    // It returns nil if given err is nil.
+    WrapCode(code gcode.Code, err error, text ...string) error
+
+    // WrapCodef wraps error with code and format specifier.
+    // It returns nil if given `err` is nil.
+    WrapCodef(code gcode.Code, err error, format string, args ...interface{}) error
+    ```
+
+- 示例：
+
+    ```go
+    func ExampleWrapCode() {
+        err1 := errors.New("permission denied")
+        err2 := gerror.WrapCode(gcode.New(10000, "", nil), err1, "Custom Error")
+        fmt.Println(err2.Error())
+        fmt.Println(gerror.Code(err2).Code())
+
+        // Output:
+        // Custom Error: permission denied
+        // 10000
+    }
+
+    func ExampleWrapCodef() {
+        err1 := errors.New("permission denied")
+        err2 := gerror.WrapCodef(gcode.New(10000, "", nil), err1, "It's %s", "Custom Error")
+        fmt.Println(err2.Error())
+        fmt.Println(gerror.Code(err2).Code())
+
+        // Output:
+        // It's Custom Error: permission denied
+        // 10000
+    }
+    ```
+
+### `NewCodeSkip/NewCodeSkipf`
+
+- 说明：功能同`NewCode/NewCodef`，用于创建一个带错误码的`error`对象，但忽略部分堆栈信息（按照当前调用方法位置往上忽略）。
+- 格式：
+
+    ```go
+    // NewCodeSkip creates and returns an error which has error code and is formatted from given text.
+    // The parameter `skip` specifies the stack callers skipped amount.
+    func NewCodeSkip(code, skip int, text string) error
+
+    // NewCodeSkipf returns an error that has error code and formats as the given format and args.
+    // The parameter `skip` specifies the stack callers skipped amount.
+    func NewCodeSkipf(code, skip int, format string, args ...interface{}) error
+    ```
+
+### `WrapCodeSkip/WrapCodeSkipf`
+
+- 说明：功能同 `WrapCodeSkip/WrapCodeSkipf`，用于包裹一个带错误码的 `error` 对象，但忽略部分堆栈信息（按照当前调用方法位置往上忽略）。
+- 格式：
+
+    ```go
+    // WrapCodeSkip wraps error with code and text.
+    // It returns nil if given err is nil.
+    // The parameter `skip` specifies the stack callers skipped amount.
+    func WrapCodeSkip(code gcode.Code, skip int, err error, text ...string) error
+
+    // WrapCodeSkipf wraps error with code and text that is formatted with given format and args.
+    // It returns nil if given err is nil.
+    // The parameter `skip` specifies the stack callers skipped amount.
+    func WrapCodeSkipf(code gcode.Code, skip int, err error, format string, args ...interface{}) error
+    ```
+
+## `Code`
+
+- 说明：获取错误对象中的错误码。该方法会递归获取，如果当前错误对象不存在错误码时，该方法会追溯查找其上一级错误对象的错误码，以此类推。当给定的`error`参数不带有错误码信息时，该方法返回预定义的错误码`gcode.CodeNil`。
+- 格式：
+  
+    ```go
+    // Code returns the error code of `current error`.
+    // It returns `CodeNil` if it has no error code neither it does not implement interface Code.
+    func Code(err error) gcode.Code
+    ```
+
+- 示例：
+  
+    ```go
+    func ExampleCode() {
+        err1 := gerror.NewCode(gcode.CodeInternalError, "permission denied")
+        err2 := gerror.Wrap(err1, "operation failed")
+        fmt.Println(gerror.Code(err1))
+        fmt.Println(gerror.Code(err2))
+
+        // Output:
+        // 50:Internal Error
+        // 50:Internal Error
+    }
+    ```
+
+## `HasCode`
+
+- 说明：该方法判断给定的错误对象中是否包含指定的错误码。与`Code`方法类似，该方法也会追溯查找上一级错误的错误码。
+- 格式：
+  
+    ```go
+    // HasCode checks and reports whether `err` has `code` in its chaining errors.
+    func HasCode(err error, code gcode.Code) bool
+    ```
+
+- 示例：
+  
+    ```go
+    func ExampleHasCode() {
+        err1 := gerror.NewCode(gcode.CodeInternalError, "permission denied")
+        err2 := gerror.Wrap(err1, "operation failed")
+        fmt.Println(gerror.HasCode(err1, gcode.CodeOK))
+        fmt.Println(gerror.HasCode(err2, gcode.CodeInternalError))
+
+        // Output:
+        // false
+        // true
+    }
+    ```

package/skills/goframe-v2/references//346/240/270/345/277/203/347/273/204/344/273/266//351/224/231/350/257/257/345/244/204/347/220/206//351/224/231/350/257/257/345/244/204/347/220/206.md

@@ -0,0 +1,15 @@
+## 基本介绍
+
+`GoFrame` 框架提供了强大、丰富、统一的错误处理能力，由 `gerror` 组件实现。该组件也是框架统一的错误处理组件，框架所有组件如果存在错误返回时，均带有堆栈信息，方便开发者快速定位问题。
+
+**使用方式**：
+
+```go
+import "github.com/gogf/gf/v2/errors/gerror"
+```
+
+**接口文档**：
+
+[https://pkg.go.dev/github.com/gogf/gf/v2/errors/gerror](https://pkg.go.dev/github.com/gogf/gf/v2/errors/gerror)
+
+## 相关文档

package/skills/goframe-v2/references//346/241/206/346/236/266/350/256/276/350/256/241/Golang/346/236/232/344/270/276/345/200/274/347/256/241/347/220/206.md

@@ -0,0 +1,36 @@
+## Go实现枚举值
+
+`Go` 语言并没有提供 `enum` 的定义，我们可以使用 `const` 来模拟枚举类型，这也是 `Go` 语言中约定俗成的方式。
+
+例如，在 `Kubernetes` 项目中，有大量的以常量形式定义的"枚举值"：
+
+```go
+// PodPhase is a label for the condition of a pod at the current time.
+type PodPhase string
+
+// These are the valid statuses of pods.
+const (
+    // PodPending means the pod has been accepted by the system, but one or more of the containers
+    // has not been started. This includes time before being bound to a node, as well as time spent
+    // pulling images onto the host.
+    PodPending PodPhase = "Pending"
+    // PodRunning means the pod has been bound to a node and all of the containers have been started.
+    // At least one container is still running or is in the process of being restarted.
+    PodRunning PodPhase = "Running"
+    // PodSucceeded means that all containers in the pod have voluntarily terminated
+    // with a container exit code of 0, and the system is not going to restart any of these containers.
+    PodSucceeded PodPhase = "Succeeded"
+    // PodFailed means that all containers in the pod have terminated, and at least one container has
+    // terminated in a failure (exited with a non-zero exit code or was stopped by the system).
+    PodFailed PodPhase = "Failed"
+    // PodUnknown means that for some reason the state of the pod could not be obtained, typically due
+    // to an error in communicating with the host of the pod.
+    PodUnknown PodPhase = "Unknown"
+)
+```
+
+## 如何跨服务高效维护枚举值
+
+如果只是项目内部使用枚举值比较简单，定义完了内部使用即可，但涉及到跨服务之间调用，或者前后端协作时，效率就比较低了。当服务需要给外部调用者展示接口能力时，往往需要生成 `API` 接口文档（或者接口定义文件，例如 `proto`），往往也需要根据接口文档（文件）生成调用的客户端 `SDK`。
+
+如果是接口定义文件，例如 `proto`，往往可以直接查看源码来解决这个问题，问题不大。我们这里主要讨论的是接口文档维护枚举值的问题，特别是前后端协作时通过 `OpenAPI` 标准协议来维护枚举值的问题。这里我们提供了专门的工具来维护这些枚举值，具体请参考章节： [枚举维护-gen enums](../开发工具/代码生成-gen/枚举维护-gen%20enums.md)

package/skills/goframe-v2/references//346/241/206/346/236/266/350/256/276/350/256/241//345/267/245/347/250/213/345/274/200/345/217/221/350/256/276/350/256/241//344/273/243/347/240/201/345/210/206/345/261/202/350/256/276/350/256/241.md

@@ -0,0 +1,73 @@
+:::tip
+代码分层的意义在于将程序逻辑进一步解耦，将层级之间的数据流和依赖关系设计为单向链路，使得系统架构更加灵活易扩展。
+:::
+## 一、基本介绍
+
+`GoFrame` 作为一款工程化完备的基础开发框架，有其独特的框架设计理念，这一章节我们来介绍一下她的代码分层设计。对于服务端业务代码的分层设计模式中，我们比较常见的是 `MVC` 设计模式和三层架构设计模式( `3-Tier Architecture`)。
+
+## 二、 `MVC` 设计模式
+
+我们先来回顾一下经典的 `MVC` 设计模式。
+
+图1\. MVC设计模式
+
+### 简要介绍
+
+`M` 代表模型( `Model`)，表示业务规则封装。在 `MVC` 的三个部件中，模型拥有最多的处理任务。被模型返回的数据是中立的，模型与数据格式无关，这样一个模型能为多个视图提供数据，由于应用于模型的代码只需写一次就可以被多个视图重用，所以减少了代码的重复性。
+
+`V` 代表视图( `View`)，用户看到并与之交互的界面。比如由 `HTML` 元素组成的网页界面，或者软件的客户端界面。 `MVC` 的好处之一在于它能为应用程序处理很多不同的视图。在视图中其实没有真正的处理发生，它只是作为一种输出数据并允许用户操纵的方式。
+
+`C` 代表控制器( `Controller`)，接受用户的输入并调用模型和视图去完成用户的需求，控制器本身不输出任何东西和做任何处理。它只是接收请求并决定调用哪个模型构件去处理请求，然后再确定用哪个视图来显示返回的数据。
+
+这种设计模式比较简单，比较合适于需要服务端渲染页面的业务场景，对于 `SEO` 来说也比较友好。但随着 `MVVM` 开发模式的兴起，以及前端技术的快速发展，特别是一些前端开发框架如 `Vue`、 `React`、 `Angular` 之类的项目出现，服务端的 `MVC` 设计模式使用场景变得越来越少。
+
+### 痛点描述
+
+针对于业务逻辑并不是特别复杂的业务场景项目， `MVC` 还能游刃有余，但随着业务逻辑变得庞大复杂， `MVC` 设计模式的项目维护成本上升的问题变得越来越明显。特别是随着互联网项目微服务架构的发展， `MVC` 设计模式在大部分的互联网项目开发中变得越来越鸡肋。究其原因，主要的几点：
+
+- 视图展示与数据操作方式的进一步剥离，特别是移动端的发展，前端 `MVVM` 框架的发展，我们大多数场景下已不再需要服务端渲染 `View`。
+- `MVC` 的代码分层设计模式其实粒度较粗：
+  - `Model` 层级的代码既维护着数据，也封装着业务逻辑，随着业务逻辑变得越来越复杂，这一层功能逻辑会变得越来越臃肿不易维护。
+  - 对于团队管理来讲， `Controller` 和 `Model` 的职责边界比较模糊，对于开发人员写好代码的要求会比较高。概念看似简单，但是却难以适应工业化的软件生产。
+
+## 三、 `3-Tier Architecture`
+
+`GoFrame` 框架推荐的代码分层设计模式为三层架构设计（ `3-Tier Architecture`），但在具体的实现中，对这种结构设计模式进行了一定的改进。三层架构设计能够很好地体现出软件设计"高内聚，低耦合"的设计思想。
+
+图2\. 三层架构设计模式
+
+传统的三层架构设计如上图，将项目代码划分了三层，每一层有其独自的职责边界。但在大多数的场景中，我们常看到的是以下的分层结构，将数据结构模型再进一步地抽离了出来统一维护。
+
+图3\. 常见三层架构设计模型
+
+### 表示层 \- `UI`
+
+`User Interface` 位于三层构架的最上层，与用户直接接触，主要是 `B/S` 中的 `WEB` 页面，也可以是 `API` 接口。表示层的主要功能是实现系统数据的传入与输出，在此过程中不需要借助逻辑判断操作就可以将数据传送到 `BLL` 系统中进行数据处理，处理后会将处理结果反馈到表示层中。换句话说，表示层就是实现用户界面/ `API` 接口功能，将用户的需求传达和反馈，并用 `BLL` 或者是 `Model` 进行调试，保证用户体验。
+
+### 业务逻辑层 - `BLL`
+
+`Business Logic Layer` 的功能是对具体问题进行逻辑判断与执行操作，接收到表现层 `UI` 的用户指令后，会连接数据访问层 `DAL`，业务逻辑层在三层构架中位于表示层与数据层中间位置，同时也是表示层与数据层的桥梁，实现三层之间的数据连接和指令传达，可以对接收数据进行逻辑处理，实现数据的增删改查等功能，并将处理结果反馈到表示层 `UI` 中，实现软件功能。
+
+### 数据访问层 - `DAL`
+
+`Data Access Layer` 是数据库的主要操控系统，实现数据的增删改查等操作，并将操作结果反馈到业务逻辑层 `BLL`。在实际运行的过程中，数据访问层没有逻辑判断能力，为了实现代码编写的严谨性，提高代码阅读程度，一般软件开发人员会在该层中实现通用数据能力进行封装（例如通过 `ORM` 组件）来保证数据访问层 `DAL` 数据处理功能。
+
+### 模型定义层 - `Model`
+
+模型定义也常用 `Entity` 实体对象来表示，主要用于数据库表的映射对象，在信息系统软件实际开发的过程中，要建立对象实例，将关系数据库表采用对象实体化的方式表现出来，辅助软件开发中对各个系统功能的控制与操作执行。建立实体类库，进而实现各个结构层的参数传输，提高代码的阅读性。从本质上看，实体类库主要服务于表示层、业务逻辑层以及数据访问层，在三层之间进行数据参数传输，强化数据表示的简约性。
+
+需要注意区分的是，这里的 `Model` 和 `MVC` 设计模式中的 `Model` 虽然都是一个名字但是差别巨大，职责完全不同。
+
+### 三层架构设计与 `MVC`
+
+由于 `MVC` 也是三层结构，因此有的同学也会将 `MVC` 笼统地归纳于三层架构设计中，从字面意义上来讲似乎也没什么问题。不过两者还是存在一定的区别。
+
+图4\. 三层架构设计与MVC
+
+可以看到，在三层架构设计中， `UI` 表示层即相当于 `MVC` 的 `View` 和 `Controller` 层，原本在 `MVC` 中这两层的逻辑应当是比较"轻量"的，因此被合并为一层进行统一管理也可以理解。比较重要的一点是，原本 `MVC` 中的 `Model` 被拆分为了 `BLL` 和 `DAL`，即将业务逻辑与数据访问进行分离，将原本臃肿的 `Model` 进行了进一步的解耦，有利于项目的更好维护。
+:::tip
+软件架构的演变过程，特别是互联网软件架构的演变过程，本质也就是将业务逻辑不断解耦的过程。
+:::
+## 四、更进一步了解
+
+代码分层思想是最基础的工程设计入门，我们需要将分层思想进行落地，具体请参考： [工程目录设计🔥](工程目录设计.md)

package/skills/goframe-v2/references//346/241/206/346/236/266/350/256/276/350/256/241//345/267/245/347/250/213/345/274/200/345/217/221/350/256/276/350/256/241//345/267/245/347/250/213/347/233/256/345/275/225/350/256/276/350/256/241.md

@@ -0,0 +1,165 @@
+工程目录设计是代码分层设计的进一步落地，建议您先仔细阅读： [代码分层设计](代码分层设计.md)
+:::tip
+这是 `GoFrame` 框架针对 **业务项目** 的目录设计，主体的思想来源于三层架构，但在具体实现中，对其进行了一定的改进和细化使其更符合工程实践和时代进步。
+:::
+## 一、工程目录结构
+
+`GoFrame` 业务项目基本目录结构如下（以 `Single Repo` 为例）：
+
+```text
+/
+├── api
+├── hack
+├── internal
+│   ├── cmd
+│   ├── consts
+│   ├── controller
+│   ├── dao
+│   ├── model
+│   |   ├── do
+│   │   └── entity
+│   └── service
+├── manifest
+├── resource
+├── utility
+├── go.mod
+└── main.go
+```
+:::info 提示
+框架的工程目录采用了 **通用化的设计**，以满足不同复杂程度业务项目的需求，但实际项目中可以根据项目需要 **适当增减默认的目录**。
+:::
+| 目录/文件名称    | 说明     | 描述                                                                                      |
+| ---------------- | -------- | ----------------------------------------------------------------------------------------- |
+| `api`            | 对外接口 | 对外提供服务的输入/输出数据结构定义。考虑到版本管理需要，往往以 `api/xxx/v1...` 存在。    |
+| `hack`           | 工具脚本 | 存放项目开发工具、脚本等内容。例如， `CLI` 工具的配置，各种 `shell/bat` 脚本等文件。      |
+| `internal`       | 内部逻辑 | 业务逻辑存放目录。通过 `Golang internal` 特性对外部隐藏可见性。                           |
+| `  - cmd`        | 入口指令 | 命令行管理目录。可以管理维护多个命令行。                                                  |
+| `  - consts`     | 常量定义 | 项目所有常量定义。                                                                        |
+| `  - controller` | 接口处理 | 接收/解析用户输入参数的入口/接口层。                                                      |
+| `  - dao`        | 数据访问 | 数据访问对象，这是一层抽象对象，用于和底层数据库交互，仅包含最基础的 `CRUD` 方法          |
+| `  - model`      | 结构模型 | 数据结构管理模块，管理数据实体对象，以及输入与输出数据结构定义。                          |
+| `    - do`       | 领域对象 | 用于 `dao` 数据操作中业务模型与实例模型转换，由工具维护，用户不能修改。                   |
+| `    - entity`   | 数据模型 | 数据模型是模型与数据集合的一对一关系，由工具维护，用户不能修改。                          |
+| `  - service`    | 业务实现 | 业务逻辑的具体实现和封装，如`service/user`用户模块、`service/order`订单模块等。                       |
+| `manifest`       | 交付清单 | 包含程序编译、部署、运行、配置的文件。常见内容如下：                                      |
+| `  - config`     | 配置管理 | 配置文件存放目录。                                                                        |
+| `  - docker`     | 镜像文件 | `Docker` 镜像相关依赖文件，脚本文件等等。                                                 |
+| `  - deploy`     | 部署文件 | 部署相关的文件。默认提供了 `Kubernetes` 集群化部署的 `Yaml` 模板，通过 `kustomize` 管理。 |
+| `  - protobuf`   | 协议文件 | `GRPC` 协议时使用的 `protobuf` 协议定义文件，协议文件编译后生成 `go` 文件到 `api` 目录。  |
+| `resource`       | 静态资源 | 静态资源文件。这些文件往往可以通过 资源打包/镜像编译 的形式注入到发布文件中。             |
+| `go.mod`         | 依赖管理 | 使用 `Go Module` 包管理的依赖描述文件。                                                   |
+| `main.go`        | 入口文件 | 程序入口文件。                                                                            |
+
+### 对外接口 - `api` + `controller`
+
+对外接口包含两部分：接口定义（ `api`）+接口实现（ `controller`）。
+
+服务接口的职责类似于三层架构设计中的 `UI` 表示层，负责接收并响应客户端的输入与输出，包括对输入参数的过滤、转换、校验，对输出数据结构的维护，并调用 `service` 实现业务逻辑处理。
+
+#### 接口定义 - `api`
+
+`api` 包用于与客户端约定的数据结构输入输出定义，往往与具体的业务场景强绑定。
+
+#### 接口实现 - `controller`
+
+`controller` 用于接收 `api` 的输入，可以直接在 `controller` 中实现业务逻辑，或者调用一个或多个 `service` 包实现业务逻辑，将执行结果封装为约定的 `api` 输出数据结构。
+
+### 业务实现 - `service`
+
+业务实现的职责类似于三层架构设计中的 `BLL` 业务逻辑层，负责具体业务逻辑的实现以及封装。在该目录下，具体的业务模块使用子目录独立封装维护，如下示例：
+```bash
+service
+├── user   # 用户模块
+├── order  # 订单模块
+└── ...    # 其他业务模块
+```
+
+### 结构模型 - `model`
+
+`model` 包的职责类似于三层架构中的 `Model` 模型定义层。模型定义代码层中仅包含全局的、公共的数据结构定义，供项目中所有的业务模块共同引用。。
+
+#### 数据模型 - `entity`
+
+与数据集合绑定的程序数据结构定义，通常和数据表一一对应，字段类型与数据表字段类型一致。
+
+#### 领域模型 - `do`
+
+字段与数据表字段一一对应的程序数据结构定义，主要用于 `dao` 数据访问层中数据的输入输出定义，供 `service` 层调用使用。
+
+#### 业务模型 - `model`
+
+与业务相关的通用数据结构定义，供项目中所有的业务模块共同引用。
+
+### 数据访问 - `dao`
+
+`dao` 包的职责类似于三层架构中的 `DAL` 数据访问层，数据访问层负责所有的数据访问收口。
+
+三层架构设计与框架代码分层映射关系
+
+## 二、请求分层流转
+
+### cmd
+
+`cmd` 层负责引导程序启动，显著的工作是初始化逻辑、注册路由对象、启动 `server` 监听、阻塞运行程序直至 `server` 退出。
+
+### api
+
+上层 `server` 服务接收客户端请求，转换为 `api` 中定义的 `Req` 接收对象、执行请求参数到 `Req` 对象属性的类型转换、执行 `Req` 对象中绑定的基础校验并转交 `Req` 请求对象给 `controller` 层。
+
+### controller
+
+`controller` 层负责接收 `Req` 请求对象后做一些业务逻辑校验，可以直接在 `controller` 中实现业务逻辑，或者调用一个或多个 `service` 实现业务逻辑，将执行结果封装为约定的 `Res` 数据结构对象返回。
+
+### model
+
+`model` 层中维护了所有公共的业务模型数据结构。
+
+### service
+
+`service` 层的业务逻辑需要通过调用 `dao` 来实现数据的操作，调用 `dao` 时需要传递 `do` 数据结构对象，用于传递查询条件、输入数据。 
+
+### dao
+
+`dao` 层通过框架的 `ORM` 抽象层组件与底层真实的数据库交互。
+
+## 三、常见问题解答
+
+### 框架是否支持常见的 `MVC` 开发模式
+
+**当然！**
+
+作为一款模块化设计的基础开发框架， `GoFrame` 不会局限代码设计模式，并且框架提供了非常强大的模板引擎核心组件，可快速用于 `MVC` 模式中常见的模板渲染开发。相比较 `MVC` 开发模式，在复杂业务场景中，我们更推荐使大家用三层架构设计模式。
+
+### 当 `api` 与 `model` 层存在重复数据结构时如何维护
+
+在 `api` 中定义的数据结构是 **对外使用的**，与具体的业务场景绑定（如具体的页面交互逻辑、单一的接口功能），数据结构是由上层展示层前置决定的； `model` 中定义的数据结构是 **服务内部公共使用的**，并且 `model` 中的数据结构可以随意在内部修改而并不会影响对外 `api` 接口的兼容性。
+
+**注意 `model` 中的数据结构不应该直接暴露给外部使用**，并且在框架的工程设计中刻意将 `model` 目录放到了 `internal` 目录下。也不应该在 `api` 层中对 `model` 中的数据结构进行 **别名类型定义** 供外部访问。一旦将 `model` 中的数据结构应用到了 `api` 层中，内部 `model` 数据结构的修改会直接影响到 `api` 接口的兼容性。
+
+**如果两者出现重复的数据结构、常量、枚举类型等，建议将数据结构定义到 `api` 层中**。服务内部逻辑可以直接访问 `api` 层的数据结构。 `model` 层的数据结构也可以直接引用 `api` 层的数据结构，但是反之则不行。
+
+我们来看一个示例，便于更好地理解：
+
+### 如何清晰界定和管理 `service` 和 `controller` 的分层职责
+
+`controller` 层处理 `Req/Res` 外部接口请求。负责接收、校验请求参数，可以直接在 `controller` 中实现业务处理逻辑，或者调用 **一个或多个** `service` 来实现业务逻辑处理，将执行结果封装为约定的 `api` 输出数据结构返回。 `service` 层处理 `Input/Output` 内部方法调用。负责内部 **可复用** 的业务逻辑封装，封装的方法粒度往往比较细。
+
+**通常来讲，开发接口时只需要编写 `controller` 层中的接口实现业务逻辑即可，当存在重复代码逻辑时，再从各个 `controller` 接口实现逻辑中抽象沉淀到 `service` 层**。如果从 `controller` 层直接透传 `Req` 对象给 `service`，同时 `service` 直接返回 `Res` 数据结构对象，该方法也就与外部接口耦合，仅面向外部接口服务，难以复用，这样会增加技术债务成本。
+
+### 如何清晰界定和管理 `service` 和 `dao` 的分层职责
+
+这是一个很经典的问题。
+
+**痛点：**
+
+常见的，开发者易把 **数据相关的业务逻辑实现** 封装到 `dao` 代码层中，而 `service` 代码层只是简单的 `dao` 调用，这么做的话会使得原本负责维护数据的 `dao` 层代码越来越繁重，反而业务逻辑 `service` 层代码显得比较轻。开发者存在困惑，我写的业务逻辑代码到底应该放到 `dao` 还是 `service` 中？
+
+业务逻辑其实绝大部分时候都是对数据的 `CRUD` 处理，这样做会使得几乎所有的业务逻辑会逐步沉淀在 `dao` 层中，业务逻辑的改变其实会频繁对 `dao` 层的代码产生修改。例如：数据查询需求，在初期的时候可能只是简单的逻辑，目前代码放到 `dao` 好像也没问题，但是查询需求增加或变化变得复杂之后，那么必定会继续维护修改原有的 `dao` 代码，同时 `service` 代码也可能同时做更新。原本仅限于 `service` 层的业务逻辑代码职责与 `dao` 层代码职责模糊不清、耦合较重，原本只需要修改 `service` 代码的需求变成了同时修改 `service` + `dao`，使得项目中后期的开发维护成本大大增加。
+
+**建议：**
+
+我们的建议。 `dao` 层的代码应该尽量保证通用性，并且大部分场景下不需要增加额外方法，只需要使用一些通用的链式操作方法拼凑即可满足。业务逻辑、包括看似只是简单的数据操作的逻辑都应当封装到 `service` 中。 `service` 中包含多个业务模块，每个模块独自管理自己的 `dao` 对象。理想情况下， `service` 与 `service` 之间通过相互调用方法来实现数据通信，而不是随意去调用其他 `service` 模块的 `dao` 对象。
+
+### 为什么要使用 `internal` 目录包含业务代码
+
+`internal` 目录是 `Golang` 语言专有的特性，防止同级目录外的其他目录引用其下面的内容。业务项目中存在该目录的目的，是避免若项目中存在多个子项目（特别是大仓管理模式时），多个项目之间无限制随意访问，造成难以避免的多项目不同包之间耦合。

package/skills/goframe-v2/references//346/241/206/346/236/266/350/256/276/350/256/241//345/267/245/347/250/213/345/274/200/345/217/221/350/256/276/350/256/241//345/276/256/346/234/215/345/212/241/345/244/247/344/273/223/347/256/241/347/220/206/346/250/241/345/274/217.md

@@ -0,0 +1,122 @@
+本文旨在介绍 `GoFrame` 框架对微服务-单仓管理( `mono-repo`)模式的支持，指导开发者如何在微服务-单仓管理( `mono-repo`)模式下进行代码开发和分工协作。
+
+## 一、前置阅读
+
+在开始本章节之前，建议先了解一下单体仓库( `monolith`)、微服务-多仓管理( `multi-repo`)、
+微服务-单仓管理( `mono-repo`)的基本概念以及各自的优缺点： 
+[单体仓库与多仓库都有哪些优势劣势，微服务选择哪种方案比较好？](https://johng.cn/management/monorepo-vs-multirepo)
+
+代码仓库的管理约束并不属于框架职责的一部分， `GoFrame` 框架的脚手架本身也支持两种仓库项目初始化的命令 \- 单仓库( `mono-repo`)、多仓库( `monolith/multi-repo`)，以满足不同团队的需求。具体选择哪种代码仓库管理模式由开发团队根据自身需求、场景、习惯来自行选择。
+:::tip
+为简化和清晰微服务-单仓管理( `mono-repo`)的描述，后续我们统一以 **大仓管理** 来指代微服务-单仓管理( `mono-repo`)模式。
+:::
+## 二、大仓管理
+
+### 1、仓库职责范围的划分
+
+通过前置阅读的文章大家也知道，这个世界上没有银弹，大仓有优点也有缺点，其中最明显的缺点就是 **权限的管控** 以及 **仓库的膨胀**。为了更好地管理代码仓库，避免这两点缺陷带来更高的成本，我们建议尽可能减小大仓中的微服务规模。至于仓库中需要维护哪些微服务，需要根据服务之间的协作频率来决定。
+
+#### 1）当团队内部的协作频率高于团队间协作频率时
+
+- 典型的场景是针对 **非微服务化架构的产品**，可以将服务管理的权限职责按照各个业务团队进行划分。这样团队内部可以将分散的若干服务通过统一的代码仓库维护起来，充分利用大仓管理的优势，提高团队内部的开发和维护效率。
+- 另外一种场景是业务的微服务数量本身不多（例如 `50` 个以内），这个时候也可以合并成一个大仓进行管理。需要注意，大仓管理的服务数量并不是由组织架构中的人员数量来决定的。
+
+#### 2）当多个团队之间的多个服务协作频率非常高时
+
+当业务的微服务数量比较多，并且各个服务之间的交互协作比较频繁，那么可以考虑将这些服务合并到大仓中进行管理，可以极大提高协作效率。这种情况大部分出现在微服务在同一产品线、跨团队但不跨中心或部门的情况下。但由于涉及跨多个团队的协作，这对人员的组织架构管理有一定要求，需要由一定权限的管理者来推动。
+:::tip
+微服务的管理并不仅是代码的组织管理，更是人员组织架构的管理。
+:::
+### 2、大仓下的微服务间如何协作
+
+#### 1）代码可见性的管理
+
+服务与服务之间能够暴露的仅仅是接口，也就是 `API`。各个服务内部的逻辑应当对外不可见。在 `Golang` 里面有很好的 `internal` 特性，正好可以满足可见性管理的要求。如下图大仓代码示例，在 `app` 目录下管理了若干的服务，每一个服务暴露了自身的 `api` 目录，供其他服务直接引用（提高服务间协作效率），但内部的业务逻辑包含在了 `internal` 目录下，对其他服务不可见（也就无法引用）。
+
+#### 2）服务间接口的调用
+
+协议文件单独维护到各自服务目录下，如果涉及到协议文件编译，那么编译的文件也存放到自身的服务目录下。调用端不需要单独再对目标服务的协议文件重新编译管理。以 `HTTP API` 的接口定义为例，调用端可以直接引用目标端服务的 `API` 接口定义：（以下截图中 `khaos-shark` 为调用端， `khaos-oss` 为服务端）
+
+针对于微服务间的 `RPC` 接口调用也是同样的道理：（以下截图中 `user-api` 为调用端， `user-rpc` 为服务端）
+
+#### 3）兼容性的严格要求
+
+通过以上介绍可以发现，通过大仓的代码管理，使得大仓中所有服务的版本保持一致，每当依赖的服务 `API` 更新时，调用端服务（使用的 `SDK`）也将自动得到更新。这就要求仓库中所有服务的接口设计， **必须严格保证兼容性**，否则接口间调用将会出现问题：轻者调用端服务编译失败需要调整代码，重者编译成功但运行时报错影响业务。此外，公共引用的大仓基础组件也会受到兼容性的影响。
+
+保证兼容性代码设计的几个要点：
+
+- **不随意删减接口参数，修改参数名称、参数类型、参数校验逻辑。**
+- **当接口必须要进行非兼容更新时，应当使用接口版本号来管理（如 `v1, v2, v3...`）。**
+- **公共组件尽量使用稳定成熟的外部组件，如果是必要的自定义组件，需要保证对外暴露方法的兼容性。** _举个例子：一些很基础的功能，比如说 `json.Marshal&Unmarshal`，有的人封装了一些库/函数，但是后面的人可能都不知道这个库，也不太信任这个函数，就会又重新写一个...久而久之这些库/函数却又无人维护。_
+
+### 3、大仓下的微服务容器化支持
+
+#### 1）镜像仓库的统一管理
+
+分散的镜像仓库将会降低服务容器化的管理维护效率。为便于统一服务容器化管理，我们建议大仓下的服务使用统一的镜像仓库。镜像仓库的地址统一维护到各个服务下的工具配置文件中：
+
+#### 2）统一编译、提交指令
+
+框架提供了常用的指令来实现程序的编译、镜像的编译、镜像的提交。
+
+- `make build`
+
+编译程序，生成二进制文件。
+
+更多介绍请参考文档： [交叉编译-build](../../开发工具/交叉编译-build.md)
+
+- `make image`
+
+编译程序并编译镜像，生成 `Docker` 镜像。
+
+通过 `make image TAG=xxx` 可以指定编译生成的镜像标签名称。
+
+更多介绍请参考文档： [镜像编译-docker](../../开发工具/镜像编译-docker.md)
+
+- `make image.push`
+
+编译程序、编译镜像并推送镜像到已配置好的镜像仓库。
+
+通过 `make image.push TAG=xxx` 可以指定编译生成的镜像标签名称。
+
+#### 3）统一部署、调试指令
+
+框架提供了常用的指令来实现 `Kubernetes` 集群的容器化部署，以及一体化编译部署的开发指令。
+
+- `make deploy TAG=xxx`
+
+部署当前服务到本地 `kubeconfig` 已连接的 `kubernetes` 集群中，其中的 `TAG` 用于指定 `deploy` 目录下的 `overlays` 目录。管理部署 `yaml` 文件使用的是行业内常用的 `kustomize` 工具，具体介绍文档请参考： [https://kubernetes.io/zh-cn/docs/tasks/manage-kubernetes-objects/kustomization/](https://kubernetes.io/zh-cn/docs/tasks/manage-kubernetes-objects/kustomization/)
+
+- `make image.push deploy TAG=xxx`
+
+该命令是开发调试指令，用于一条指令 编译二进制文件、编译并推送 `Docker` 镜像、部署 `Kubernetes` 应用并重启应用。
+
+### 4、大仓下的框架其他指令
+
+框架针对于项目工程管理提供了丰富的工具指令支持，这些指令往往需要再特定的服务目录下执行，例如 `./app/服务名称`
+
+#### 1） `make cli`
+
+用于升级本地的框架 `CLI` 到最新稳定版本。
+
+#### 2） `make up`
+
+用于升级本地的框架到最新社区稳定版本。
+
+更多介绍请参考文档： [框架升级-up](../../开发工具/框架升级-up.md)
+
+#### 3） `make dao`
+
+用于生成 `DAO/Entity/DO` 代码文件。
+
+更多介绍请参考文档： [数据规范-gen dao](../../开发工具/代码生成-gen/数据规范-gen%20dao.md)
+
+#### 4） `make enums`
+
+用于解析指定代码目录（默认为 `api` 目录）并自动生成 `enums` 加载代码。
+
+更多介绍请参考文档： [枚举维护-gen enums](../../开发工具/代码生成-gen/枚举维护-gen%20enums.md)
+
+#### 5）更多指令
+
+更多的指令支持请参考框架官网工具介绍章节： [开发工具](../../开发工具/开发工具.md)

package/skills/goframe-v2/references//347/273/204/344/273/266/345/210/227/350/241/250//345/212/237/350/203/275/350/260/203/350/257/225//350/260/203/350/257/225/345/212/237/350/203/275-gdebug.md

@@ -0,0 +1,38 @@
+`goframe` 框架提供了丰富的调试功能，由 `gdebug` 组件实现。
+:::warning
+所谓的“调试”方法大多数和开发环境有一定关系，包含堆栈和调用链信息分析，并且性能往往不是特别高。
+:::
+**使用方式：**
+
+```go
+import "github.com/gogf/gf/v2/debug/gdebug"
+```
+
+**接口文档：**
+
+[https://pkg.go.dev/github.com/gogf/gf/v2/debug/gdebug](https://pkg.go.dev/github.com/gogf/gf/v2/debug/gdebug)
+
+**方法列表：**
+
+```go
+func BinVersion() string
+func BinVersionMd5() string
+func Caller(skip ...int) (function string, path string, line int)
+func CallerDirectory() string
+func CallerFileLine() string
+func CallerFileLineShort() string
+func CallerFilePath() string
+func CallerFunction() string
+func CallerPackage() string
+func CallerWithFilter(filter string, skip ...int) (function string, path string, line int)
+func FuncName(f interface{}) string
+func FuncPath(f interface{}) string
+func GoroutineId() int
+func PrintStack(skip ...int)
+func Stack(skip ...int) string
+func StackWithFilter(filter string, skip ...int) string
+func StackWithFilters(filters []string, skip ...int) string
+func TestDataPath(names ...string) string
+```
+
+> 熟悉 `PHP` 的同学可能比较好理解，这里某些方法其实和 `PHP` 的部分 [魔术常量](https://www.php.net/manual/en/language.constants.predefined.php) 功能一致。 `CallerDirectory` 对应 `__DIR__`， `CallerFilePath` 对应 `__FILE__`， `CallerFunction` 对应 `__FUNCTION__`。

package/skills/goframe-v2/references//347/273/204/344/273/266/345/210/227/350/241/250//345/212/240/345/257/206/350/247/243/345/257/206/AES/347/256/227/346/263/225-gaes.md

@@ -0,0 +1,19 @@
+AES算法。
+
+**使用方式**：
+
+```go
+import "github.com/gogf/gf/v2/crypto/gaes"
+```
+
+**接口文档**：
+
+[https://pkg.go.dev/github.com/gogf/gf/v2/crypto/gaes](https://pkg.go.dev/github.com/gogf/gf/v2/crypto/gaes)
+
+**温馨提示：**
+
+如果待解密数据经过其它编码，则要先解码再解密，如base64.decode
+
+反过来也一样
+
+如果希望加密完的数据编码，则将结果编码即可，如base64.encode