Rails带scope校验的first_or_create触发email已存在报错排查

Attendee模型配置了如下邮箱唯一性校验规则：

validates :email, uniqueness: { case_sensitive: false, allow_blank: true, allow_nil: true, scope: :customer_id }

执行业务代码时使用first_or_create!实现查询存在则返回、不存在则创建的逻辑：

attendee = Attendee.where(email: params['email'], customer: customer).first_or_create!

异常表现：当数据库中已存在同时匹配email、customer两个条件的记录时，应用内执行会抛出如下错误，但相同逻辑在Rails控制台中可正常运行：

ActiveRecord::RecordInvalid (Validation failed: Email has already been taken)

两种场景下的SQL查询日志如下：

• 应用运行时生成的SQL日志：

BEGIN
Customer Load (0.9ms)  SELECT "customers".* FROM "customers" WHERE "customers"."id" = $1 LIMIT $2  [["id", 4883], ["LIMIT", 1]]
SELECT 1 AS one FROM "attendees" WHERE LOWER("attendees"."email") = LOWER($1) AND "attendees"."customer_id" = $2 LIMIT $3  [["email", "some@email"], ["customer_id", 4883], ["LIMIT", 1]]

• Rails控制台执行时生成的SQL日志：

Attendee Load (1.2ms)  SELECT "attendees".* FROM "attendees" WHERE "attendees"."email" = $1 AND "attendees"."customer_id" = $2 ORDER BY "attendees"."id" ASC LIMIT $3  [["email", "some@email.com"], ["customer_id", 4883], ["LIMIT", 1]]

核心原因是*first_or_create!的前置查询条件，和后续创建记录时的校验查询条件不一致*：前置查询没命中已有记录，走到创建流程后，校验查询命中了已有记录才抛出错误。控制台执行正常，本质是控制台传入的参数刚好能命中前置查询，没有走到创建流程。
从日志和常见场景看，触发问题的原因按概率排序：

1. 传入参数本身不一致：从贴出的日志就能直接看到，应用场景传入的email参数值是some@email，控制台传入的是some@email.com，参数本身就存在差异。如果业务代码中拿到的params['email']被截断、带不可见字符、编码异常、前后带空格，都会导致精确匹配的前置where查询查不到记录。
2. 模型层对email做了格式化，但查询时用了未格式化的原始值：这是这类问题最高频的坑。多数项目会在模型层重写email= setter，或者加before_validation回调对邮箱做标准化处理，比如去除首尾空格、转成全小写、过滤特殊字符等。但first_or_create!的前置where查询不会走模型的setter和回调，直接用传入的原始值做精确匹配，只要原始值和库里存的标准化值有一点差异，就会查不到记录。等初始化新实例后，setter/回调把email处理成库里的标准值，后续唯一性校验用标准化值做不区分大小写的匹配，自然能查到已存在的记录，抛出校验错误。
3. 默认范围过滤：如果Attendee模型配置了default_scope（比如软删除场景默认过滤已删除记录），要确认前置查询和校验查询的范围一致，不过Rails的uniqueness校验默认会继承default_scope，这个场景概率很低。

1. 先确认参数的真实值：在first_or_create!代码前加日志，打印参数的字节级内容，和数据库中对应customer下的所有email做对比，确认参数是否有空格、截断、不可见字符、编码问题：

# 调试用代码
puts "传入email参数：#{params['email'].inspect}，字节序列：#{params['email'].bytes}"
puts "当前customer下所有已存email：#{Attendee.where(customer: customer).pluck(:email).inspect}"

2. 检查模型层逻辑：翻Attendee模型的代码，找所有对email字段做处理的逻辑，包括自定义setter、before_validation/before_save回调、字段类型转换规则，确认是否存在格式化逻辑。
3. 补全SQL日志：当前贴出的应用日志缺失了first_or_create!本该最先执行的Attendee前置查询语句，把日志级别调到debug，确认前置查询的实际执行条件和返回结果，验证是不是确实没查到记录。
4. 验证格式化逻辑影响：如果存在email格式化逻辑，把传入的email提前做相同的格式化处理再查询，看是否能正常命中已有记录。

1. 统一查询和写入时的email处理逻辑：所有查询场景下，对传入的email参数做和模型层完全一致的标准化处理，保证查询条件和库里存储的值匹配。
2. 优化查询写法：把属性标准化逻辑提前，用find_or_create_by实现逻辑，新建记录的额外属性赋值放在块中，避免查询和实例化用的值不一致：

# 做和模型层完全一致的标准化处理，逻辑如果复用可以抽到模型的类方法里
normalized_email = params['email']&.strip&.downcase
attendee = Attendee.find_or_create_by(customer: customer, email: normalized_email) do |att|
  # 新建记录时才需要执行的其他属性赋值写在这里
end

3. 数据库层加唯一索引兜底：Rails的唯一性校验是应用层逻辑，并发场景下会出现漏判，必须在数据库层加对应的唯一索引，从根本上保证数据唯一性：

# 迁移文件示例，针对不区分大小写的email加唯一索引
add_index :attendees, [:customer_id, "LOWER(email)"], unique: true, name: 'idx_attendees_on_customer_id_lower_email'

内容的提问来源于stack exchange，提问作者wachichornia