XORM框架标签需用column(单引号包裹)、type(内置关键词)与null/notnull显式声明:xorm:"varchar(20) 'user_name' notnull"精确控制字段名、类型及非空约束。

XORM框架标签怎么用?拆解column、type与null属性
要在Go结构体中精确控制数据库字段名、类型和空值约束,必须正确使用xorm结构体字段上的Tag——它不是可选装饰,而是映射逻辑的核心开关。写错一个关键字或漏掉引号,可能导致建表失败、字段名被自动蛇形转换、甚至null约束失效。
定义字段名:用name或单引号包裹的column
方法一:直接指定数据库列名
在字段Tag中写 xorm:"name(user_name)" 或 xorm:"'user_name'",两者等效。前者显式声明name关键字,后者用单引号包裹即默认视为列名。【单引号不可省略于含下划线、数字开头或与关键字冲突的列名】
方法二:混用列名与类型声明
写成 xorm:"varchar(50) 'usr_name'" 是合法的,xorm会把单引号内内容识别为列名,其余部分解析为类型和约束。但若写成 xorm:"varchar(50) usr_name"(无引号),xorm会尝试按SnakeMapper规则转换usr_name → usr_name,实际仍可能生效,但属于隐式行为,不推荐。
注意:如果结构体字段名本身是 UserName,而你希望数据库列名为 user_name,仅靠 xorm:"varchar(50)" 不够——xorm默认启用 SnakeMapper,会自动转,但这种依赖映射器的行为不稳定;显式写 'user_name' 才真正锁定列名。
声明数据类型:用xorm内置类型关键词
第一步:选择兼容型关键词
xorm不强制要求写标准SQL类型(如VARCHAR),而是提供了一组跨数据库适配的关键词:text、tinytext、mediumtext、longtext、blob、tinyblob、mediumblob、longblob、char、varchar、tinyint、smallint、mediumint、int、bigint、float、double、decimal、bool、date、datetime、time、timestamp、binary、varbinary、enum、set。
第二步:带长度或精度时加括号xorm:"varchar(32)" 合法;xorm:"decimal(10,2)" 合法;xorm:"int(11)" 在MySQL中有效,但PostgreSQL会忽略括号内容,所以更稳妥的是只写 xorm:"int" 并依赖驱动自动适配。
第三步:避免混用原生SQL类型
不要写 xorm:"VARCHAR(32) NOT NULL"(全大写+空格+SQL关键字)。xorm解析Tag时区分大小写不敏感,但NOT NULL会被当作字段名的一部分而非约束,导致建表语句出错。正确写法是 xorm:"varchar(32) notnull"。
控制NULL约束:notnull与null必须显式声明
方法1:禁止为空 → 加 notnullName string `xorm:"varchar(20) notnull"` 生成的SQL字段定义为 name VARCHAR(20) NOT NULL。这是最常用也最安全的写法。
方法2:允许为空 → 显式加 null 或不加任何约束
默认情况下,未声明 notnull 的字段即为可空。但强烈建议显式写 null,例如 Remark string `xorm:"text null"`,因为某些版本xorm在字段类型为text/blob时会默认加notnull,显式声明可消除歧义。
方法3:禁用隐式NOT NULL陷阱
如果字段是int64且未赋初值,在Go中默认为0,但数据库里你可能希望它是NULL。此时必须同时写 xorm:"int null" 并确保该字段在Insert前设为指针类型(*int64)或使用 -> 标签控制写入逻辑,否则0会被写入而非NULL。
组合实战:一个字段标签的完整拆解
看这个真实字段:CreatedAt time.Time `xorm:"datetime created notnull 'created_at'"`
→ datetime 是xorm认可的跨库时间类型关键词;
→ created 是xorm内置行为标签,表示插入时自动填当前时间;
→ notnull 强制该字段非空;
→ 'created_at' 用单引号锁定列名为下划线风格,覆盖默认映射器行为。【四个组件缺一不可,顺序可变,但单引号必须存在】
如果去掉单引号,写成 xorm:"datetime created notnull created_at",xorm会把 created_at 当作另一个约束关键词处理,报错“unknown tag created_at”。
这一步操作起来很简单,直接把字段Tag按上述规则拼好就行。











