Hanami是Ruby生态中一款以简洁和模块化著称的Web框架，它的Action设计尤其强调显式配置。在使用Hanami构建RESTful API时，我们经常需要明确限定某个接口只接受特定的HTTP方法，例如删除操作只允许DELETE，登录接口只允许POST。Hanami::Action::Payload中的AllowedMethods正是为此而生的机制，它让Action能够声明自己支持的HTTP方法集合，并在收到不支持的请求时返回规范的405 Method Not Allowed响应。本文将从配置方式、内部原理和实践建议三个层面详细展开。
一、AllowedMethods的基本配置与使用场景
在Hanami中，Action类可以通过类方法声明允许的HTTP方法。这种声明会被框架收集并用于请求分发阶段的方法校验。一个典型的用法如下：
class UsersController < Hanami::Action
# 只允许DELETE方法访问该Action
def self.allowed_methods
[:delete]
end
def handle(req, res)
user = UserRepository.new.find(req.params[:id])
return res.status = 404 unless user
UserRepository.new.delete(user.id)
res.status = 204
end
end
这段代码展示了AllowedMethods最直接的价值：当客户端尝试用GET或POST访问这个Action时，框架不会执行handle方法，而是直接返回405状态码。这比在方法内部手动判断req.env['REQUEST_METHOD']要干净得多，也避免了业务逻辑与协议校验代码混在一起。
使用场景方面，AllowedMethods特别适合以下几类情况。第一是严格语义化的REST接口，比如删除资源必须用DELETE、更新必须用PATCH，不允许通过GET触发有副作用的操作。第二是安全加固，某些老旧网关或浏览器扩展可能会以非预期的方法发送请求，显式白名单能挡掉这类异常流量。第三是团队协作中统一约定，将允许的方法写在Action头部，阅读代码的人一眼就能看出接口的访问契约，不需要翻路由文件去确认。
需要注意的一点是，如果你使用的是Hanami的路由层（Hanami::Router），路由本身已经按方法做了区分，例如delete '/users/:id', to: 'users.destroy'这条路由天然只匹配DELETE请求。那么AllowedMethods还有存在的必要吗？答案是肯定的。路由层的匹配是分散在路由表中的，而Action内的声明是自描述的；当Action被多个路由复用、或者被挂载到其他Rack应用中时，Action内部的校验就成了最后一道防线。两者配合使用，语义最清晰。
二、内部原理：框架如何校验方法并生成响应
理解AllowedModules的内部处理流程，有助于你在遇到诡异问题时快速定位。Hanami的Action在接收到请求后，会经历参数解析、方法校验、调用业务逻辑三个阶段。方法校验发生在业务逻辑之前，框架会对比request.request_method与声明的白名单，不匹配则中断后续流程。
下面是一个简化版的实现思路，模拟了框架内部的处理方式：
module AllowedMethods
def self.included(action)
action.extend ClassMethods
end
module ClassMethods
def allowed_methods(*methods)
methods.empty? ? @allowed_methods : @allowed_methods = methods.map(&:to_s).map(&:upcase)
end
end
def call(env)
req = Rack::Request.new(env)
allowed = self.class.allowed_methods
if allowed && !allowed.include?(req.request_method)
[405, {'Allow' => allowed.join(', ')}, ['Method Not Allowed']]
else
handle(req, build_response(env))
end
end
end
这段代码揭示了两个容易被忽略的细节。第一个是405响应中携带的Allow响应头，按照HTTP规范，返回405时应当通过Allow头告知客户端该资源支持哪些方法，Hanami会自动补全这个头，很多HTTP客户端（例如浏览器开发者工具、curl的-v模式）会依赖它给出提示。第二个细节是HEAD方法的特殊处理，按照RFC规范，任何允许GET的资源都应该隐式允许HEAD，Hanami在判断时会把HEAD视为GET的等价方法，这一点如果你自己手写校验很容易遗漏。
另一个值得关注的点是OPTIONS请求。一些跨域场景下，浏览器会先发OPTIONS预检请求。如果你的Action白名单里没有包含OPTIONS，预检请求可能被405拒绝，导致前端跨域调用失败。解决办法要么在Action中加入OPTIONS，要么在中间件层（如Rack::Cors）提前处理预检请求，不让它穿透到Action层。这是实践中非常高频的一个踩坑点。
三、实践建议与常见问题排查
第一个建议是保持路由声明与Action声明的一致性。如果路由写的是post而Action白名单是[:put]，请求会在Action层被拒绝，日志中会出现路由匹配成功但返回405的奇怪现象，排查起来相当费时。建议在CI中加一个简单的约定测试，遍历路由表，断言每个路由的方法都包含在对应Action的白名单中。
第二个建议是定制405响应体。默认的405响应通常是纯文本，对API来说不够友好。你可以在Action中重写错误处理钩子，返回JSON格式的错误信息：
class ApiAction < Hanami::Action
def handle_exception(exception)
if exception.is_a?(Hanami::Action::MethodNotAllowedError)
res.status = 405
res.body = {error: 'method_not_allowed', message: '请求方法不被支持'}.to_json
else
super
end
end
end
第三个建议是善用405做接口探测的防护。有些安全扫描器会遍历各种HTTP方法（包括TRACE、TRACK这类历史遗留方法）来探测服务器漏洞。通过显式白名单，这些请求会被统一挡在405，你可以在日志监控中对高频405的来源IP设置告警，把它当作异常流量的信号源之一。
排查相关问题时，推荐两个技巧。一是用curl直接构造带任意方法的请求，观察返回的状态码和Allow头：curl -X TRACE -v http://127.0.0.1:2300/users/1，从输出中可以直接看到框架识别到的方法和返回的处理结果。二是检查Hanami版本差异，不同版本中Action基类的配置DSL略有不同，早期版本通过configure块设置，新版本改为类方法形式，升级依赖时记得同步调整写法。
总结来说，AllowedMethods看起来只是一个小特性，但它体现了Hanami显式优于隐式的设计哲学。正确使用它，不仅能让接口行为更符合HTTP语义，还能在安全和可维护性上获得额外收益。建议在项目初期就把Action方法白名单的约定固化下来，配合路由声明形成双保险，让接口契约在代码层面一目了然。
HanamiAllowedMethodsHTTP方法修改时间：2026-09-07 20:44:41