PaperTrail 5 升级警告:"user_for_paper_trail is present, but whodunnit has not been set" 的完整解决方案与原理剖析
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
注意两点:
- 它只在
PaperTrail.request.enabled?为真时设置值。若请求被paper_trail_enabled_for_controller关闭(返回false),whodunnit不会被赋值; - 写入的目标是
PaperTrail.request(基于 request.rb 中的RequestStore实现的请求级存储),而非全局变量,因此不同请求之间不会串值。
谁在真正消费这个值
当模型发生变更时,PaperTrail 的三个事件类会在构造 Version 记录时读取 whodunnit:
- create 事件:lib/paper_trail/events/create.rb
- destroy 事件:lib/paper_trail/events/destroy.rb
- update 事件:lib/paper_trail/events/update.rb
三处均为 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_whodunnitcontroller 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 会静默地不再被记录——这正是那条升级警告存在的意义。