根本原因是主键生成策略脱离数据库自增且未保障全局唯一：Beego ORM不强制生成主键，手动设ID（如缺陷UUID、时间戳拼接、分库重复ID等）导致数据库级主键冲突；需精准识别错误、用Raw SQL实现Upsert，并改用自增、Snowflake或Google UUID等可靠主键方案。
Beego 项目在分布式环境下插入数据报主键重复（如 Duplicate entry 'xxx' for key 'PRIMARY'），根本原因不是 Beego ORM 本身的问题，而是主键生成策略脱离了数据库自增能力，又没做好全局唯一性保障。
为什么 Beego ORM 会触发主键冲突？
Beego ORM 默认不强制接管主键生成——它只是把结构体字段映射到 SQL 插入语句里。一旦你手动设置了 Id 字段（比如用 uuid.NewV4().String() 但逻辑有缺陷，或从上游传入未校验的 ID），而该值已存在，就会直接抛出数据库级约束异常（MySQL 是 SQLIntegrityConstraintViolationException，PostgreSQL 是 unique_violation）。常见诱因包括：
- 多个服务实例并发调用同一段生成 UUID 的代码，且未加锁或未用线程安全方式（如
sync.Once初始化随机源） - 使用时间戳+机器码拼接 ID，在高并发下毫秒级重复（尤其容器重启后时钟回拨）
- 分库分表场景下，ShardingSphere 或自定义路由规则未对主键字段做全局唯一分片，导致不同库中插入相同 ID
- 测试环境误将生产 dump 数据导入，又未清空或重置自增起点，后续插入撞上已有主键
Beego 中捕获并区分主键冲突异常
不能只 catch error，要精准识别是主键冲突而非其他数据库错误。Beego ORM 执行失败时返回的是标准 error，需向下断言为 *mysql.MySQLError（MySQL）或检查错误消息内容：
- MySQL：判断
err.Error()是否包含"Duplicate entry"和"for key 'PRIMARY'" - PostgreSQL：匹配
"unique_violation"或"duplicate key value violates unique constraint" - 避免用模糊关键词如
"Duplicate"——它也可能来自唯一索引（uk_email），和主键冲突处理策略不同
示例片段：
_, err := o.Insert(&user)
if err != nil {
if strings.Contains(err.Error(), "Duplicate entry") && strings.Contains(err.Error(), "PRIMARY") {
// 主键冲突，走降级逻辑
return errors.New("id already exists")
}
}
用 Beego ORM 实现安全插入（Upsert）
Beego ORM 本身不原生支持 INSERT ON DUPLICATE KEY UPDATE 或 ON CONFLICT DO NOTHING，但可通过 Raw SQL 绕过：
- MySQL：用
o.Raw("INSERT IGNORE INTO ...").Exec()跳过冲突行 - PostgreSQL：用
o.Raw("INSERT INTO ... ON CONFLICT (id) DO NOTHING").Exec() - 若需更新已有记录，MySQL 写
INSERT ... ON DUPLICATE KEY UPDATE name=VALUES(name)；PostgreSQL 用ON CONFLICT (id) DO UPDATE SET name=EXCLUDED.name - 注意：Raw SQL 会绕过 Beego ORM 的结构体自动映射，参数需手动占位（
?）并传入切片
真正防冲突：别依赖 Beego，改主键生成机制
ORM 层再怎么兜底也只是补救。关键得让主键天生唯一：
- 放弃手动生成字符串 ID，改用数据库自增（
int64类型 +orm:"auto"标签），Beego ORM 会自动忽略插入时赋的值 - 必须用字符串 ID 时，用
github.com/google/uuid的uuid.NewString()（v1.20+ 推荐），它基于硬件地址+时间+随机数，碰撞概率可忽略 - 分库分表场景下，禁用任何本地生成逻辑，统一走 Snowflake 服务（如 Twitter 的
id-worker改写版）或 ShardingSphere 的SNOWFLAKE分布式主键策略 - 所有插入前加唯一索引（不只是主键），比如
email、phone字段建UNIQUE INDEX，让数据库在最底层拦住业务层漏掉的重复
最容易被忽略的一点：Beego 的 Insert 操作默认不开启事务。如果前置校验（SELECT）和插入（INSERT）之间没有事务包裹，高并发下仍可能被其他请求插队——所以校验+插入必须包在 o.Begin() / o.Commit() 里，或者直接信任数据库唯一约束，删掉校验步骤，靠异常兜底更可靠。
