在Hanami框架构建的Web应用中，内容协商是一个核心环节。当客户端发起请求时，框架会读取HTTP头中的Accept字段，尝试解析出客户端期望的媒体类型及其优先级。如果Accept头格式不符合RFC 7231规范，例如出现了无法识别的字符、质量值q超出0到1的范围，或者媒体类型之间缺少逗号分隔，Hanami底层的内容协商组件便会构造并抛出Hanami::Action::Mime::Type::Accept::Parse::Error::Message这一特定异常。该异常不同于普通的参数错误，它专门指向MIME类型解析阶段的失败，并携带了导致解析中断的位置与原因描述。
理解Hanami中Accept头解析异常的产生机制
Hanami的Action在处理请求前，会经由Hanami::Action::Mime模块进行媒体类型匹配。其内部调用了专门的解析器，将Accept头字符串拆分为多个媒体范围（media range）与质量因子。解析器采用状态机方式逐字符扫描，当遇到非法令牌（token）或结构断裂时，便实例化Hanami::Action::Mime::Type::Accept::Parse::Error::Message。这个异常对象并非简单的字符串，它通常包含原始头片段、出错偏移量以及人类可读的消息模板，方便开发者定位是哪一段Accept值出了问题。
从框架源码角度看，该异常继承自标准错误体系，但被放置在特定的命名空间下，意味着它属于内容协商子系统的内部契约。很多初学者在日志中看到这一长串类名时会误以为是配置缺失，实际上它几乎总是由客户端请求不合规引起。比如在微服务间调用时，若某一方手动拼接Accept头却未正确编码斜杠或分号，就会触发此错误。理解这一点，有助于我们区分服务端Bug与客户端输入问题，从而采取不同的响应策略。
另一个容易被忽视的点是，Hanami默认并不会将此类解析异常转换为HTTP状态码，而是让其冒泡至应用服务器层。在开发环境，这表现为堆栈跟踪；在生产环境，若未捕获则可能返回500错误，这并不符合HTTP语义，因为解析失败本质属于客户端请求不可满足，应归为406 Not Acceptable。因此，明确异常来源是设计正确处理逻辑的前提。
在Action层拦截并转换错误消息为合规响应
最直观的处理方式是在业务Action的基类中覆写异常处理逻辑。Hanami的Action提供了handle_exception类方法或实例层面的 rescue 机制，我们可以针对Hanami::Action::Mime::Type::Accept::Parse::Error::Message进行精确捕获。捕获后，不再将原始错误消息直接输出，而是提取其中的偏移与原因，组装为JSON或纯文本的错误主体，并设置响应状态码为406。
如下示例展示了一个基础Action如何重写异常钩子。代码中我们避免了暴露内部类名，仅向客户端说明Accept头无法解析及大致位置，这既遵循了最小信息暴露原则，也符合API友好性。注意在pre代码块中，所有标签符号均做了转义，以客观展示源码结构。
class BaseAction < Hanami::Action
def handle_exception(response, exception)
if exception.is_a?(Hanami::Action::Mime::Type::Accept::Parse::Error::Message)
response.status = 406
response.body = {
error: 'invalid_accept_header',
message: 'The Accept header could not be parsed',
detail: exception.message
}.to_json
else
super
end
end
end
class Articles::Index < BaseAction
def handle(req, res)
# 正常业务逻辑，若Accept头非法，基类已拦截
res.body = 'ok'
end
end
这种方式的优势在于每个Action自动继承处理能力，且错误消息格式统一。缺点是若项目中有大量非继承自有统一基类的Action，则需重复配置。此外，在响应体中我们建议不要将完整的异常类名回传，因为那属于框架实现细节，客户端无需感知具体是Hanami的哪一个深层模块报错。
借助中间件实现全局解析错误的集中处理
当希望将所有内容协商错误从业务代码中彻底解耦时，编写一个Rack中间件是更优雅的方案。中间件位于Hanami应用之前，可以捕获下游抛出的Hanami::Action::Mime::Type::Accept::Parse::Error::Message，并直接构造Rack兼容的三元组响应。这样做让Action保持纯净，只关心领域逻辑，而协议层的错误由基础设施层统一消化。
以下中间件示例演示了如何在call方法中包裹@app.call(env)。一旦捕获目标异常，便返回[406, {'Content-Type' => 'application/json'}, [错误体]]。我们把原始消息中的换行剔除，防止响应体被破坏，同时记录日志供运维排查。这种结构在网关或API边缘服务中尤为常见。
class AcceptParseErrorMiddleware
def initialize(app)
@app = app
end
def call(env)
@app.call(env)
rescue Hanami::Action::Mime::Type::Accept::Parse::Error::Message => e
message = e.message.gsub("n", ' ')
[
406,
{ 'Content-Type' => 'application/json' },
[{ error: 'bad_accept', info: message }.to_json]
]
end
end
# 在config.ru或应用装配处
# use AcceptParseErrorMiddleware
对比Action层处理，中间件方案具备全局性和低侵入性，不会因个别Action遗漏基类而漏捕异常。不过它也要求团队理解Rack协议，且错误响应难以针对单个接口做差异化文案。实践中，可将两者结合：中间件做兜底，特定Action做增强提示。无论哪种路径，核心目标都是将Hanami抛出的深层解析异常转化为语义正确、信息适度的HTTP响应，从而提升系统对非法请求的包容度与专业性。
HanamiAccept_headererror_handling修改时间：2026-08-14 17:39:28