GoFrame 數據庫ORM-使用配置

配置文件

我們推薦使用配置組件來管理數據庫配置，并使用?g?對象管理模塊中的?g.DB?("數據庫分組名稱")方法獲取數據庫操作對象，數據庫對象將會自動讀取配置組件中的相應配置項，并自動初始化該數據庫操作的單例對象。數據庫配置管理功能使用的是配置管理組件實現(xiàn)（配置組件采用接口化設計默認使用文件系統(tǒng)實現(xiàn)），同樣支持多種數據格式如：?toml/yaml/json/xml/ini?。默認并且推薦的配置文件數據格式為?yaml?。

簡單配置

一個簡單的數據庫配置如下：

database:
  default:
    type:  "mysql"
    link:  "root:12345678@tcp(127.0.0.1:3306)/test"
  user:
    type:  "mysql"
    link:  "root:12345678@tcp(127.0.0.1:3306)/user"

也可以將?type?數據庫類型寫到?link?配置項中，以上簡化為：

database:
  default:
    link:  "mysql:root:12345678@tcp(127.0.0.1:3306)/test"
  user:
    link:  "mysql:root:12345678@tcp(127.0.0.1:3306)/user"

不同數據類型對應的?link?如下:

完整配置

完整的?config.yaml?數據庫配置項的數據格式形如下：

database:
  分組名稱:
    host:                  "地址"
    port:                  "端口"
    user:                  "賬號"
    pass:                  "密碼"
    name:                  "數據庫名稱"
    type:                  "數據庫類型(mysql/pgsql/mssql/sqlite/oracle)"
    link:                  "(可選)自定義數據庫鏈接信息，當該字段被設置值時，以上鏈接字段(Host,Port,User,Pass,Name)將失效，但是type必須有值"         
    role:                  "(可選)數據庫主從角色(master/slave)，不使用應用層的主從機制請均設置為master"
    debug:                 "(可選)開啟調試模式"
    prefix:                "(可選)表名前綴"
    dryRun:                "(可選)ORM空跑(只讀不寫)"
    charset:               "(可選)數據庫編碼(如: utf8/gbk/gb2312)，一般設置為utf8"
    weight:                "(可選)負載均衡權重，用于負載均衡控制，不使用應用層的負載均衡機制請置空"
    timezone:              "(可選)時區(qū)配置，例如:local"
    maxIdle:               "(可選)連接池最大閑置的連接數"
    maxOpen:               "(可選)連接池最大打開的連接數"
    maxLifetime:           "(可選)連接對象可重復使用的時間長度"
    createdAt:             "(可選)自動創(chuàng)建時間字段名稱"
    updatedAt:             "(可選)自動更新時間字段名稱"
    deletedAt:             "(可選)軟刪除時間字段名稱"
    timeMaintainDisabled:  "(可選)是否完全關閉時間更新特性，true時CreatedAt/UpdatedAt/DeletedAt都將失效"

完整的數據庫配置項示例(?YAML?)：

database:
  default:
    host:          "127.0.0.1"
    port:          "3306"
    user:          "root"
    pass:          "12345678"
    name:          "test"
    type:          "mysql"
    role:          "master"
    debug:         "true"
    dryrun:        0
    weight:        "100"
    prefix:        "gf_"
    charset:       "utf8"
    timezone:      "local"
    maxIdle:       "10"
    maxOpen:       "100"
    maxLifetime:   "30s"

使用該配置方式時，為保證數據庫安全，默認底層不支持多行?SQL?語句執(zhí)行。為了得到更多配置項控制，請參考推薦的簡化配置，同時建議您務必了解清楚簡化配置項中每個連接參數的功能作用。

集群模式

?gdb?的配置支持集群模式，數據庫配置中每一項分組配置均可以是多個節(jié)點，支持負載均衡權重策略，例如：

database:
  default:
  - link: "mysql:root:12345678@tcp(127.0.0.1:3306)/test"
    role: "master"
  - link: "mysql:root:12345678@tcp(127.0.0.1:3306)/test"
    role: "slave"

  user:
  - link: "mysql:root:12345678@tcp(127.0.0.1:3306)/user"
    role: "master"
  - link: "mysql:root:12345678@tcp(127.0.0.1:3306)/user"
    role: "slave"
  - link: "mysql:root:12345678@tcp(127.0.0.1:3306)/user"
    role: "slave"

日志配置

?gdb?支持日志輸出，內部使用的是?glog.Logger?對象實現(xiàn)日志管理，并且可以通過配置文件對日志對象進行配置。默認情況下?gdb?關閉了?DEBUG?日志輸出，如果需要打開?DEBUG?信息需要將數據庫的?debug?參數設置為?true?。以下是為一個配置文件示例：

database:
  logger:
    path:    "/var/log/gf-app/sql"
    level:   "all"
    stdout:  true
  default:
    link:    "mysql:root:12345678@tcp(127.0.0.1:3306)/user_center"
    debug:   true

其中?database.logger?即為?gdb?的日志配置，當該配置不存在時，將會使用日志組件的默認配置。

需要注意：由于?ORM?底層都是采用安全的預處理執(zhí)行方式，提交到底層的?SQL?與參數其實是分開的，因此日志中記錄的完整?SQL?僅作參考方便人工閱讀，并不是真正提交到底層的?SQL?語句。

