Hanami是Ruby语言下一个以简洁和模块化著称的Web框架，它将控制器层抽象为一个个独立的Action类。在处理HTTP请求时，除了路径匹配之外，请求方法（如GET、POST、PUT、DELETE等）的合法性校验同样是不可忽视的一环。如果一个接口只允许POST访问，却收到了一个PATCH请求，服务端应当明确拒绝并告知客户端原因，而不是默默执行或抛出异常。Hanami通过AllowedMethods相关机制提供了这套校验能力，本文将围绕其原理与用法展开详细说明。
一、为什么需要验证HTTP方法的合法性
HTTP协议定义了一系列标准方法，其中GET、HEAD、POST、PUT、DELETE、PATCH、OPTIONS是RESTful接口中最常用的几种。每一种方法在语义上都有明确约定：GET用于读取资源且应当无副作用，POST用于创建资源，PUT和PATCH用于更新资源，DELETE用于删除资源。如果服务端不校验方法而一股脑处理，会带来两类问题。
第一类是安全性问题。某些遗留代码可能习惯于用GET请求携带修改操作，这会导致爬虫或预取工具在无意间触发数据变更。第二类是语义混乱问题。当客户端使用了不被支持的方法时，若服务端返回200或者500，客户端会误以为操作成功或服务出错，而按照HTTP规范，正确的做法是返回405 Method Not Allowed，并在Allow响应头中列出该资源实际支持的方法。Hanami的校验机制正是为了让这类边界情况的处理变得标准化、自动化。
从框架设计角度看，方法校验应该发生在Action执行之前，属于一种前置过滤。Hanami将其收敛到统一的位置处理，开发者只需声明允许的方法，无需在每个Action里手写判断逻辑，这大大降低了遗漏的风险。
二、AllowedMethods校验机制的原理剖析
Hanami的Action体系中，请求进入Action实例后，会经过一系列中间处理步骤，方法校验便是其中之一。其核心思路是维护一个允许方法的白名单，当请求的REQUEST_METHOD不在白名单内时，直接中断后续处理流程，构造一个405响应返回，而不会执行业务代码。这个过程可以用下面的伪代码概括：
# 模拟 AllowedMethods 校验的内部逻辑
def call(env)
request_method = env["REQUEST_METHOD"]
if allowed_methods.include?(request_method)
# 方法合法，继续执行Action的业务逻辑
super
else
# 方法不合法，直接返回405，并携带Allow头
headers = { "Allow" => allowed_methods.join(", ") }
[405, headers, ["Method Not Allowed"]]
end
end
def allowed_methods
@allowed_methods ||= %w[GET POST]
end
注意响应中的Allow头部，它列出了当前资源真正支持的方法集合。这是HTTP规范（RFC 7231）对405状态码的配套要求，良好的API实现应当遵守。客户端收到405后，可以根据Allow头决定换用正确的方法重试。
另一个值得关注的细节是大小写问题。按照标准，方法名是区分大小写的，且全部为大写字母。Rack环境下取到的REQUEST_METHOD通常已经是标准形式，但在某些代理或自定义客户端的场景下可能出现小写方法名。如果需要兼容，可以在比较之前统一做upcase处理，不过更推荐的做法是直接拒绝非标准形式，以保持接口的严格性。
三、在Hanami Action中配置允许的方法
在实际项目中，为Action声明允许的方法非常直观。以一个用户资源接口为例，我们希望列表接口只接受GET，创建接口只接受POST：
# app/actions/users/index.rb
module Users
class Index < MyApp::Action
# 该Action仅接受GET请求
accepted_params [:page, :per_page]
def handle(req, res)
users = UserRepository.new.paginate(req.params[:page])
res.render view, users: users
end
end
end
需要说明的是，方法的允许列表通常与路由定义配合使用。在Hanami的路由配置中，为某个路径指定方法本身就形成了一层约束：
# config/routes.rb Hanami.app.routes do get "/users", to: "users.index" post "/users", to: "users.create" get "/users/:id", to: "users.show" patch "/users/:id", to: "users.update" delete "/users/:id", to: "users.destroy" end
当请求方法与路由声明不匹配时，框架层面就会拦截。但如果你的Action可能被多个路由复用，或者你希望通过继承体系给一组Action统一加上方法约束，就需要在Action内部显式声明白名单。可以在基类中定义一个类方法供子类覆盖：
# app/actions/my_app/action.rb 内添加
module MyApp
class Action < Hanami::Action
def self.allowed_methods(*methods)
if methods.empty?
@allowed_methods || %w[GET HEAD]
else
@allowed_methods = methods.map(&:to_s).map(&:upcase)
end
end
private
def verify_allowed_method(req)
unless self.class.allowed_methods.include?(req.env["REQUEST_METHOD"])
halt 405, "Method Not Allowed"
end
end
end
end
在before回调中调用verify_allowed_method，即可确保任何业务逻辑执行前先完成校验。这种写法的好处是集中管控：管理后台的基类可以收紧到GET和POST，而API基类可以放开全部标准方法。
四、自定义405响应与客户端体验优化
默认的405响应往往只有一句干巴巴的错误信息。对于面向开发者的API来说，返回结构化的错误体会更友好。可以在halt之前构造JSON响应：
def verify_allowed_method(req, res)
allowed = self.class.allowed_methods
unless allowed.include?(req.env["REQUEST_METHOD"])
res.status = 405
res.headers["Allow"] = allowed.join(", ")
res.body = JSON.generate(
error: "method_not_allowed",
message: "本接口仅支持 #{allowed.join(', ')} 方法",
allowed: allowed
)
halt
end
end
这样做有三个好处：客户端可以程序化地读取allowed字段、错误码具有可读性、日志系统也能根据error字段快速过滤。对于前后端分离的项目，规范的错误结构能显著减少联调时的沟通成本。
此外建议在API文档中明确每个端点支持的方法，并配合自动化测试覆盖405场景。测试示例如下：
# spec/web/users/create_spec.rb
RSpec.describe "POST /users" do
it "拒绝GET请求并返回405" do
get "/users"
expect(last_response.status).to eq(405)
expect(last_response.headers["Allow"]).to include("POST")
end
end
将这类用例纳入CI流程后，一旦有人误改了路由或方法声明，测试会立刻暴露问题，避免线上出现方法约束失效的隐患。
五、常见误区与注意事项
第一个常见误区是认为OPTIONS和HEAD请求无关紧要。实际上，浏览器发起跨域请求前的预检（preflight）就是OPTIONS方法，如果接口没有正确处理它，跨域调用会直接失败。HEAD则常被健康检查工具使用，Hanami在声明GET支持时通常也会顺带接受HEAD，因为HEAD语义上等同于无响应体的GET。
第二个误区是混淆405与404。路径不存在应返回404，路径存在但方法不支持应返回405。有些框架在不匹配时会统一返回404，这会让客户端无法区分是自己拼错了路径还是用错了方法，调试时非常折磨人。Hanami的路由与方法校验配合良好，只要配置得当就能返回正确的状态码。
最后一点是性能考量。方法校验本身是字符串比较，开销几乎可以忽略，不需要为了性能去绕过它。相反，尽早拦截非法请求可以避免后续参数解析和业务逻辑的执行，对高并发场景反而是节省资源的做法。将方法白名单、参数校验、权限校验按顺序排列在请求处理管道的前端，是构建健壮Web应用的通用最佳实践。
Hanami框架AllowedMethodsHTTP方法验证修改时间：2026-08-31 23:51:12