@colin4k1024/tsp 2.4.0

package/skills/goframe-v2/references//345/270/270/350/247/201/351/227/256/351/242/230-FAQ.md

@@ -0,0 +1,215 @@
+寄语：
+
+- 请使用页面右上角的搜索功能，全文快速检索常见问题。
+- 欢迎大家积极参与编辑，把自己遇到的坑怎么填的记录起来。 **众人拾柴火焰高**
+
+## 一、Golang基础
+
+### 1、程序产生异常，但是程序直接崩溃未被框架自动捕获
+
+使用 `GoFrame` 框架是严谨和安全的，如果程序产生了异常，会默认被框架捕获。如果未被自动捕获，那么可能是由于程序逻辑自行开了新的 `goroutine`，在新的 `goroutine` 中产生了异常。因此这里有两个方案可供大家选择：
+
+- 不建议在请求中再开 `goroutine` 来处理请求，这样或使得 `goroutine` 快速膨胀，当 `goroutine` 多了之后也会在 `Go` 引擎层面影响程序的整体调度。
+- 如果实在有必要新开 `goroutine` 的场景下，可以考虑使用 `grpool.AddWithRecover` 来创建新的 `goroutine`，见名知意，它会自动捕获异常。更详细的介绍请参考： [协程管理-grpool](组件列表/系统相关/协程管理-grpool.md)
+
+### 2、 `json` 输出时屏蔽掉一些字段
+
+可以通过结构体嵌套的方式实现，通过使用 `*struct{}` 类型不占用空间以及 `omitempty` 字段为空不输出字段的特性
+
+```go
+type User struct {
+    Pwd string `json:"pwd"`
+    Age int    `json:"age"`
+}
+
+type UserOut struct {
+    User
+    Pwd *struct{} `json:"pwd,omitempty"`// 这里的字段json名需要和嵌套的字段json名一致，否则无效
+}
+
+func TestJson(t *testing.T) {
+    u := User{Pwd: "123", Age: 1}
+    bb := UserOut{User: u}
+    b, _ := json.MarshalIndent(bb, "", "    ")
+    t.Log(string(b))
+}
+```
+
+## 二、兼容性相关
+
+### 1、 `client_tracing.go:73:3: undefined: attribute.Any`
+
+以下错误：
+
+```bash
+D:\Program Files\Go\bin\pkg\mod\github.com\gogf\gf@v1.16.6\net\ghttp\internal\client\client_tracing.go:73:3: undefined: attribute.Any
+D:\Program Files\Go\bin\pkg\mod\github.com\gogf\gf@v1.16.6\net\ghttp\internal\client\client_tracing_tracer.go:150:3: undefined: attribute.Any
+D:\Program Files\Go\bin\pkg\mod\github.com\gogf\gf@v1.16.6\net\ghttp\internal\client\client_tracing_tracer.go:151:3: undefined: attribute.Any
+```
+
+导致该错误的原因在于目前您正在使用的 `goframe` 依赖的 `otel` 包版本过低（ `otel` 包是 `OpenTelemetry` 使用 `Golang` 实现的第三方包，比较常用，很多第三方基础组件都会依赖），而项目中其他的第三方依赖的 `otel` 包过高，按照 `Golang module` 的管理策略，项目将会使用最新的 `otel` 包，于是导致了版本不兼容。
+
+根因还是在于 `otel` 的包在迭代中出现了不兼容升级导致，不过目前 `otel` 包已经较稳定，出现不兼容的可能性降低。
+
+解决的办法是只有升级 `goframe` 的版本， `goframe` 最新版本已经更新使用了稳定的 `otel` 包。如果您使用的已经是 `v1` 的最新版本（ `v1.16`），那么请升级为 `v2` 版本解决。
+
+### 2、使用 `gf` 依赖 `v1.16.2` 时 `go mod tidy` 失败
+
+`found (v0.36.0), but does not contain package go.opentelemetry.io/otel/metric/registry`
+
+解决办法，升级 `gf` 依赖到 `v1.16.9` 再 `go mod tidy`
+
+### 3、升级引起兼容性报错 ..\..\net\ghttp\ghttp_server.go:300:9: table.SetHeader undefined (type *tablewriter.Table has no field or method SetHeader)
+
+使用`go get -u`导致间接依赖版本提升，出现如下的报错。
+>..\..\net\ghttp\ghttp_server.go:300:9: table.SetHeader undefined (type *tablewriter.Table has no field or method SetHeader)
+..\..\net\ghttp\ghttp_server.go:301:9: table.SetRowLine undefined (type *tablewriter.Table has no field or method SetRowLine)
+..\..\net\ghttp\ghttp_server.go:302:9: table.SetBorder undefined (type *tablewriter.Table has no field or method SetBorder)
+..\..\net\ghttp\ghttp_server.go:303:9: table.SetCenterSeparator undefined (type *tablewriter.Table has no field or method SetCenterSeparator)
+
+原因：
+
+使用`go get -u`命令升级了，如"github.com/gogf/gf/contrib/drivers/mysql/v2"这样的依赖了"github.com/gogf/gf/v2"主库的组件，会导致间接依赖被同时升级到最新版本。
+
+间接依赖被升级到最新版本后，如果间接依赖不兼容的旧版就会报错。
+
+解决方式：
+```bash
+// linux
+go list -m -f '{{if and .Indirect (not .Main)}}{{.Path}}{{end}}' all | xargs -I {} go mod edit -droprequire={} && go mod tidy
+
+// windows cmd
+(FOR /F "tokens=*" %G IN ('go list -m -f "{{if and .Indirect (not .Main)}}{{.Path}}{{end}}" all') DO @go mod edit -droprequire=%G) & go mod tidy
+
+// 以上方式还不能解决的时候，手动修改 go.mod 的版本号降级，然后执行 go mod tidy
+// 例如
+// 将 go.mod 文件中的 tablewriter 依赖版本从较高版本降级为 v0.0.5：
+// 修改前（go.mod 部分）:
+// github.com/olekukonko/tablewriter v1.0.9 // indirect
+// 修改后（go.mod 部分）:
+// github.com/olekukonko/tablewriter v0.0.5 // indirect
+// 保存 go.mod 后，执行 go mod tidy 以更新依赖。
+```
+
+## 三、数据库相关
+
+请参考章节： [ORM常见问题](核心组件/数据库ORM/ORM常见问题.md)
+
+## 四、使用相关
+
+### 1、不同环境如何，加载不同的配置文件?
+
+不同环境指的是：开发环境/测试环境/预发环境/生产环境等。
+
+- 首先，在一些互联网项目中，特别是分布式或者微服务化的架构下，一般会使用配置管理中心，不同的环境会对应不同的配置管理中心，所以这样的场景不会存在这样的问题。
+- 其次，如果是传统的项目管理方式下，可能会将配置文件放到代码仓库中共同管理，这样的方式是不推荐的。如果您仍然想要这么做，您可以通过系统环境变量或者命令行启动参数，让程序自动选择配置文件或者指定配置目录，参考 [配置管理](核心组件/配置管理/配置管理.md) 章节。例如： `./app --gf.gcfg.file config-prod.toml ` 则通过命令行启动参数的方式将默认读取的配置文件修改为了 `config-prod.toml` 文件。
+
+我们不建议您在程序中通过代码逻辑来区分和读取不同环境的配置文件。
+
+### 2、 `glog with "ERROR: logging before flag.Parse"`
+
+`Golang` 官方有个简单的日志库包名也叫做 `glog`，检查你文件顶部 `import` 的包名，将 `github.com/golang/glog` 修改为框架的日志组件即可，日志组件使用请参考： [日志组件](核心组件/日志组件/日志组件.md)
+
+### 3、 `gcron` 与 `http` 如何同时使用?
+
+```go
+func main() {
+    //定时任务1
+    gcron.AddSingleton("*/5 * * * * *", func() {
+        task.Test()
+        glog.Debug("gcron1")
+    })
+
+    //定时任务2
+    gcron.AddSingleton("*/10 * * * * *", func() {
+        glog.Debug("gcron2")
+    })
+
+    //接收http请求
+    g.Server().Run()
+}
+```
+
+注意, `gcron` 一定要在 `g.Server().Run` 的前面。
+
+### 4、 `GoFrame` 的 `struct tag`(标签) 有哪些？
+
+参数请求、数据校验、 `OpenAPIv3`、命令管理、数据库ORM。
+
+| Tag(简写) | 全称 | 描述 | 相关文档 |
+| --- | --- | --- | --- |
+| `v` | `valid` | 数据校验标签。 | [Struct校验-基本使用](核心组件/数据校验/数据校验-参数类型/数据校验-Struct校验/Struct校验-基本使用.md) |
+| `p` | `param` | 自定义请求参数匹配。 | [请求输入-对象处理](WEB服务开发/请求输入/请求输入-对象处理.md) |
+| `d` | `default` | 请求参数默认值绑定。 | [请求输入-默认值绑定](WEB服务开发/请求输入/请求输入-默认值绑定.md) |
+| `orm` | `orm` | ORM标签，用于指定表名、关联关系。 | [数据规范-gen dao](开发工具/代码生成-gen/数据规范-gen%20dao.md)<br />[模型关联-静态关联-With特性](核心组件/数据库ORM/ORM链式操作/ORM链式操作-模型关联/模型关联-静态关联-With特性.md) |
+| `dc` | `description` | 通用结构体属性描述，ORM和接口都用到。属于框架默认的属性描述标签。 |  |
+
+其他：
+
+- 命令行结构化管理参数： [命令管理-结构化参数](核心组件/命令管理/命令管理-结构化参数.md)
+- 框架常用标签标签集中管理到了 `gtag` 组件下： [https://github.com/gogf/gf/blob/master/util/gtag/gtag.go](https://github.com/gogf/gf/blob/master/util/gtag/gtag.go)
+- 在接口文档章节，由于采用了标签形式生成 `OpenAPI` 文档，因此标签比较多，具体请参考章节： [接口文档](WEB服务开发/接口文档/接口文档.md)
+
+### 5、 `HTTP Server` 出现 `context cancel` 报错
+
+从框架 `v2.5` 版本开始，框架的 `HTTP Server` 的 `Request` 对象将会直接继承与标准库的 `http.Request` 对象，
+其中就包括其中的 `context` 上下文对象。当客户端例如浏览器、 `HTTP Client` 取消请求时，
+服务端会接收到 `context cancel` 操作( `context.Done`)，但是服务端并不会直接报出 `context cancel` 的错误。
+这种错误往往在业务逻辑调用了底层的数据库、消息组件等组件时，由这些组件识别到 `context cancel` 操作，
+将会停止执行并往上抛出 `context cancel` 错误提醒上层已经终止执行。
+
+这是符合标准库设计的行为，客户端终止请求后，服务端也没有继续执行下去的必要。
+
+[服务端频繁出现contextcancel错误](../docs/WEB服务开发/常见问题.md)
+
+## 五、环境相关
+
+### 1、 `Linux` 下执行 `go build main.go` 提示连接超时 `connection timed out`
+
+```bash
+go: github.com/gogf/gf@v1.14.6-0.20201214132204-c685876e6f67: Get "https://proxy.golang.org/github.com/gogf/gf/@v/v1.14.6-0.20201214132204-c685876e6f67.mod":
+dial tcp 172.217.160.113:443:
+connect: connection timed out
+```
+
+解决办法：
+
+```bash
+export GO111MODULE=on
+export GOPROXY=https://goproxy.cn
+```
+
+具体请看：
+
+- [Go Module](其他资料/准备开发环境/Go%20Module.md)
+- [https://goproxy.cn](https://goproxy.cn)
+
+### 2、 `Linux` 下安装 `gf` 提示命令不存在 `command not found`
+
+```bash
+./gf install
+安装后
+执行gf -v
+提示gf: command not found
+且/usr/bin目录下并没有gf文件
+
+解决方法:
+拷贝sh文件到 /usr/bin目录
+cp gf /usr/bin
+
+然后执行
+gf -v
+
+就会看到
+GoFrame CLI Tool v1.15.4, https://goframe.org
+Install Path: /bin/gf
+Build Detail:
+Go Version: go1.16.2
+GF Version: v1.15.3
+Git Commit: 22011e76dc3e14006936164cc89e2d4c9190a36d
+Build Time: 2021-03-30 15:43:22
+```
+
+### 3、 `Win10` 提示 `gf` 命令不存在
+
+解决办法：安装 `gf.exe` 参考： [开发工具](开发工具/开发工具.md)

package/skills/goframe-v2/references//345/274/200/345/217/221/345/267/245/345/205/267//344/272/244/345/217/211/347/274/226/350/257/221-build.md

@@ -0,0 +1,89 @@
+## 使用方式
+
+`gf build` 命令用于 Go 项目的交叉编译，是 `go build` 的强大封装。
+
+使用 `gf build -h` 查看完整帮助信息。支持为多种操作系统和架构编译可执行文件。
+
+## 内置编译变量
+
+`gf build` 命令在编译时会自动嵌入一组内置变量到二进制文件中，开发者也可以自定义这些变量。运行时可通过 `gbuild` 组件读取这些变量。
+
+默认嵌入的变量包括（可通过 `gf -v` 查看）：
+
+- 当前 `Go` 版本
+- 当前 `GoFrame` 版本
+- 当前 `Git Commit`（如果存在）
+- 当前编译时间
+
+这些信息有助于版本管理和问题追溯。
+
+## 编译配置文件
+
+`gf build` 支持从命令行参数和配置文件两种方式指定编译选项。GoFrame 的配置管理采用统一的配置组件，默认配置文件及使用方法请参考 [配置管理](../核心组件/配置管理/配置管理.md)。
+
+以下是一个配置文件示例：
+
+```yaml
+gfcli:
+  build:
+    name:     "gf"
+    arch:     "all"
+    system:   "all"
+    mod:      "none"
+    packSrc:  "resource,manifest"
+    version:  "v1.0.0"
+    output:   "./bin"
+    extra:    ""
+```
+
+配置选项与命令行同名参数含义一致。各配置项说明如下：
+
+| 名称 | 默认值 | 含义 | 示例 |
+| --- | --- | --- | --- |
+| `name` | 与程序入口 `go` 文件同名 | 生成的可执行文件名称。如果是 `windows` 平台，那么默认会加上 `.exe` 后缀 | `gf` |
+| `arch` | 当前系统架构 | 编译架构，多个以 `,` 号分隔，如果是 `all` 表示编译所有支持架构 | `386,amd64,arm` [更多](https://golang.google.cn/doc/install/source#environment) |
+| `system` | `当前系统平台` | 编译平台，多个以 `,` 号分隔，如果是 `all` 表示编译所有支持平台 | `linux,darwin,windows` [更多](https://golang.google.cn/doc/install/source#environment) |
+| `path` | `./bin` | 编译可执行文件存储的 **目录地址** | `./bin` |
+| `mod` |  | 同 `go build -mod` 编译选项，不常用 | `none` |
+| `cgo` | `false` | 是否开启 `CGO`，默认是关闭的。如果开启，那么交叉编译可能会有问题。 |  |
+| `packSrc` |  | 需要打包的目录，多个以 `,` 号分隔，生成到 `internal/packed/build_pack_data.go` | `public,template,manifest` |
+| `packDst` | `internal/packed/build_pack_data.go` | 打包后生成的 `Go` 文件路径，一般使用相对路径指定到本项目目录中 |  |
+| `version` |  | 程序版本，如果指定版本信息，那么程序生成的路径中会多一层以版本名称的目录 | `v1.0.0` |
+| `output` |  | 输出的可执行文件路径，当该参数指定时， `name` 和 `path` 参数失效，常用于编译单个可执行文件。 | `./bin/gf.exe` |
+| `extra` |  | 额外自定义的编译参数，会直接传递给 `go build` 命令 |  |
+| `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) 获取。
+:::
+
+## 使用示例
+
+```text
+$ gf build
+2020-12-31 00:35:25.562 start building...
+2020-12-31 00:35:25.562 go build -o ./bin/darwin_amd64/gf main.go
+2020-12-31 00:35:28.381 go build -o ./bin/freebsd_386/gf main.go
+2020-12-31 00:35:30.650 go build -o ./bin/freebsd_amd64/gf main.go
+2020-12-31 00:35:32.957 go build -o ./bin/freebsd_arm/gf main.go
+2020-12-31 00:35:35.824 go build -o ./bin/linux_386/gf main.go
+2020-12-31 00:35:38.082 go build -o ./bin/linux_amd64/gf main.go
+2020-12-31 00:35:41.076 go build -o ./bin/linux_arm/gf main.go
+2020-12-31 00:35:44.369 go build -o ./bin/linux_arm64/gf main.go
+2020-12-31 00:35:47.352 go build -o ./bin/linux_ppc64/gf main.go
+2020-12-31 00:35:50.293 go build -o ./bin/linux_ppc64le/gf main.go
+2020-12-31 00:35:53.166 go build -o ./bin/linux_mips/gf main.go
+2020-12-31 00:35:55.840 go build -o ./bin/linux_mipsle/gf main.go
+2020-12-31 00:35:58.423 go build -o ./bin/linux_mips64/gf main.go
+2020-12-31 00:36:01.062 go build -o ./bin/linux_mips64le/gf main.go
+2020-12-31 00:36:03.502 go build -o ./bin/netbsd_386/gf main.go
+2020-12-31 00:36:06.280 go build -o ./bin/netbsd_amd64/gf main.go
+2020-12-31 00:36:09.332 go build -o ./bin/netbsd_arm/gf main.go
+2020-12-31 00:36:11.811 go build -o ./bin/openbsd_386/gf main.go
+2020-12-31 00:36:14.140 go build -o ./bin/openbsd_amd64/gf main.go
+2020-12-31 00:36:17.859 go build -o ./bin/openbsd_arm/gf main.go
+2020-12-31 00:36:20.327 go build -o ./bin/windows_386/gf.exe main.go
+2020-12-31 00:36:22.994 go build -o ./bin/windows_amd64/gf.exe main.go
+2020-12-31 00:36:25.795 done!
+```

package/skills/goframe-v2/references//345/274/200/345/217/221/345/267/245/345/205/267//344/273/243/347/240/201/347/224/237/346/210/220-gen//344/273/243/347/240/201/347/224/237/346/210/220-gen.md

@@ -0,0 +1,31 @@
+:::info
+从 `v2` 版本开始，最新的 `CLI` 工具版本功能会随着 `GoFrame` 框架的最新版本编译，引入如果本地的 `CLI` 工具自动化生成的代码与项目的 `GoFrame` 框架版本出现兼容性问题时，建议升级项目框架版本，或者自定义安装旧版本的 `CLI` 工具。旧版本CLI工具安装方式参考仓库首页介绍： [https://github.com/gogf/gf-cli](https://github.com/gogf/gf-cli)
+:::
+## 重要说明🔥
+
+- `CLI` 工具提供的代码生成功能，目的是 **规范化项目代码编写**、 **简化项目开发复杂度**， **让开发者能够把精力聚焦于业务逻辑本身**。
+- `CLI` 工具本身会需要有一定前置的学习和理解成本（尽量理解为什么），但在熟练之后，大家的开发工作将会事半功倍。
+- `CLI` 工具的代码生成功能针对于企业级项目、多成员的团队性项目中收益会非常高。但针对于单人小型项目，开发者可根据个人意愿评估是否选择使用。 `GoFrame` 框架本身只是提供了基础组件，采用了组件化的灵活设计，不会对项目代码做严格的要求；但 `CLI` 工具会有一定的条框限制，目的是使得团队中每个成员的步调和风格一致，不会使得开发者的代码编写过于随意。
+
+## 使用方式
+
+```text
+$ gf gen -h
+USAGE
+    gf gen COMMAND [OPTION]
+
+COMMAND
+    ctrl        parse api definitions to generate controller/sdk go files
+    dao         automatically generate go files for dao/do/entity
+    enums       parse go files in current project and generate enums go file
+    pb          parse proto files and generate protobuf go files
+    pbentity    generate entity message files in protobuf3 format
+    service     parse struct and associated functions from packages to generate service go file
+
+DESCRIPTION
+    The "gen" command is designed for multiple generating purposes.
+    It's currently supporting generating go files for ORM models, protobuf and protobuf entity files.
+    Please use "gf gen dao -h" for specified type help.
+```
+
+## 相关文档

package/skills/goframe-v2/references//345/274/200/345/217/221/345/267/245/345/205/267//344/273/243/347/240/201/347/224/237/346/210/220-gen//345/215/217/350/256/256/347/274/226/350/257/221-gen pb.md"

@@ -0,0 +1,39 @@
+:::tip
+该功能特性从 `v2.4` 版本开始提供。
+:::
+## 基本介绍
+
+该命令用于编译 `proto` 文件，生成对应的 `protobuf go` 文件以及对应的控制器文件。
+
+## 命令使用
+
+```text
+$ gf gen pb -h
+USAGE
+    gf gen pb [OPTION]
+
+OPTION
+    -p, --path   protobuf file folder path
+    -a, --api    output folder path storing generated go files of api
+    -c, --ctrl   output folder path storing generated go files of controller
+    -h, --help   more information about this command
+
+EXAMPLE
+    gf gen pb
+    gf gen pb -p . -a . -p .
+```
+:::tip
+如果使用框架推荐的项目工程脚手架，并且系统安装了 `make` 工具，也可以使用 `make pb` 快捷指令。
+:::
+参数说明：
+
+| 名称 | 必须 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `path` | 否 | `manifest/protobuf` | 指向 `proto` 协议定义文件 |
+| `api` | 否 | `api` | 指向生成的接口文件存放目录 |
+| `ctrl` | 否 | `internal/controller` | 指向生成的控制器文件存放目录 |
+
+## 注意事项
+
+- 在生成控制器文件时，会自动识别是否已经存在对应的接口实现方法，如果已经存在则不再重复生成对应的接口方法，防止覆盖。
+- 如果在 `proto` 目录执行该命令，并且指定的 `path` 目录不存在时，那么将会自动编译本地 `proto` 文件，且编译后的文件生成到当前目录，并自动关闭控制器文件的生成功能。

package/skills/goframe-v2/references//345/274/200/345/217/221/345/267/245/345/205/267//344/273/243/347/240/201/347/224/237/346/210/220-gen//346/216/245/345/217/243/350/247/204/350/214/203-gen ctrl.md"

@@ -0,0 +1,134 @@
+:::tip
+该功能特性从 `v2.5` 版本开始提供。该命令目前仅支持 `HTTP` 接口开发， `GRPC` 部分请参考 `gen pb` 命令。未来会考虑 `HTTP` 及 `GRPC` 统一使用该命令生成控制器及 `SDK` 源代码。
+:::
+## 基本介绍
+
+### 解决痛点
+
+在开发项目时，通常需要先根据业务需求设计 API 接口，使用 `proto` 或 `golang struct` 定义 API 的输入输出，然后创建对应的控制器实现，最后可能还需要提供 SDK（同为 Golang 语言条件下）供内外部服务调用。开发过程中会遇到以下痛点：
+
+- **重复性的代码工作繁琐**。在 `api` 中创建输入输出定义文件后，还需要在控制器目录下创建对应的文件、编写控制器初始化代码、从 `api` 代码中反复拷贝输入输出结构名称，过程繁琐。
+- **API与控制器之间的关联缺乏可靠规范约束**。除了 `API` 有一定的命名约束外，控制器的创建和方法命名灵活度较高，`API` 的结构名称与控制器方法名称难以约束对应，当接口越来越多时维护成本增加。
+- **团队开发多人协作时代码文件冲突概率大**。多人同时修改同一个文件时，文件冲突概率增大，处理这种冲突的精力开销毫无意义。
+- **缺少API的HTTP SDK自动生成工具**。开发完 `API` 后，往往需要立即给内部或外部调用，缺少便捷的 `SDK` 生成工具，手动维护 `SDK` 代码的成本很高。
+
+### 命令特性
+
+- 规范了 `API` 定义与控制器文件命名、控制器方法命名。
+- 规范了 `API` 定义与控制器代码之间的关联关系，便于快速定位 `API` 实现。
+- 根据 `API` 定义自动生成控制器接口、初始化文件及代码、接口初始化代码。
+- 根据 `API` 定义自动生成易用的 `HTTP SDK` 代码。该功能可配置，默认关闭。
+- 支持 `File Watch` 自动化生成模式：当 `API` 结构定义文件发生变化时，自动增量更新对应的控制器、`SDK` 代码。
+
+## 前置约定
+
+### 重要规范🔥
+
+该命令的目的之一是规范化 `api` 代码编写，以下是必须遵守的重要规范（否则无法生成代码）：
+
+- `api` 层的接口定义文件路径需要满足 `/api/模块/版本/定义文件.go`，例如：`/api/user/v1/user.go`、`/api/user/v1/user_delete.go`等。
+  - **模块**：指 `API` 的模块划分，可以按照不同的 **业务属性** 拆分，方便聚合维护。也可以将模块理解为具体的业务资源。
+  - **版本**：通常使用 `v1`/`v2` 等形式定义，用于 `API` 兼容性的版本控制。当相同的 `API` 出现兼容性更新时，需要通过不同版本号区分。默认使用 `v1` 管理第一个版本。
+  - **定义文件**：指 `API` 的输入输出定义文件，通常每个 `API` 需要单独定义一个 `go` 文件来独立维护。也支持将多个 `API` 放到一个 `go` 文件中统一维护。
+- `api` 定义的结构体名称需要满足 `操作+Req` 及 `操作+Res` 的命名方式。例如：`GetOneReq/GetOneRes`、`GetListReq/GetListRes`、`DeleteReq/DeleteRes` 等。
+  - **操作**：当前 `API` 模块的操作名称，通常对应 `CRUD` 是：`Create`、`Read`、`Update`、`Delete`。
+
+以下是项目工程模板中的 `Hello` 接口示例：
+
+### 建议性的命名
+
+我们对一些常用的接口定义做了一些建议性的命名，供大家参考：
+
+| 操作名称 | 建议命名 | 备注 |
+| --- | --- | --- |
+| **查询列表** | `GetListReq/Res` | 通常是从数据库中分页查询数据记录 |
+| **查询详情** | `GetOneReq/Res` | 通常接口需要传递主键条件，从数据库中查询记录详情 |
+| **创建资源** | `CreateReq/Res` | 通常是往数据表中插入一条或多条数据记录 |
+| **修改资源** | `UpdateReq/Res` | 通常是按照一定条件修改数据表中的一条或多条数据记录 |
+| **删除资源** | `DeleteReq/Res` | 通常是按照一定条件删除数据表中的一条或多条数据记录 |
+
+## 命令使用
+
+该命令通过分析给定的 `api` 接口定义目录下的代码，自动生成对应的控制器/ `SDK Go` 代码文件。
+
+### 手动模式
+
+如果是手动执行命令行，直接在项目根目录下执行 `gf gen ctrl` 即可，她将完整扫描 `api` 接口定义目录，并生成对应代码。
+
+```text
+$ gf gen ctrl -h
+USAGE
+    gf gen ctrl [OPTION]
+
+OPTION
+    -s, --srcFolder       source folder path to be parsed. default: api
+    -d, --dstFolder       destination folder path storing automatically generated go files. default: internal/controller
+    -w, --watchFile       used in file watcher, it re-generates go files only if given file is under srcFolder
+    -k, --sdkPath         also generate SDK go files for api definitions to specified directory
+    -v, --sdkStdVersion   use standard version prefix for generated sdk request path
+    -n, --sdkNoV1         do not add version suffix for interface module name if version is v1
+    -c, --clear           auto delete generated and unimplemented controller go files if api definitions are missing
+    -m, --merge           generate all controller files into one go file by name of api definition source go file
+    -h, --help            more information about this command
+
+EXAMPLE
+    gf gen ctrl
+
+```
+:::tip
+如果使用框架推荐的项目工程脚手架，并且系统安装了 `make` 工具，也可以使用 `make ctrl` 快捷指令。
+:::
+参数说明：
+
+| 名称 | 必须 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `srcFolder` | 否 | `api` | 指向 `api` 接口定义文件目录地址 |
+| `dstFolder` | 否 | `internal/controller` | 指向生成的控制器文件存放目录 |
+| `watchFile` | 否 |  | 用在IDE的文件监控中，用于根据当文件发生变化时自动执行生成操作 |
+| `sdkPath` | 否 |  | 如果需要生成 `HTTP SDK`，该参数用于指定生成的SDK代码目录存放路径 |
+| `sdkStdVersion` | 否 | `false` | 生成的 `HTTP SDK` 是否使用标准的版本管理。标准的版本管理将自动根据 `API` 版本增加请求的路由前缀。例如 `v1` 版本的API将会自动增加 `/api/v1` 的请求路由前缀。 |
+| `sdkNoV1` | 否 | `false` | 生成的 `HTTP SDK` 中，当接口为 `v1` 版本时，接口模块名称是否不带 `V1` 后缀。 |
+| `clear` | 否 | `false` | 是否删除 `controller` 中与 `api` 层定义不存在的控制器接口文件。 |
+| `merge` | 否 | `false` | **用以控制生成的 `ctrl` 控制器代码文件按照 `api` 层的文件生成，而不是默认按照 `api` 接口拆分为不同的接口实现文件。** |
+
+### 自动模式（推荐）
+
+如果您是使用的 `GolandIDE`，那么可以使用我们提供的配置文件：[watchers.xml](gen-ctrl-watchers.xml)  自动监听代码文件修改时自动生成接口文件。使用方式，如下图：
+
+## 使用示例
+
+### 自动生成的接口定义文件
+
+### 自动生成的控制器代码文件
+
+### 自动生成的 `HTTP SDK` 代码文件
+
+## 常见问题
+
+### 为什么每一个 `api` 接口生成一个 `controller` 文件而不是合并到一个 `controller` 文件中
+
+当然，针对小型项目或者个人简单项目、一个 `api` 模块只有几个接口的项目而言，管理的方式并不会成为什么问题，可以根据个人喜好维护代码文件即可。我们这里以较复杂的业务项目，或者企业级项目，在一个 `api` 模块的接口比较多的场景来展开描述一下。
+
+- 首先，开发 `api` 接口时，查找 `api` 接口实现更加清晰，而不是在一个动则上千行的代码文件中查找。
+- 其次，在多人协作的项目中，如果多人同时修改同一个 `controller` 文件在版本管理中容易出现文件冲突。一个 `api` 接口对应一个 `controller` 实现文件的维护方式能最大减少代码协作时的文件冲突概率，大部分开发者也不希望花费自己宝贵的时间一次又一次地解决文件冲突上。
+- 最后， `controller` 层的代码有它自身的职责：
+  - 校验输入参数：客户端提交的参数都是不可信任的，大部分场景下都需要做数据校验。
+  - 实现接口逻辑：直接在 `controller` 中实现接口逻辑，或者调用一个或多个 `service` 接口、第三方服务接口来实现接口逻辑。注意事项，不能在 `service` 层的接口中去实现 `api` 接口逻辑，因为 `api` 接口是与具体的业务场景绑定的，无法复用。💀 **大部分常见的错误是 `controller` 直接把请求透传给 `service` 接口来实现 `api` 接口逻辑，造成了 `controller` 看起来可有可无、 `service` 层的实现越来越重且无法复用。** 💀
+  - 生成返回数据：组织内部产生的结果数据，生成接口定义的返回数据接口。
+- 这些职责也就意味着 `controller` 的代码也是比较复杂，分开维护能减少开发者心智负担、易于清晰维护 `api` 接口实现逻辑。
+
+**一些建议**：
+
+如果一个 `api` 模块下的接口文件太多，建议将复杂的 `api` 模块进一步划分为子模块。这样可以对复杂的 `api` 模块进行解耦，也能通过多目录的方式来维护 `api` 接口定义和 `controller` 接口实现文件。目录结构会更清晰，更利于多人协作和版本管理。
+
+_看完以上关于对此的设计后，如果您仍然想使用单源码文件来管理所有接口，可以参考 `merge` 参数。_
+
+### 根据 `api` 模块生成对应的 `controller` 模块中为何存在一个空的 `go` 文件
+
+**例如**：
+
+**说明**：
+
+每个 `api` 模块会生成一个空的该模块 `controller` 下的 `go` 文件，该文件只会生成一次，用户可以在里面填充必要的预定义代码内容，例如，该模块 `controller` 内部使用的变量、常量、数据结构定义，或者包初始化 `init` 方法定义等等。 _我们提倡好的代码管理习惯，模块下的 **预定义内容** 尽量统一维护到该模块下以模块名称命名的 `go` 文件中（ `模块.go`），而不是分散到各个 `go` 文件中，以便于更好地维护代码。_
+
+如果该 `controller` 目前没有需要自定义填充的代码内容，那么保留该文件为空即可，为未来预留扩展能力。

package/skills/goframe-v2/references//345/274/200/345/217/221/345/267/245/345/205/267//344/273/243/347/240/201/347/224/237/346/210/220-gen//346/225/260/346/215/256/350/241/250PB-gen pbentity.md"

@@ -0,0 +1,134 @@
+:::tip
+该功能特性从 `v2.4` 版本开始提供。
+:::
+## 基本介绍
+
+该命令用于读取配置的数据库，根据数据表生成对应的 `proto` 数据结构文件。
+
+## 命令使用
+
+```text
+$ gf gen pbentity -h
+USAGE
+    gf gen pbentity [OPTION]
+
+OPTION
+    -p, --path                 directory path for generated files storing
+    -k, --package              package path for all entity proto files
+    -l, --link                 database configuration, the same as the ORM configuration of GoFrame
+    -t, --tables               generate models only for given tables, multiple table names separated with ','
+    -f, --prefix               add specified prefix for all entity names and entity proto files
+    -r, --removePrefix         remove specified prefix of the table, multiple prefix separated with ','
+    -rf, --removeFieldPrefix   remove specified prefix of the field, multiple prefix separated with ','
+    -n, --nameCase             case for message attribute names, default is "Camel":
+                               | Case            | Example            |
+                               |---------------- |--------------------|
+                               | Camel           | AnyKindOfString    |
+                               | CamelLower      | anyKindOfString    | default
+                               | Snake           | any_kind_of_string |
+                               | SnakeScreaming  | ANY_KIND_OF_STRING |
+                               | SnakeFirstUpper | rgb_code_md5       |
+                               | Kebab           | any-kind-of-string |
+                               | KebabScreaming  | ANY-KIND-OF-STRING |
+    -j, --jsonCase             case for message json tag, cases are the same as "nameCase", default "CamelLower".
+                               set it to "none" to ignore json tag generating.
+    -o, --option               extra protobuf options
+    -h, --help                 more information about this command
+
+EXAMPLE
+    gf gen pbentity
+    gf gen pbentity -l "mysql:root:12345678@tcp(127.0.0.1:3306)/test"
+    gf gen pbentity -p ./protocol/demos/entity -t user,user_detail,user_login
+    gf gen pbentity -r user_ -k github.com/gogf/gf/example/protobuf
+    gf gen pbentity -r user_
+
+CONFIGURATION SUPPORT
+    Options are also supported by configuration file.
+    It's suggested using configuration file instead of command line arguments making producing.
+    The configuration node name is "gf.gen.pbentity", which also supports multiple databases, for example(config.yaml):
+    gfcli:
+      gen:
+      - pbentity:
+            link:    "mysql:root:12345678@tcp(127.0.0.1:3306)/test"
+            path:    "protocol/demos/entity"
+            tables:  "order,products"
+            package: "demos"
+      - pbentity:
+            link:    "mysql:root:12345678@tcp(127.0.0.1:3306)/primary"
+            path:    "protocol/demos/entity"
+            prefix:  "primary_"
+            tables:  "user, userDetail"
+            package: "demos"
+            option:  |
+              option go_package    = "protobuf/demos";
+              option java_package  = "protobuf/demos";
+              option php_namespace = "protobuf/demos";
+            typeMapping:
+              json:
+                type: google.protobuf.Value
+                import: google/protobuf/struct.proto
+              jsonb:
+                type: google.protobuf.Value
+                import: google/protobuf/struct.proto
+```
+:::tip
+如果使用框架推荐的项目工程脚手架，并且系统安装了 `make` 工具，也可以使用 `make pbentity` 快捷指令。
+:::
+参数说明：
+
+| 名称 | 默认值 | 含义 | 示例 |
+| --- | --- | --- | --- |
+| `gfcli.gen.pbentity` |  | 代码生成配置项，可以有多个配置项构成数组，支持多个数据库生成。不同的数据库可以设置不同的生成规则，例如可以生成到不同的位置或者文件。 | - |
+| `path` | `manifest/protobuf/pbentity` | 生成 `proto` 文件的存储 **目录** 地址。 | `protobuf/pbentity` |
+| `package` | 自动识别 `go.mod` | 生成的 `proto` 文件中的 `go_package` 路径，并自动识别 `package` 名称 | - |
+| `link` |  | 分为两部分，第一部分表示你连接的数据库类型 `mysql`, `postgresql` 等, 第二部分就是连接数据库的 `dsn` 信息。具体请参考 [ORM使用配置](../../核心组件/数据库ORM/ORM使用配置/ORM使用配置.md) 章节。 | - |
+| `prefix` |  | 生成数据库对象及文件的前缀，以便区分不同数据库或者不同数据库中的相同表名，防止数据表同名覆盖。 | `order_`<br />`user_` |
+| `removePrefix` |  | 删除数据表的指定前缀名称。多个前缀以 `,` 号分隔。 | `gf_` |
+| `removeFieldPrefix` |  | 删除字段名称的指定前缀名称。多个前缀以 `,` 号分隔。 | `f_` |
+| `tables` |  | 指定当前数据库中需要执行代码生成的数据表。如果为空，表示数据库的所有表都会生成。 | `user, user_detail` |
+| `nameCase` | `CamelLower` | 生成的 `message` 属性字段名称格式。参数可选为： `Camel`、 `CamelLower`、 `Snake`、 `SnakeScreaming`、 `SnakeFirstUpper`、 `Kebab`、 `KebabScreaming`。具体介绍请参考命名行帮助示例。 | `Snake` |
+| `option` |  | 额外的 `proto option` 配置列表 |  |
+| `typeMapping` |  | 用于自定义数据表字段类型到生成的Go文件中对应属性类型映射 |  |
+| `fieldMapping` |  | 用于自定义数据表具体字段到生成的Go文件中对应属性类型映射 |  |
+
+### 参数：`typeMapping`
+
+参数`typeMapping`支持配置数据库字段类型对应的`Go`数据类型，默认值为：
+```yaml
+decimal:
+  type: float64
+money:
+  type: float64
+numeric:
+  type: float64
+smallmoney:
+  type: float64
+```
+该配置支持通过`import`配置项引入第三方包，例如：
+```yaml
+decimal:
+  type:   decimal.Decimal
+  import: github.com/shopspring/decimal
+```
+
+### 参数：`fieldMapping`
+
+参数`fieldMapping`提供细粒度的字段类型映射配置，支持配置指定数据库字段生成的`Go`数据类型。除了配置名称不一样外，配置内容与`typeMapping`一致。配置示例：
+```yaml
+paid_orders.amount:
+  type:   decimal.Decimal
+  import: github.com/shopspring/decimal
+```
+示例中，`paid_orders`为表名称，`amount`为字段名称，`type`表示生成的`Go`代码中对应的数据类型名称，`import`表示生成的代码中需要引入第三方包。
+
+## 与 `gen dao` 中的 `entity` 差别
+
+### 相同之处
+
+- 两者生成的内容都是 `entity` 内容，即从数据集合（数据库表）中生成对应的 `Golang` 实体对象供程序方便使用。并且都是单向生成，即只能从数据集合生成实体对象代码，以保证实体对象数据结构的同步。
+- `gen dao` 生成的 `entity` 数据实体对象是对于 `Golang` 语言来说是通用的，但目前主要为 `HTTP` 协议服务。在 `HTTP` 服务中， `gen dao` 中生成的 `entity` 虽然是在 `internal` 目录下，但最终也会作为 `HTTP API` 返回的一部分服务客户端。
+
+### 不同之处
+
+- 在 `GRPC` 服务中， `gen dao` 生成的 `entity` 数据结构无法提供给 `GRPC` 接口使用，因为 `GRPC` 的数据结构需要使用 `proto` 文件来定义。因此，在 `GRPC` 服务中就需要使用到 `gen pbentity` 中生成的 `pbentity proto` 文件。同时，在 `GRPC` 微服务开发中， `gen dao` 生成的 `entity` 已经没有具体作用。
+- 取名 `pbentity` 而不是 `entity` 的名称，是为了防止和 `gen dao` 中的 `entity` 含义冲突。