# gin-gorm

**Repository Path**: chenbool/gin-gorm

## Basic Information

- **Project Name**: gin-gorm
- **Description**: No description available
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-04
- **Last Updated**: 2025-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gin-gorm

## 项目介绍

这是一个全面、系统的基于 Go 语言的 GORM 数据库操作示例项目，旨在帮助 Go 开发者快速掌握 GORM ORM 框架的核心功能和最佳实践。项目从基础连接到高级特性，循序渐进地演示了如何使用 GORM 进行 MySQL 数据库的各项操作。

### 项目价值

- **全面覆盖**：涵盖从数据库连接、表结构迁移到高级查询的完整 GORM 功能集
- **实例导向**：每个功能点都配有简洁明了的代码示例，易于理解和实践
- **系统组织**：按照操作类型和复杂度合理组织代码，便于查阅和学习
- **中文注释**：所有代码均提供详细的中文注释，降低学习门槛
- **实用技巧**：包含大量实际开发中常用的技巧和最佳实践

## 项目架构

### 目录结构

项目采用清晰的分层架构设计，将数据访问、业务逻辑和配置管理分离，便于维护和扩展：

```bash
.
├── global/                 # 全局配置与连接管理
│   └── enter.go           # 数据库连接初始化与全局DB对象管理
├── models/                # 数据模型定义层
│   ├── user_model.go      # 用户模型定义（包含基本字段和约束）
│   ├── girl_model.go      # 女孩模型定义（一对多关联示例）
│   ├── boy_model.go       # 男孩模型定义（一对多关联示例）
│   ├── article_model.go   # 文章模型定义（多对多关联示例）
│   ├── tag_model.go       # 标签模型定义（多对多关联示例）
│   ├── user_article.go    # 用户文章关联模型（自定义多对多中间表）
│   ├── user_zdy.go        # 自定义数据类型模型
│   └── log_model.go       # 日志模型定义（枚举类型示例）
├── 0.原生SQL.go           # 原生SQL查询示例
├── 1.连接.go              # 数据库连接配置与测试示例
├── 2.自动生成表.go         # 表结构自动迁移与更新示例
├── 3.单表操作.go           # 单表数据插入操作示例（单条和批量）
├── 4.查询.go              # 基本数据查询操作示例
├── 5.更新.go              # 数据更新操作示例（多种更新方式）
├── 6.删除.go              # 数据删除操作示例（包含软删除）
├── 7.高级查询.go           # 高级条件查询示例（复合条件、排序等）
├── 8.scan 分组 去重.go     # 数据转换与聚合示例（Scan、分组、去重）
├── 9.分页 Scope.go        # 分页查询与可重用查询逻辑示例
├── 10.一对一.go           # 一对一关联关系操作示例
├── 11.一对多.go           # 一对多关联关系操作示例
├── 12.多对多.go           # 多对多关联关系操作示例
├── 13.多对多自定义表.go     # 自定义中间表的多对多关联示例
├── 14.自定义数据.go        # 自定义数据类型处理示例
├── 15.枚举类型.go         # 枚举类型处理示例
├── 16.事务.go             # 事务处理示例
├── go.mod                 # Go 模块定义文件
├── go.sum                 # Go 模块依赖校验文件
└── README.md              # 项目说明文档
```

### 核心模块架构图

```mermaid
graph TD
    A[应用程序入口] --> B[全局配置层]
    A --> C[数据模型层]
    A --> D[业务逻辑层]
    
    B --> B1[数据库连接管理]
    B --> B2[表结构迁移]
    
    C --> C1[基础模型]
    C --> C2[关联关系模型]
    C --> C3[自定义数据模型]
    
    D --> D1[CRUD操作]
    D --> D2[关联操作]
    D --> D3[高级查询]
    D --> D4[事务处理]
    
    C1 --> E[UserModel]
    C2 --> F[GirlModel/BoyModel]
    C2 --> G[ArticleModel/TagModel]
    C2 --> H[User1Model/Article1Model]
    C3 --> I[UserZdyModel]
    C3 --> J[LogModel]
    
    D1 --> D11[创建(Create)]
    D1 --> D12[查询(Read)]
    D1 --> D13[更新(Update)]
    D1 --> D14[删除(Delete)]
    
    D2 --> D21[一对一关联]
    D2 --> D22[一对多关联]
    D2 --> D23[多对多关联]
    
    D3 --> D31[条件查询]
    D3 --> D32[分组统计]
    D3 --> D33[分页查询]
    D3 --> D34[Scope查询]
    
    D4 --> D41[自动事务]
    D4 --> D42[手动事务]
```

### 核心组件说明

