前言
通常业务系统开发中，数据库的设计与维护是至关重要的环节。而数据库的文档化则是确保团队成员之间有效沟通、快速理解系统架构的基础。
但目前数据文档都是手动写的，耗时费力，由于当前项目使用的是 mysql 作为存储引擎，找找看有没有比较好用的工具，发现了一个比较契合的 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 会在创建 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