PaperTrail 5 升级警告:"user_for_paper_trail is present, but whodunnit has not been set" 的完整解决方案与原理剖析

原创2026-10-14 23:50:401,655 阅读
文章标签:后端

PaperTrail 5 升级警告:"user_for_paper_trail is present, but whodunnit has not been set" 的完整解决方案与原理剖析

导读:从 PaperTrail 5 开始,升级后的 Rails 应用会在控制台看到一条关于 whodunnit 未设置("not setting whodunnit")的警告。本文以官方文档 doc/warning_about_not_setting_whodunnit.md 为核心,给出"继续追踪操作者 / 彻底关闭追踪 / 仅消除警告"三种处理路径,并结合本仓库源码说明警告的触发逻辑、set_paper_trail_whodunnit 的底层实现,以及 PaperTrail 为何不再自动注入该回调。读完你将能准确判断自己属于哪种场景,并写出可复制的控制器配置。

警告长什么样

将 PaperTrail 升级到 5.x 后,如果满足以下两个条件,Rails 应用启动或请求过程中就会打印一条警告:

  • 你的控制器中存在 user_for_paper_trail 方法(或它可被解析);
  • 但 whodunnit 一直没有被真正设置。

警告原文如下:

user_for_paper_trail is present, but whodunnit has not been set. PaperTrail no longer adds the set_paper_trail_whodunnit before_action for you. Please add this before_action to your ApplicationController to continue recording whodunnit.

翻译过来即:"检测到 user_for_paper_trail 存在,但 whodunnit 尚未被设置。PaperTrail 不再替你添加 set_paper_trail_whodunnit 这个 before_action,请自行在 ApplicationController 中添加它,以继续记录 whodunnit。"

whodunnit 是 PaperTrail 版本记录中"谁造成了这次变更"的字段。在安装生成器生成的 create_versions.rb.erb 模板里可以看到,versions 表默认就包含 t.string :whodunnit 列,记录每次 create / update / destroy 事件的操作者标识(通常为 current_user 的 id 或用户名)。

场景一:你仍然想记录"谁改的"

如果你希望继续追踪每次变更的操作者,做法非常简单:在 ApplicationController 中添加一行 before_action:

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  before_action :set_paper_trail_whodunnit
end

这也是官方 README 中 4.a 章节 推荐的做法。添加之后,每个请求进入控制器时都会执行该回调,把 user_for_paper_trail 的返回值写入 PaperTrail.request.whodunnit,随后该值会被持久化到对应 Version 记录的 whodunnit 列。

默认取的是谁

回调内部的取值逻辑定义在 lib/paper_trail/frameworks/rails/controller.rb:

def user_for_paper_trail
  return unless defined?(current_user)
  current_user.try(:id) || current_user
end

也就是说,默认情况下 PaperTrail 会调用控制器里的 current_user 方法,优先取 current_user.id;若没有 id 方法则退回为 current_user 本身。如果你的项目用的不是 current_user(比如 current_member、current_admin),覆盖这个方法即可,README 也给出了示例:

class ApplicationController
  def user_for_paper_trail
    logged_in? ? current_member.id : 'Public user'  # or whatever
  end
end

回调如何把值写入请求

set_paper_trail_whodunnit 的实现同样位于 controller.rb:

def set_paper_trail_whodunnit
  if ::PaperTrail.request.enabled?
    ::PaperTrail.request.whodunnit = user_for_paper_trail
  end
end

注意两点:

  1. 它只在 PaperTrail.request.enabled? 为真时设置值。若请求被 paper_trail_enabled_for_controller 关闭(返回 false),whodunnit 不会被赋值;
  2. 写入的目标是 PaperTrail.request(基于 request.rb 中的 RequestStore 实现的请求级存储),而非全局变量,因此不同请求之间不会串值。

谁在真正消费这个值

当模型发生变更时,PaperTrail 的三个事件类会在构造 Version 记录时读取 whodunnit:

三处均为 whodunnit: PaperTrail.request.whodunnit。这解释了为什么"只定义 user_for_paper_trail 而不添加 before_action"时 whodunnit 是空的——方法存在但从未被回调调用,请求存储里自然没有值,于是升级后触发警告。

场景二:你不再需要记录操作者

如果你从业务上就不打算记录 whodunnit,可以让警告消失的同时彻底关闭追踪:覆盖 user_for_paper_trail 让它返回 nil。

# app/controllers/application_controller.rb
def user_for_paper_trail
  nil # disable whodunnit tracking
end

这样即使 set_paper_trail_whodunnit 被(或未被)调用,写入请求存储的值也是 nil,最终落到 versions.whodunnit 列的就是空值,相当于关掉了这项追踪。