| 模块类别 | 组件名称 | 文件路径 | 主要职责 | 特点 |
|---------|---------|---------|---------|------|
| **基础配置** | 数据库连接 | [1.连接.go](./1.连接.go) | 数据库连接参数配置与测试 | 包含错误处理与连接验证 |
| | 全局连接管理 | [global/enter.go](./global/enter.go) | 提供全局数据库连接对象 | 单例模式，全局复用 |
| **数据模型** | 用户模型 | [models/user_model.go](./models/user_model.go) | 定义用户实体结构与约束 | 包含字段验证与钩子函数 |
| | 关联模型 | [models/girl_model.go, models/boy_model.go]() | 定义关联实体结构 | 演示一对多关系定义 |
| | 多对多模型 | [models/article_model.go, models/tag_model.go]() | 定义多对多关联结构 | 演示多对多关系定义 |
| | 自定义模型 | [models/user_article.go, models/user_zdy.go]() | 自定义中间表和数据类型 | 演示高级关联和自定义类型 |
| **CRUD操作** | 表结构迁移 | [2.自动生成表.go](./2.自动生成表.go) | 自动创建和更新表结构 | 基于模型自动同步表结构 |
| | 数据插入 | [3.单表操作.go](./3.单表操作.go) | 演示数据添加方法 | 支持单条和批量插入 |
| | 数据查询 | [4.查询.go](./4.查询.go) | 基本数据检索功能 | 包含条件查询和单条查询 |
| | 数据更新 | [5.更新.go](./5.更新.go) | 多种数据更新策略 | 支持全量、部分、条件更新 |
| | 数据删除 | [6.删除.go](./6.删除.go) | 数据删除与软删除 | 支持物理删除和软删除 |
| **高级功能** | 高级查询 | [7.高级查询.go](./7.高级查询.go) | 复杂条件组合查询 | 包含WHERE、OR、NOT等高级条件 |
| | 数据转换与聚合 | [8.scan 分组 去重.go](./8.scan%20分组%20去重.go) | 数据映射与统计分析 | 支持Scan、分组统计、去重 |
| | 分页与可重用查询 | [9.分页 Scope.go](./9.分页%20Scope.go) | 分页功能与查询逻辑复用 | 使用Limit/Offset和Scope实现 |
| | 原生SQL操作 | [0.原生SQL.go](./0.原生SQL.go) | 执行原生SQL语句 | 适用于复杂查询场景 |
| **关联操作** | 一对一关联 | [10.一对一.go](./10.一对一.go) | 一对一关系操作示例 | 包含创建、查询、删除关联数据 |
| | 一对多关联 | [11.一对多.go](./11.一对多.go) | 一对多关系操作示例 | 演示主从表数据操作方法 |
| | 多对多关联 | [12.多对多.go](./12.多对多.go) | 多对多关系操作示例 | 演示关联表操作方法 |
| | 自定义多对多 | [13.多对多自定义表.go](./13.多对多自定义表.go) | 自定义中间表关联操作 | 支持额外字段的关联关系 |
| **特殊数据类型** | 自定义数据 | [14.自定义数据.go](./14.自定义数据.go) | 自定义数据类型处理 | 演示JSON序列化自定义 |
| | 枚举类型 | [15.枚举类型.go](./15.枚举类型.go) | 枚举类型处理 | 演示自定义枚举序列化 |
| **事务处理** | 事务操作 | [16.事务.go](./16.事务.go) | 事务处理示例 | 包含自动和手动事务控制 |

### 数据模型关系图

```mermaid
erDiagram
    UserModel ||--o{ UserDetailModel : "一对一"
    GirlModel ||--o{ BoyModel : "一对多"
    ArticleModel }o--o{ TagModel : "多对多"
    User1Model }o--o{ Article1Model : "多对多(自定义)"
    User2ArticleModel }|--|| User1Model : "关联"
    User2ArticleModel }|--|| Article1Model : "关联"
    UserZdy ||--|| UserInfo : "嵌套"
    UserZdy ||--|| Card : "嵌套"
    LogModel ||--|| Level : "枚举"
```

## 软件架构

本项目基于 GORM 框架构建，GORM 是 Go 语言中最受欢迎的 ORM (Object-Relational Mapping) 库之一，它提供了强大的数据库操作功能，简化了数据库交互代码。

### 技术栈

项目采用现代化的技术栈组合，确保高性能、可靠性和开发效率：

