Add config

zeromicro · Apr 10, 2024 · 0451abb · 0451abb
1 parent f1e7929
commit 0451abb
Show file tree

Hide file tree

Showing 7 changed files with 936 additions and 2 deletions.
diff --git a/docs/tutorials/cli/config.md b/docs/tutorials/cli/config.md
@@ -0,0 +1,321 @@
+---
+title: goctl config
+slug: /docs/tutorials/cli/config
+---
+
+## 概述
+
+goctl config 是 用于对 goctl 静态配置文件做管理。
+goctl config 的目录是根据工程项目来寻找的，以 goctl 可执行文件当前所在工作目录，寻找当前工作目录处在的 go module 或者 go
+path空间，然后在该空间下对 `goctl.yaml` 进行管理。
+如果当前工作目录下没有 go module 则会自动根据工作目录名称创建 go.mod 文件。
+
+## goctl config 指令
+
+```bash
+$ goctl config --help
+Usage:
+  goctl config [command]
+
+Available Commands:
+  clean       Clean goctl config file
+  init        Initialize goctl config file
+
+Flags:
+  -h, --help   help for config
+
+
+Use "goctl config [command] --help" for more information about a command.
+```
+
+### init
+
+初始化 goctl 静态配置文件。
+
+```bash
+$ goctl config init --help
+Initialize goctl config file
+
+Usage:
+  goctl config init [flags]
+
+Flags:
+  -h, --help   help for init
+```
+
+### clean
+
+删除 goctl 配置文件。
+
+```bash
+$ goctl config clean --help
+Clean goctl config file
+
+Usage:
+  goctl config clean [flags]
+
+Flags:
+  -h, --help   help for clean
+```
+
+## 配置说明
+
+goctl config 目前暂时仅支持对 model 数据类型映射的配置，其他配置将根据需要加入。
+
+goctl config 初始化后会在项目工程中创建一个 goctl.yaml 文件，其内容如下：
+
+```yaml
+model:
+  types_map:
+    bigint:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    dec:
+      null_type: sql.NullFloat64
+      type: float64
+    decimal:
+      null_type: sql.NullFloat64
+      type: float64
+    double:
+      null_type: sql.NullFloat64
+      type: float64
+    float:
+      null_type: sql.NullFloat64
+      type: float64
+    float4:
+      null_type: sql.NullFloat64
+      type: float64
+    float8:
+      null_type: sql.NullFloat64
+      type: float64
+    int:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    int1:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    int2:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    int3:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    int4:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    int8:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    integer:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    mediumint:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    middleint:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    smallint:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    tinyint:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    date:
+      null_type: sql.NullTime
+      type: time.Time
+    datetime:
+      null_type: sql.NullTime
+      type: time.Time
+    timestamp:
+      null_type: sql.NullTime
+      type: time.Time
+    time:
+      null_type: sql.NullString
+      type: string
+    year:
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    bit:
+      null_type: sql.NullByte
+      type: byte
+      unsigned_type: byte
+    bool:
+      null_type: sql.NullBool
+      type: bool
+    boolean:
+      null_type: sql.NullBool
+      type: bool
+    char:
+      null_type: sql.NullString
+      type: string
+    varchar:
+      null_type: sql.NullString
+      type: string
+    nvarchar:
+      null_type: sql.NullString
+      type: string
+    nchar:
+      null_type: sql.NullString
+      type: string
+    character:
+      null_type: sql.NullString
+      type: string
+    longvarchar:
+      null_type: sql.NullString
+      type: string
+    linestring:
+      null_type: sql.NullString
+      type: string
+    multilinestring:
+      null_type: sql.NullString
+      type: string
+    binary:
+      null_type: sql.NullString
+      type: string
+    varbinary:
+      null_type: sql.NullString
+      type: string
+    tinytext:
+      null_type: sql.NullString
+      type: string
+    text:
+      null_type: sql.NullString
+      type: string
+    mediumtext:
+      null_type: sql.NullString
+      type: string
+    longtext:
+      null_type: sql.NullString
+      type: string
+    enum:
+      null_type: sql.NullString
+      type: string
+    set:
+      null_type: sql.NullString
+      type: string
+    json:
+      null_type: sql.NullString
+      type: string
+    blob:
+      null_type: sql.NullString
+      type: string
+    longblob:
+      null_type: sql.NullString
+      type: string
+    mediumblob:
+      null_type: sql.NullString
+      type: string
+    tinyblob:
+      null_type: sql.NullString
+      type: string
+```
+
+| <img width={100}/> 字段名称 | <img width={200}/> 说明                                         |
+|-------------------------|---------------------------------------------------------------|
+| model                   | model 配置                                                      |
+| model.types_map         | model 配置之类型映射规则，是一个 map<string,obj> 结构，key 为数据库类型，value 为映射对象 |
+
+model 的 golang 结构体
+
+```go
+// Model defines the configuration for the model code generation.
+Model struct {
+    // 类型映射
+    TypesMap map[string]ModelTypeMapOption `yaml:"types_map,omitempty" `
+}
+
+// ModelTypeMapOption custom Type Options.
+ModelTypeMapOption struct {
+    // 数据库类型名称，不需要附加约束（如：长度等）如 bigint,varchar
+    Type string `yaml:"type"`
+
+    // 当数据类型为 unsigned 修饰时需要映射的 golang 映射类型
+    UnsignedType string `yaml:"unsigned_type,omitempty"`
+
+    // 当数据类型允许为 null且没有默认值时需要映射的 golang 映射类型，此优先级高于 unsigned 约束
+    NullType string `yaml:"null_type,omitempty"`
+
+    // 当被映射的 golang 类型为外部包时，需要指定包名。
+    Pkg string `yaml:"pkg,omitempty"`
+}
+```
+
+数据库类型映射示例：将 decimal 映射为三方的 decimal.Decimal 包，其在 yaml 的表现为灰色底纹部分：
+
+```yaml {10-13}
+model:
+  types_map:
+    bigint: # 当数据字段类型为 bigint 时，
+      # 1. 如果允许 null 且没有默认值时 golang 类型映射为 sql.NullInt64
+      # 2. 如果不允许 null 或者有默认值，则 golang 类型映射为 int64
+      # 3. 如果不允许 null 或者有默认值，且为 unsigned 修饰，则 golang 类型映射为 uint64
+      null_type: sql.NullInt64
+      type: int64
+      unsigned_type: uint64
+    dec:
+      null_type: sql.NullFloat64
+      type: float64
+    decimal:
+      null_type: decimal.NullDecimal
+      pkg: github.com/shopspring/decimal
+      type: decimal.Decimal
+    ...
+```
+
+## 使用示例
+
+### 在不存在 go module 的目录下初始化配置
+
+```bash
+$ ll
+total 0
+$ goctl config init
+goctl.yaml generated in ~/demo/goctl-config/goctl.yaml
+$ ls
+go.mod     goctl.yaml
+$ cat go.mod
+module goctl-config
+
+go 1.20
+```
+
+### 在存在 go module 的目录下初始化配置
+
+```bash
+$ ll
+total 8
+-rw-r--r--  1 ***  staff    29B Apr 10 16:35 go.mod
+$ goctl config init
+goctl.yaml generated in ~/demo/goctl-config/goctl.yaml
+$ ll
+total 16
+-rw-r--r--  1 ***  staff    29B Apr 10 16:35 go.mod
+-rw-r--r--  1 ***  staff   3.3K Apr 10 16:37 goctl.yaml
+```
+
+### 清除配置
+
+```bash
+$ ll
+total 16
+-rw-r--r--  1 ***  staff    29B Apr 10 16:35 go.mod
+-rw-r--r--  1 ***  staff   3.3K Apr 10 16:37 goctl.yaml
+$ goctl config clean
+$ ll
+total 8
+-rw-r--r--  1 ***  staff    29B Apr 10 16:35 go.mod
+```
diff --git a/docs/tutorials/cli/env.md b/docs/tutorials/cli/env.md
@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
 
 goctl env 可以快速检测 goctl 的依赖环境，如果你的环境中缺少了 goctl 的依赖环境，goctl env 会给出相应的提示，当然，你可以可以通过 goctl env install 命令来安装缺失的依赖环境。
 