原生配置(高階，可選)

以下為數據庫底層管理配置介紹，如果您對數據庫的底層配置管理比較感興趣，可繼續(xù)閱讀后續(xù)章節(jié)。

數據結構

?gdb?數據庫管理模塊的內部配置管理數據結構如下：

type Config      map[string]ConfigGroup // 數據庫配置對象
type ConfigGroup []ConfigNode           // 數據庫分組配置
// 數據庫配置項(一個分組配置對應多個配置項)
type ConfigNode  struct {
    Host             string        // 地址
    Port             string        // 端口
    User             string        // 賬號
    Pass             string        // 密碼
    Name             string        // 數據庫名稱
    Type             string        // 數據庫類型：mysql, sqlite, mssql, pgsql, oracle<br />    Link             string        // (可選)自定義鏈接信息，當該字段被設置值時，以上鏈接字段(Host,Port,User,Pass,Name)將失效(該字段是一個擴展功能)     Role             string        // (可選，默認為master)數據庫的角色，用于主從操作分離，至少需要有一個master，參數值：master, slave
    Debug            bool          // (可選)開啟調試模式
    Charset          string        // (可選，默認為 utf8)編碼，默認為 utf8
    Prefix           string        // (可選)表名前綴
    Weight           int           // (可選)用于負載均衡的權重計算，當集群中只有一個節(jié)點時，權重沒有任何意義
    MaxIdleConnCount int           // (可選)連接池最大閑置的連接數
    MaxOpenConnCount int           // (可選)連接池最大打開的連接數
    MaxConnLifetime  time.Duration // (可選，單位秒)連接對象可重復使用的時間長度
}

?ConfigNode?用于存儲一個數據庫節(jié)點信息；?ConfigGroup?用于管理多個數據庫節(jié)點組成的配置分組(一般一個分組對應一個業(yè)務數據庫集群)；?Config?用于管理多個?ConfigGroup?配置分組。

配置管理特點：

1. 支持多節(jié)點數據庫集群管理；
2. 每個節(jié)點可以單獨配置連接屬性；
3. 采用單例模式管理數據庫實例化對象；
4. 支持對數據庫集群分組管理，按照分組名稱獲取實例化的數據庫操作對象；
5. 支持多種關系型數據庫管理，可通過?ConfigNode.Type?屬性進行配置；
6. 支持?Master-Slave?讀寫分離，可通過?ConfigNode.Role?屬性進行配置；
7. 支持客戶端的負載均衡管理，可通過?ConfigNode.Weight?屬性進行配置，值越大，優(yōu)先級越高；

特別說明，?gdb?的配置管理最大的特點是，（同一進程中）所有的數據庫集群信息都使用同一個配置管理模塊進行統(tǒng)一維護，不同業(yè)務的數據庫集群配置使用不同的分組名稱進行配置和獲取。

配置方法

這是原生調用?gdb?模塊來配置管理數據庫。如果開發(fā)者想要自行控制數據庫配置管理可以參考以下方法。若無需要可忽略該章節(jié)。

接口文檔： https://pkg.go.dev/github.com/gogf/gf/v2/database/gdb

// 添加一個數據庫節(jié)點到指定的分組中
func AddConfigNode(group string, node ConfigNode)<br />
// 添加一個配置分組到數據庫配置管理中(同名覆蓋)
func AddConfigGroup(group string, nodes ConfigGroup)

// 添加一個數據庫節(jié)點到默認的分組中(默認為default，可修改)
func AddDefaultConfigNode(node ConfigNode)<br />
// 添加一個配置分組到數據庫配置管理中(默認分組為default，可修改)
func AddDefaultConfigGroup(nodes ConfigGroup)

// 設置默認的分組名稱，獲取默認數據庫對象時將會自動讀取該分組配置
func SetDefaultGroup(groupName string)

// 設置數據庫配置為定義的配置信息，會將原有配置覆蓋
func SetConfig(c Config)

默認分組表示，如果獲取數據庫對象時不指定配置分組名稱，那么?gdb?默認讀取的配置分組。例如：?gdb.NewByGroup()?可獲取一個默認分組的數據庫對象。簡單的做法，我們可以通過?gdb?包的?SetConfig?配置管理方法進行自定義的數據庫全局配置，例如：

gdb.SetConfig(gdb.Config {
    "default" : gdb.ConfigGroup {
        gdb.ConfigNode {
            Host     : "192.168.1.100",
            Port     : "3306",
            User     : "root",
            Pass     : "123456",
            Name     : "test",
            Type     : "mysql",
            Role     : "master",
            Weight   : 100,
        },
        gdb.ConfigNode {
            Host     : "192.168.1.101",
            Port     : "3306",
            User     : "root",
            Pass     : "123456",
            Name     : "test",
            Type     : "mysql",
            Role     : "slave",
            Weight   : 100,
        },
    },
    "user-center" : gdb.ConfigGroup {
        gdb.ConfigNode {
            Host     : "192.168.1.110",
            Port     : "3306",
            User     : "root",
            Pass     : "123456",
            Name     : "test",
            Type     : "mysql",
            Role     : "master",
            Weight   : 100,
        },
    },
})

隨后，我們可以使用?gdb.NewByGroup("數據庫分組名稱")?來獲取一個數據庫操作對象。該對象用于后續(xù)的數據庫一系列方法/鏈式操作。