| 技术类别 | 技术/依赖 | 版本 | 用途 | 优势 | 来源 |
|---------|-----------|------|------|------|------|
| **编程语言** | Go | 1.25+ | 主要开发语言 | 高性能、并发友好、编译快速 | [Go 官网](https://golang.org/) |
| **ORM框架** | GORM | v1.31.0 | 数据库操作抽象层 | 强大的CRUD操作、关联支持、钩子函数 | [GORM 官网](https://gorm.io/) |
| **数据库** | MySQL | 5.7+ | 关系型数据库存储 | 稳定性高、社区活跃、功能完善 | [MySQL 官网](https://www.mysql.com/) |
| **数据库驱动** | MySQL Driver | v1.6.0 | MySQL驱动程序 | 高性能、兼容性好、维护活跃 | [GitHub](https://github.com/go-sql-driver/mysql) |
| **项目管理** | Go Modules | 内置 | 依赖管理 | 版本控制精确、依赖解析可靠 | [Go Modules 文档](https://golang.org/ref/mod) |

### 依赖管理

项目使用 Go Modules 进行依赖管理，主要依赖如下：

```bash
# 初始化项目
# go mod init gin-gorm

# 主要依赖
gorm.io/gorm        # 核心 ORM 框架
gorm.io/driver/mysql # MySQL 数据库驱动
```

## 安装教程

### 环境准备

1. **安装 Go**：确保已安装 Go 1.25 或更高版本
   ```bash
   # 查看 Go 版本
go version
   ```

2. **安装 MySQL**：确保本地已安装并运行 MySQL 数据库服务
   ```bash
   # 验证 MySQL 是否运行
   # Windows
   net start mysql
   
   # Linux/macOS
   systemctl status mysql
   ```

### 项目安装

1. **克隆项目**：将项目代码克隆到本地
   ```bash
   git clone <repository-url>
   cd gin-gorm
   ```

2. **初始化依赖**：下载并安装项目依赖
   ```bash
   go mod tidy
   ```

3. **创建数据库**：在 MySQL 中创建名为 `gorm` 的数据库
   ```sql
   CREATE DATABASE gorm DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   ```

## 使用说明

### 数据库配置

项目默认使用以下数据库配置：

- 用户名：`root`
- 密码：`root`
- 主机：`127.0.0.1`
- 端口：`3306`
- 数据库名：`gorm`
- 字符集：`utf8mb4`

如需修改数据库连接配置，请编辑 [global/enter.go](./global/enter.go) 文件中的连接字符串。

### 运行示例

项目包含多个独立的示例程序，每个文件对应一种操作类型，可以分别运行：

1. **数据库连接示例**：演示如何连接到 MySQL 数据库
   ```bash
   go run 1.连接.go
   ```

2. **表结构迁移示例**：演示如何自动创建数据库表
   ```bash
   go run 2.自动生成表.go
   ```

3. **数据插入示例**：演示如何向数据库表中插入数据
   ```bash
   go run 3.单表操作.go
   ```

4. **数据查询示例**：演示如何查询数据库中的数据
   ```bash
   go run 4.查询.go
   ```

5. **数据更新示例**：演示如何更新数据库中的数据
   ```bash
   go run 5.更新.go
   ```

6. **数据删除示例**：演示如何删除数据库中的数据
   ```bash
   go run 6.删除.go
   ```

7. **高级查询示例**：演示复杂条件查询的使用方法
   ```bash
   go run 7.高级查询.go
   ```

8. **数据转换与聚合示例**：演示 Scan、分组和去重操作
   ```bash
   go run 8.scan\ 分组\ 去重.go
   ```

9. **分页与 Scope 示例**：演示分页查询和可重用查询逻辑
   ```bash
   go run 9.分页\ Scope.go
   ```

10. **原生 SQL 示例**：演示如何执行原生 SQL 查询
    ```bash
    go run 0.原生SQL.go
    ```

### 功能特点

本项目以功能完整、示例丰富、实用性强为特点，全面覆盖 GORM 的核心功能和最佳实践：

#### 🏗️ 数据库基础操作
- **完整 CRUD 示例**：提供全面的增删改查操作演示
- **表结构管理**：支持自动迁移、表创建和更新
- **数据类型映射**：展示 Go 类型与数据库类型的对应关系

#### 🔍 查询功能
- **基础查询**：单条查询、多条查询、条件查询
- **高级查询**：复合条件、OR/NOT 条件、嵌套条件
- **数据转换**：Scan 方法实现灵活数据映射
- **聚合统计**：分组查询、去重查询、计数统计
- **分页功能**：标准分页实现，支持自定义页大小

#### 🔄 数据操作
- **多种更新方式**：全量更新、部分更新、条件更新
- **删除策略**：物理删除、软删除支持
- **批量操作**：批量插入、批量更新、批量删除

#### 🔗 关联关系
- **一对一关联**：关联定义、级联操作、预加载
- **一对多关联**：主从表操作、数据同步
- **多对多关联**：关联表操作、自定义中间表

#### 🛠️ 高级特性
- **Scope 可重用查询**：封装和复用查询逻辑
- **事务处理**：声明式事务、手动事务控制
- **钩子函数**：生命周期钩子、业务逻辑注入
- **原生 SQL 支持**：执行自定义 SQL 查询和命令
- **自定义数据类型**：JSON序列化、枚举类型处理

#### 💡 实用技巧
- **性能优化**：查询优化、索引使用建议
- **错误处理**：完整的错误处理模式
- **连接管理**：数据库连接池配置和管理

## 开发建议

### 🏢 项目结构最佳实践
- **模块化设计**：将业务逻辑、数据访问和API层分离
- **配置外部化**：将数据库连接参数等配置抽取到环境变量或配置文件
- **统一错误处理**：建立全局错误处理机制，确保错误信息清晰一致
- **日志管理**：集成结构化日志系统，便于问题排查和性能监控

### 🚀 性能优化指南
- **连接池管理**：生产环境中配置合适的数据库连接池大小
- **索引优化**：为频繁查询的字段添加适当索引
- **查询优化**：使用Select指定所需字段，避免查询不必要的数据
- **预加载关联**：使用Preload或Joins预加载关联数据，避免N+1查询问题
- **批量操作**：对大量数据操作使用批量API，减少网络开销

### 🛡️ 安全建议
- **参数绑定**：使用GORM的参数绑定功能，避免SQL注入风险
- **数据验证**：在业务层实现完善的数据验证逻辑
- **事务管理**：对关键业务操作使用事务确保数据一致性
- **权限控制**：实现细粒度的数据访问权限控制

## 注意事项

### ⚠️ 使用前准备
- **环境要求**：确保安装Go 1.20+和MySQL 5.7+版本
- **依赖安装**：运行`go mod tidy`安装所需依赖包
- **配置修改**：根据您的环境修改数据库连接参数（用户名、密码、数据库名等）

### 📋 示例使用说明
- 所有示例文件可以独立运行，通过`go run 文件名.go`执行
- 建议按照示例序号顺序学习，从基础到高级逐步掌握
- 每个示例文件都包含完整的注释说明，帮助理解代码逻辑

### 🚧 生产环境注意事项
- 本项目示例主要用于学习目的，在生产环境中请根据实际情况进行调整
- 生产环境应使用更严格的错误处理和日志记录机制
- 考虑使用数据库迁移工具管理表结构变更
- 对于高并发场景，需要额外的性能优化和资源监控

### 🔄 版本兼容性
- 示例代码基于GORM v2.x版本编写，请确保使用兼容版本
- 不同版本的GORM API可能存在差异，请参考官方文档进行适配

## 参考资料

- [GORM 官方文档](https://gorm.io/zh_CN/docs/)
- [Go 语言官方文档](https://golang.org/doc/)
- [MySQL 官方文档](https://dev.mysql.com/doc/)

## 参考资料

- [GORM 官方文档](https://gorm.io/zh_CN/docs/)
- [Go 官方网站](https://golang.org/)
- [MySQL 官方文档](https://dev.mysql.com/doc/)

3. 运行数据插入示例：
   ```bash
   go run 3.单表操作.go
   ```

4. 运行数据查询示例：
   ```bash
   go run 4.查询.go
   ```

### 功能演示

| 功能 | 对应文件 | 说明 |
|------|---------|------|
| 数据库连接 | [1.连接.go](./1.连接.go) | 建立与 MySQL 数据库的连接 |
| 表结构迁移 | [2.自动生成表.go](./2.自动生成表.go) | 使用 GORM 的 AutoMigrate 自动创建用户表 |
| 数据插入 | [3.单表操作.go](./3.单表操作.go) | 演示单条和批量数据插入操作 |
| 数据查询 | [4.查询.go](./4.查询.go) | 演示多种查询方式，包括条件查询、单条查询等 |

## 数据模型

### 用户模型 (UserModel)

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| ID | int64 | primaryKey | 主键，自动递增 |
| Name | string | size:16;not null;unique | 用户名，最大16字符，非空且唯一 |
| Age | int | default:18 | 年龄，默认值18 |
| CreatedAt | time.Time | - | 创建时间，自动设置 |

## 高级特性

### 钩子函数

在 [models/user_model.go](./models/user_model.go) 中实现了 `BeforeCreate` 钩子函数，在创建用户记录前会自动调用。

### 错误处理

所有数据库操作都包含适当的错误处理机制，确保程序的健壮性。

## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

## 许可证

本项目采用 MIT 许可证，详情请见 [LICENSE](LICENSE) 文件。