-## goctl env 指令
+## goctl env 帮助指令
 
 ```bash
 $ goctl env --help
@@ -34,6 +34,38 @@ Flags:
 Use "goctl env [command] --help" for more information about a command.
 ```
 
+### goctl env 指令
+
+goctl env 可以快速查看当前关于 goctl 环境的一些变量，在用户反馈 bug 时可以将这些信息一并提供给维护人员。
+
+```bash
+$ goctl env
+GOCTL_OS=darwin 
+GOCTL_ARCH=arm64
+GOCTL_HOME=/Users/sh00414ml/.goctl
+GOCTL_DEBUG=False
+GOCTL_CACHE=/Users/sh00414ml/.goctl/cache
+GOCTL_EXPERIMENTAL=off
+GOCTL_VERSION=1.6.4
+PROTOC_VERSION=3.19.4
+PROTOC_GEN_GO_VERSION=v1.28.0
+PROTO_GEN_GO_GRPC_VERSION=1.2.0
+```
+
+| <img width={100}/> 字段 | <img width={200}/> 默认值 | <img width={800}/> 参数说明 |
+| -- | --- | --- | 
+| GOCTL_OS | 空字符串 | 操作系统 |
+| GOCTL_ARCH | 空字符串 | 系统架构 |
+| GOCTL_HOME | 空字符串 | goctl 配置目录 |
+| GOCTL_DEBUG | 空字符串 | 是否开启 debug 模式，维护者使用，枚举值 Ture、False |
+| GOCTL_CACHE | 空字符串 | 缓存目录 |
+| GOCTL_EXPERIMENTAL | off | 是否开启试验性功能，枚举值 on：开启，off: 关闭 |
+| GOCTL_VERSION | 空字符串 | goctl 版本 |
+| PROTOC_VERSION | 空字符串 | protoc 版本 |
+| PROTOC_GEN_GO_VERSION | 空字符串 | protoc_gen_go 插件版本，没有安装则无 |
+| PROTO_GEN_GO_GRPC_VERSION | 空字符串 | protoc_gen_go_grpc 插件版本，没有安装则无 |
+
+
 ### goctl env check 指令
 
 goctl env check 指令用于快速检测 goctl 的依赖环境是否准备好，如果你的环境中缺少了 goctl 的依赖环境，goctl env check 会给出相应的提示。