gin-vue-admin Model 层开发指南GORM 实体定义、标签规范与字段类型约定【免费下载链接】gin-vue-adminViteVue3Gin的开发基础平台支持TS和JS混用。它集成了JWT鉴权、权限管理、动态路由、显隐可控组件、分页封装、多点登录拦截、资源权限、上传下载、代码生成器【可AI辅助】、表单生成器和可配置的导入导出等开发必备功能。项目地址: https://gitcode.com/flipped-aurora/gin-vue-admin导读本文面向在 gin-vue-admin 项目中新增或修改数据库实体的开发者包括 AI 辅助编码场景系统讲解后端server/model/**目录下数据模型Model的编写规范。你将掌握global.GVA_MODEL基类的继承方式、json与gorm双标签的使用约定、关联关系的声明方法、字段命名与类型一致性要点并结合仓库中的真实模型文件如sys_api_token.go、sys_user.go获得可直接照抄的实战写法。背景Model 在分层架构中的定位gin-vue-admin 后端采用经典的分层结构router → api → service → model其中Model 负责定义数据库实体与持久化字段是 Service 与数据库交互的基础。项目目录划分见 server/model主要包含三块server/model/system系统核心实体用户、角色、菜单、API、字典、操作记录等server/model/example示例业务实体客户、文件上传下载等也是代码生成器的参考样板server/model/common公共基类型如JSONMap、JSONSlice等自定义字段类型。当你需要新增一张业务表、为现有表补字段、或定义 GORM 结构与关联关系时就应当遵循本文介绍的写法。这也是 aiDoc/examples/backend 中约定的后端分层示例之一其余还有 request、service、api、router、enter.go 等示例见 model-example.md。一、什么时候应该写 Model 文件根据 model-example.md 的约定以下场景需要在server/model/**中新增或修改代码新增一张业务表定义全新的持久化实体对应数据库中的一张新表为现有表补字段在已有实体上扩展持久化字段需要定义 GORM 结构与关联关系声明一对一、一对多、多对多关系或需要定制表名、索引、默认值等。注意仅用于请求参数校验、或仅用于接口展示如列表视图 DTO的数据不应直接塞进数据库 model而是放在对应的request/response包中如 server/model/system/request 与 server/model/system/response。二、推荐写法示例model-example.md 给出了一个最小可用的订单模型示例package system import github.com/flipped-aurora/gin-vue-admin/server/global type Order struct { global.GVA_MODEL Name string json:name gorm:comment:订单名称 Status int json:status gorm:default:1;comment:订单状态 Remark string json:remark gorm:comment:备注 CreatorID uint json:creatorId gorm:comment:创建人ID }几个关键点结构体命名为Order对应表名默认是复数蛇形形式orders首行嵌入global.GVA_MODEL自动获得主键与时间字段每个业务字段必须同时带json标签接口输出用与gorm标签字段约束用布尔、枚举类字段建议声明默认值如default:1。三、为什么这样写标签背后的原理3.1 继承global.GVA_MODEL基类global.GVA_MODEL定义在 server/global/model.gotype GVA_MODEL struct { ID uint gorm:primarykey json:ID // 主键ID CreatedAt time.Time // 创建时间 UpdatedAt time.Time // 更新时间 DeletedAt gorm.DeletedAt gorm:index json:- // 删除时间 }继承它带来的效果主键风格统一ID为uint自增主键所有表主键命名一致时间字段统一自动获得CreatedAt、UpdatedAtGORM 会自动维护软删除开箱即用DeletedAt gorm.DeletedAt实现了 GORM 软删除——删除操作变为逻辑删除写入删除时间查询时自动过滤已删除记录且该字段通过json:-隐藏不会出现在接口输出中。从源码结构看几乎所有业务实体sys_api_token.go、exa_customer.go 等都以嵌入global.GVA_MODEL开头这是项目内最强的一致性原则。3.2json标签前后端字段契约json标签决定结构体序列化为 JSON 时的字段名是前端接口契约。例如sys_api_token.go中UserID uint json:userId gorm:comment:用户ID AuthorityID uint json:authorityId gorm:comment:角色ID前端拿到的字段就是userId、authorityId驼峰命名而 Go 源码中则是UserID、AuthorityID大驼峰。两者通过标签解耦因此字段命名要清晰、稳定避免随意改名造成前端联动修改同一字段在前后端必须使用相同语义的命名如userId就统一用userId这正是 model-example.md 强调的字段命名尽量清晰、稳定便于前后端保持一致。3.3gorm标签字段级数据库约束gorm标签用于约束字段类型、默认值和注释。常见用法汇总均来自仓库真实代码用法示例含义字段注释gorm:comment:订单名称生成表结构时写入字段注释默认值gorm:default:1;comment:订单状态插入时未指定则取默认值类型指定gorm:type:text;comment:Token强制指定数据库列类型长文本等索引gorm:index;comment:用户UUID为该字段建普通索引唯一gorm:not null;unique;primary_key非空 唯一如角色 ID见 sys_authority.go外键gorm:foreignKey:UserID声明关联外键多对多gorm:many2many:sys_user_authority;声明连接表内嵌结构gorm:embedded将子结构字段扁平化嵌入本表忽略字段gorm:-不映射数据库列仅用于内存计算/展示参考实例sys_user.go中HeaderImg带default:https://...头像默认值、AuthorityId带default:888sys_operation_record.go中Agent、Body、Resp使用type:text存放可能较长的内容。四、进阶关联关系与自定义字段4.1 外键关联belongs to / has manyserver/model/system/sys_api_token.go 展示了外键关联的标准写法type SysApiToken struct { global.GVA_MODEL UserID uint json:userId gorm:comment:用户ID User SysUser json:user gorm:foreignKey:UserID; AuthorityID uint json:authorityId gorm:comment:角色ID Token string json:token gorm:type:text;comment:Token Status bool json:status gorm:default:true;comment:状态 // true有效 false无效 ExpiresAt time.Time json:expiresAt gorm:comment:过期时间 Remark string json:remark gorm:comment:备注 }要点同时保留外键字段UserID和关联字段User SysUser通过gorm:foreignKey:UserID绑定SysUser类型来自同包定义sys_user.go跨包引用时需显式 import见 exa_customer.go 中对system.SysUser的引用关联字段也带json标签方便接口输出嵌套用户信息。4.2 多对多与自关联server/model/system/sys_user.go 演示了多对多用户 ↔ 角色Authorities []SysAuthority json:authorities gorm:many2many:sys_user_authority;连接表sys_user_authority由 GORM 自动维护无需手动建实体。server/model/system/sys_dictionary.go 演示了一对多自关联父字典 → 子字典ParentID *uint json:parentID gorm:column:parent_id;comment:父级字典ID Children []SysDictionary json:children gorm:foreignKey:ParentID注意父字段用*uint允许为空表示顶级节点并用column:parent_id显式指定列名以保持蛇形命名。同样的自关联模式也出现在 sys_dictionary_detail.go。4.3 自定义表名默认表名由 GORM 根据结构体名推导复数蛇形。需要定制时实现TableName()方法例如 sys_user.gofunc (SysUser) TableName() string { return sys_users }server/model/system/sys_api.go 同样通过该方法将SysApi映射到sys_apis。这是保持系统内表名命名统一复数、蛇形的可靠手段。4.4 JSON 类型字段公共基类型gin-vue-admin 在 server/model/common/basetypes.go 中提供了可直接使用的 JSON 字段类型JSONMapmap[string]any序列化为 JSON 列JSONSlice[T]泛型切片如[]string、[]int。它们实现了driver.Valuer/sql.Scanner并会根据方言自动选择数据库列类型MySQL 为JSON旧版/ MariaDB 回退LONGTEXT、PostgreSQL 为JSONB。使用示例见 sys_user.go 中的OriginSetting common.JSONMap字段搭配gorm:type:text;default:null;column:origin_setting;comment:配置;使用。五、常见错误清单务必规避model-example.md 明确列出了以下高频问题缺少json或gorm标签字段将无法正确输出到接口或无法生成合理的表结构把仅用于请求或展示的字段直接写入数据库 model应放入request/response包避免污染表结构如按钮权限等只读计算字段在sys_dictionary_detail.go中用gorm:-排除同一个字段在前后端使用不同类型前端userId为字符串、后端却定义为uint会导致类型不匹配与隐性 bug忽略Status、ID、时间字段这类高风险类型一致性问题ID统一用uint、状态字段统一用int/bool、时间统一用time.Time并尽量使用global.GVA_MODEL继承的字段避免重复定义主键与时间字段造成风格分裂。六、真实参考文件以下是仓库中可直接参考的成熟 Model 文件建议在动手前逐一对照server/model/system/sys_api_token.go外键关联 type:text长文本 默认值 时间字段的完整示例server/model/system/sys_user.go多对多、索引、默认值、TableName()、common.JSONMap综合示例server/model/system/sys_base_menu.gogorm:embedded内嵌子结构、多对多、gorm:-忽略字段示例server/model/system/sys_authority.go自定义主键primary_key与not null;unique约束示例server/model/system/sys_operation_record.gotime.Duration、type:text、关联用户字段示例server/model/example/exa_customer.go跨包引用system.SysUser的示例业务实体。结语Model 层是 gin-vue-admin 后端数据链路的基石。遵循本文约定——统一继承global.GVA_MODEL、为每个持久化字段同时声明json与gorm标签、按需声明关联关系与自定义表名、保持字段命名与类型的前后端一致——就能让新增的业务表与既有系统风格完全对齐也能让 AI 辅助生成的后端代码与人工代码无缝衔接减少后续维护成本。【免费下载链接】gin-vue-adminViteVue3Gin的开发基础平台支持TS和JS混用。它集成了JWT鉴权、权限管理、动态路由、显隐可控组件、分页封装、多点登录拦截、资源权限、上传下载、代码生成器【可AI辅助】、表单生成器和可配置的导入导出等开发必备功能。项目地址: https://gitcode.com/flipped-aurora/gin-vue-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考