Beego ORM中结构体字段必须用orm标签精确声明映射行为,否则导致列缺失、主键失效等;需首字母大写、主键加pk;auto、显式column、size/type控制类型、auto_now_add/auto_now处理时间、digits/decimals控精度、default设默认值、unique建唯一索引、rel(fk)和reverse配置关联。

在Beego ORM中定义结构体时,字段必须通过orm标签精确声明数据库映射行为,否则字段不会生成对应列、主键失效、索引丢失或类型错配——比如把int64字段漏写pk;auto,建表后该字段就只是普通 bigint 而非自增主键。
基础字段标签:主键、自增、列名
第一步:确保结构体字段首字母大写(Go导出规则),否则 ORM 完全忽略该字段,不会映射到数据库。
第二步:为整型主键字段同时添加 【pk;auto】 标签,例如:ID int64 `orm:"pk;auto;column(id)"`。只写 pk 不写 auto 会导致 MySQL 报错“Field 'id' doesn't have a default value”,因为 Beego 默认不给 pk 字段加 AUTO_INCREMENT 属性。
第三步:用 column(字段名) 显式指定数据库列名,避免默认下划线转换(如 CreatedAt → created_at)。若不写,Beego 会按驼峰转蛇形规则自动推导,但易与已有表结构冲突。
字符串与文本类型控制
方法一:设长度用 size(n),例如 Name string `orm:"size(64)"` → MySQL 中为 VARCHAR(64);不写 size 则默认 VARCHAR(255),可能浪费空间或触发严格模式报错。
方法二:存长文本必须用 type(text),例如 Content string `orm:"type(text)"` → 映射为 LONGTEXT;若仅靠 size(10000) 会失败,MySQL 的 VARCHAR 最大仅支持 65535 字节且受行总长限制。
方法三:允许 NULL 值需显式加 null,例如 Bio *string `orm:"null;size(512)"`;不加则默认 NOT NULL,插入 nil 时 ORM 会报错“invalid sql type”。
时间字段与自动更新逻辑
① 创建时间用 auto_now_add:仅首次 Insert 时写入当前时间,后续 Update 不变。标签写法:CreatedAt time.Time `orm:"auto_now_add;type(datetime)"`。
② 更新时间用 auto_now:每次调用 o.Update() 都刷新为当前时间,无需手动赋值。注意:【auto_now 和 auto_now_add 不会出现在 SQL 建表语句中,是 ORM 层运行时行为】,所以数据库字段本身仍是普通 DATETIME 类型。
③ 若需存储日期(不含时分秒),必须配合 type(date),例如:Birthday time.Time `orm:"type(date);null"` → 映射为 MySQL 的 DATE 类型;漏写 type(date) 会变成 DATETIME,导致查询精度偏差。
数值精度、默认值与唯一约束
float64 字段需用 digits(n);decimals(m) 控制精度,例如:Price float64 `orm:"digits(10);decimals(2)"` → DECIMAL(10,2);不写则映射为无精度保证的 DOUBLE,金融类场景可能引发四舍五入误差。
设置默认值用 default(值),注意值类型必须与 Go 字段类型一致:整型写 default(1),字符串写 default("pending"),布尔写 default(true);【default 仅影响 INSERT 语句,UPDATE 时不会回填】。
加唯一索引只需 unique,例如:Email string `orm:"size(128);unique"` → 自动生成 UNIQUE KEY;若同时需要普通索引,再额外加 index,两者可共存。
外键与关联关系标签
正向外键(本表存对方ID)用 rel(fk),并指定 column 名,例如:AuthorId int64 `orm:"column(author_id);rel(fk)"`;此时 Beego 会自动在 author_id 列上建外键约束并关联到 Author 表的主键。
反向一对多(如 User 下查多个 Post)用 reverse(many),字段类型必须为切片:Posts []*Post `orm:"reverse(many)"`;注意该字段不生成数据库列,纯 ORM 查询用。
一对一反向(如 Profile 查 User)用 reverse(one),字段类型为指针:User *User `orm:"reverse(one)"`;若正向已用 rel(one),此处可省略,但显式写出更清晰。











