# 数据库markdown文档生成器

**Repository Path**: to_free/kz-db-md-generator

## Basic Information

- **Project Name**: 数据库markdown文档生成器
- **Description**: 这是一个基于Spring Boot的MySQL数据库文档自动生成工具，能够连接到MySQL数据库，读取表结构信息，并生成格式化的中文markdown文档。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-09
- **Last Updated**: 2025-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据库markdown文档生成器

这是一个基于Spring Boot的MySQL数据库文档自动生成工具，能够连接到MySQL数据库，读取表结构信息，并生成格式化的中文markdown文档。

## 功能特性

- 🔗 **自动连接MySQL数据库** - 支持MySQL 5.x和8.x版本
- 📊 **完整的表结构分析** - 获取字段信息、数据类型、索引、注释等
- 📝 **标准化文档格式** - 生成符合规范的中文markdown文档
- 🛡️ **完善的错误处理** - 详细的中文错误提示和解决建议
- 🧪 **测试驱动开发** - 通过测试类执行，无需前端界面
- 📁 **灵活的输出配置** - 支持自定义输出路径和文件名

## 快速开始

### 1. 环境要求

- Java 8 或更高版本
- Maven 3.6 或更高版本
- MySQL 5.7 或更高版本

### 2. 配置数据库连接

编辑 `application.yml` 文件，修改数据库连接配置：

```yaml
database:
  url: jdbc:mysql://localhost:3306/your_database_name?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
  username: your_username
  password: your_password
```

### 3. 运行文档生成

使用Maven运行测试类来生成文档：

```bash
# 编译项目
mvn clean compile

# 运行文档生成测试
mvn test -Dtest=DatabaseDocGeneratorTest#generateDatabaseDocumentation
```

或者运行所有测试：

```bash
mvn test
```

### 4. 查看生成的文档

文档将保存在 `./output/` 目录下，文件名格式为：`{数据库名}数据库设计说明书_{日期}.md`

## 配置说明

### 数据库配置

| 配置项 | 说明 | 示例 |
|--------|------|------|
| `database.url` | 数据库连接URL | `jdbc:mysql://localhost:3306/test` |
| `database.username` | 数据库用户名 | `root` |
| `database.password` | 数据库密码 | `password` |
| `database.driver-class-name` | 驱动类名 | `com.mysql.cj.jdbc.Driver` |

### 文档生成配置

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `documentation.output-path` | 输出文件路径 | `./output/` |
| `documentation.template-version` | 文档版本号 | `1.0.0` |
| `documentation.author` | 文档作者 | `系统生成` |
| `documentation.database-name` | 数据库名称 | 从URL自动提取 |

## 生成的文档格式

生成的markdown文档包含以下内容：

1. **文档标题** - `{数据库名}数据库设计说明书`
2. **修改历史记录** - 版本、日期、修订者信息
3. **数据结构章节** - 每个表的详细信息
   - 索引信息表格（主键、唯一索引、普通索引）
   - 字段信息表格（字段名、类型、是否允许空、默认值、说明）

### 示例输出

```markdown
# 测试数据库数据库设计说明书

## 1.修改历史记录

| 版本  | 日期      | amd  | 修订者 | 说明     |
| ----- | --------- | ---- | ------ | -------- |
| 1.0.0 | 2024-1-15 | a    | 系统生成 | 自动生成 |

## 2.数据结构
###  2.1.基础表结构
#### 用户表(users)

|   类型    | 名称        | 序号 | 字段名       | 备注         |
| :-------: | ----------- | ---- | ------------ | ------------ |
| 主键 | PRIMARY | 1 | id | |
| 唯一索引 | uk_username | 1 | username |  |

| 字段名       | 名称         | 类型         | 允许空 | 默认值 | 说明                                  |
| ------------ | ------------ | ------------ | ------ | ------ | ------------------------------------- |
| id | 用户ID | bigint(20) | 否 |  | AUTO_INCREMENT |
| username | 用户名 | varchar(50) | 否 |  |  |
| email | 邮箱 | varchar(100) | 是 |  |  |
```

## 测试功能

项目包含多个测试类来验证不同功能：

### 主要测试

```bash
# 生成完整的数据库文档
mvn test -Dtest=DatabaseDocGeneratorTest#generateDatabaseDocumentation

# 测试数据库连接
mvn test -Dtest=DatabaseDocGeneratorTest#testDatabaseConnection

# 测试文档生成功能
mvn test -Dtest=DatabaseDocGeneratorTest#testDocumentGeneration
```

### 单元测试

```bash
# 测试文档生成服务
mvn test -Dtest=DocumentGeneratorServiceTest

# 测试数据模型
mvn test -Dtest=TableInfoTest,ColumnInfoTest,IndexInfoTest
```

## 常见问题

### 1. 数据库连接失败

**错误信息：** `数据库连接测试失败`

**解决方案：**
- 检查数据库服务是否启动
- 验证数据库URL、用户名和密码是否正确
- 确认网络连接是否正常
- 检查防火墙设置
- 验证MySQL驱动版本是否兼容

### 2. 权限不足

**错误信息：** `用户没有查看表结构的权限`

**解决方案：**
```sql
-- 授予用户查看表结构的权限
GRANT SELECT ON database_name.* TO 'username'@'%';
GRANT SHOW VIEW ON database_name.* TO 'username'@'%';
FLUSH PRIVILEGES;
```

### 3. 文件保存失败

**错误信息：** `文件操作失败`

**解决方案：**
- 检查输出目录是否存在写入权限
- 确认磁盘空间是否充足
- 验证文件路径是否包含非法字符

### 4. 中文字符显示异常

**解决方案：**
- 确保数据库连接URL包含字符编码设置：`?useUnicode=true&characterEncoding=utf8`
- 检查数据库表和字段的字符集设置

## 项目结构

```
src/
├── main/
│   ├── java/com/example/dbdoc/
│   │   ├── config/          # 配置类
│   │   ├── exception/       # 异常处理
│   │   ├── model/          # 数据模型
│   │   ├── service/        # 业务服务
│   │   └── DatabaseDocGeneratorApplication.java
│   └── resources/
│       ├── application.yml          # 配置文件
│       ├── application-example.yml  # 示例配置
│       └── logback-spring.xml      # 日志配置
└── test/
    └── java/com/example/dbdoc/
        ├── model/          # 模型测试
        ├── service/        # 服务测试
        └── DatabaseDocGeneratorTest.java  # 主测试类
```

## 技术栈

- **Spring Boot 2.7.18** - 应用框架
- **MySQL Connector/J 8.0.33** - MySQL驱动
- **JUnit 5** - 单元测试框架
- **Logback** - 日志框架
- **Maven** - 项目管理工具

## 许可证

本项目采用 MIT 许可证。

## 贡献

欢迎提交Issue和Pull Request来改进这个项目。

## 更新日志

### v1.0.0 (2024-01-15)
- 初始版本发布
- 支持MySQL数据库连接和表结构读取
- 生成标准化的中文markdown文档
- 完善的错误处理和日志记录
- 全面的单元测试覆盖