场景三:你只是想让警告消失

如果 whodunnit 既不需要、你又不想改控制器代码,直接**升级到 PaperTrail 6(PT 6)**即可。

依据在本仓库的 CHANGELOG.md:

Removed the warn_about_not_setting_whodunnit controller method.

PaperTrail 6 移除了 warn_about_not_setting_whodunnit 这个控制器方法,而该警告正是由它发出的。因此升级后警告不会再出现;只有极少数显式调用 skip_after_action :warn_about_not_setting_whodunnit 的应用会受影响(升级后该方法不存在,需要移除这行跳过声明)。

为什么 PaperTrail 5 起不再自动添加这个回调

这是最值得理解的一个设计决策。官方文档给出的理由是:让你自己控制回调的执行顺序。

从源码可以看到,PaperTrail 注入到 ActionController::Base 的扩展(通过 lib/paper_trail/frameworks/rails/railtie.rb 的 ActiveSupport.on_load(:action_controller) 完成 include)现在只自动添加两个 before_action,见 controller.rb:

def self.included(controller)
  controller.before_action(
    :set_paper_trail_enabled_for_controller,
    :set_paper_trail_controller_info
  )
end

set_paper_trail_whodunnit 不在其中——这就是"PaperTrail 不再替你添加"的直接证据。同样在 CHANGELOG.md 的 PT 5 发布说明中也明确记载了这一破坏性变更。

回调顺序为什么重要:仓库里的真实例子

本仓库的 dummy app 提供了一个极具说服力的案例,见 spec/dummy_app/app/controllers/application_controller.rb:

class ApplicationController < ActionController::Base
  protect_from_forgery

  # Some applications and libraries modify `current_user`. Their changes need
  # to be reflected in `whodunnit`, so the `set_paper_trail_whodunnit` below
  # must happen after this.
  before_action :modify_current_user

  # PT used to add this callback automatically. Now people are required to add
  # it themselves, like this, allowing them to control the order of callbacks.
  # The `modify_current_user` callback above shows why this control is useful.
  before_action :set_paper_trail_whodunnit

场景还原:有些应用或第三方库会在请求早期修改 current_user(例如中间件把匿名用户替换成真实登录用户)。如果 PaperTrail 把 set_paper_trail_whodunnit 固定在自动注入的位置,它可能早于 modify_current_user 执行,于是 whodunnit 记录到的是"修改前的用户",与真实操作者不符。

由你自己在 ApplicationController 里声明 before_action :set_paper_trail_whodunnit,就可以把它放在任何依赖回调之后,确保 whodunnit 捕获到最终的用户身份。dummy app 中 modify_current_user 把 @current_user 设为 User.new(id: 153),对应的控制器测试 spec/controllers/widgets_controller_spec.rb 断言 widget.versions.last.whodunnit.to_i == 153,正是这个顺序生效后的结果。

补充:whodunnit 的进阶用法与相关 API

在解决升级警告之后,如果你继续使用 whodunnit 追踪,以下 API 也值得了解(均有 README 与源码依据):

  • 直接赋值:在 console、迁移或服务类中可手动设置 PaperTrail.request.whodunnit = 'Andy Stewart',随后创建的 version 会记录该值(README.md);
  • 赋值 Proc(惰性求值):whodunnit= 接受 Proc,直到真正插入 Version 记录前才求值(见 request.rb 的 whodunnit 读取逻辑)。README 明确提示这种方式难以排查,不建议常规使用(README.md);
  • 临时设置:用块形式 PaperTrail.request(whodunnit: 'Dorian Marié') do ... end,块结束后自动恢复原值(README.md);
  • 读取 side 信息:version.whodunnit 与 version.terminator(别名 version_author)返回"谁把对象改成了当前状态";version.paper_trail_originator 返回"谁让对象进入当前版本所呈现的状态"(lib/paper_trail/version_concern.rb 与 README.md)。

小结:三种场景速查

你的诉求 操作 依据
继续记录操作者 ApplicationController 中添加 before_action :set_paper_trail_whodunnit README.md
彻底关闭 whodunnit 追踪 覆盖 user_for_paper_trail 返回 nil doc/warning_about_not_setting_whodunnit.md
仅消除警告 升级到 PaperTrail 6 CHANGELOG.md

无论选择哪条路径,核心结论一致:从 PaperTrail 5 开始,set_paper_trail_whodunnit 的注册权完全交还给了开发者。这既是对回调顺序控制的让渡,也意味着升级后需要主动检查你的 ApplicationController,否则 whodunnit 会静默地不再被记录——这正是那条升级警告存在的意义。

登录后查看全文
paper_trail