前言

通常業(yè)務系統(tǒng)開發(fā)中，數據庫的設計與維護是至關重要的環(huán)節(jié)。而數據庫的文檔化則是確保團隊成員之間有效溝通、快速理解系統(tǒng)架構的基礎。

但目前數據文檔都是手動寫的，耗時費力，由于當前項目使用的是 mysql 作為存儲引擎，找找看有沒有比較好用的工具，發(fā)現了一個比較契合的 mysql_markdown。

mysql_markdown 的使用

可以直接上 GitHub 上下載源碼，自行編譯。

快速使用

# 幫助
?  mysql_markdown -h
flag needs an argument: -h
Usage: mysql_markdown [options...]
--help  This help text
-h      host.     default 127.0.0.1
-u      username. default root
-p      password. default root
-d      database. default mysql
-P      port.     default 3306
-c      charset.  default utf8
-o      output.   default current location
-t      tables.   default all table and support ',' separator for filter, every item can use regexp
-l      language. default cn,support: cn,en# 使用
? mysql_markdown -p 123456 -d test
connecting to MySQL to export markdown document file.100% |█████████████████████████████████████████████████████████████████████████████████████| (1/1, 394 it/s)
convert to document finished in test_20241122_103043.md

go gorm 生成表/字段描述

使用過 gorm 的，對于生成數據庫字段描述應該不陌生，只需要在對應的結構體上添加 tag 即可，如下：

type User struct {Name string `gorm:"comment:姓名"`Age  int    `gorm:"comment:年齡"`
}

生成表的描述信息，注意：gorm 沒有提供類似 TableName 設置表名的方式來設置描述，得用 gorm:table_options 來設置，如果不是新建的表，這種設置方式也不能生效。

db.Set("gorm:table_options", "COMMENT '用戶表'").AutoMigrate(&User{})

實際例子

package mainimport ("gorm.io/driver/mysql""gorm.io/gorm""gorm.io/gorm/logger""log""os"
)type User struct {Name string `gorm:"comment:姓名"`Age  int    `gorm:"comment:年齡"`
}func (User) TableName() string {return "user"
}func getLocalTestDb() (db *gorm.DB, err error) {newLogger := logger.New(log.New(os.Stderr, "\r\n", log.LstdFlags), logger.Config{LogLevel:                  logger.Info,IgnoreRecordNotFoundError: true,Colorful:                  true,})db, err = gorm.Open(mysql.New(mysql.Config{DSN: "root:123456@tcp(127.0.0.1:3306)/test",}), &gorm.Config{Logger: newLogger, CreateBatchSize: 1000})return
}func main() {db, err := getLocalTestDb()if err != nil {log.Fatal(err)}db = db.Debug()// gorm:table_options 會在創(chuàng)建 table 的語句后添加相關的語句，不是新建的表不能生效err = db.Set("gorm:table_options", "COMMENT '用戶表'").AutoMigrate(&User{})if err != nil {log.Fatal(err)}log.Println("OK")
}

程序輸出

2024/11/22 10:23:08 main.go:41
[0.000ms] [rows:-] SELECT DATABASE()2024/11/22 10:23:08 main.go:41
[5.769ms] [rows:1] SELECT SCHEMA_NAME from Information_schema.SCHEMATA where SCHEMA_NAME LIKE 'test%' ORDER BY SCHEMA_NAME='test' DESC,SCHEMA_NAME limit 12024/11/22 10:23:08 main.go:41
[2.575ms] [rows:-] SELECT count(*) FROM information_schema.tables WHERE table_schema = 'test' AND table_name = 'user' AND table_type = 'BASE TABLE'2024/11/22 10:23:09 main.go:41
[49.289ms] [rows:0] CREATE TABLE `user` (`name` longtext COMMENT '姓名',`age` bigint COMMENT '年齡')COMMENT '用戶表'
2024/11/22 10:23:09 OK

使用 mysql_markdown 工具導出 md 文檔

mysql_markdown -p 123456 -d test

可見文檔內容如下：

## test tables message
#### 1、 user
用戶表| 序號 | 名稱 | 描述 | 類型 | 鍵 | 為空 | 額外 | 默認值 |
| :--: | :--: | :--: | :--: | :--: | :--: | :--: | :--: |
| 1 | `name` | 姓名 | longtext |  | YES |  |  |
| 2 | `age` | 年齡 | bigint |  | YES |  |  |

參考

• mysql_markdown