Hanami 3.0 正式发布：全面绽放

背景

Hanami 是一个以"清晰、模块化、可成长"为核心理念的 Ruby Web 框架。自诞生之初，它就试图走出一条不同于 Rails 的道路，强调显式依赖注入、Slice（切片）架构以及更可控的框架行为。经过多个大版本的迭代，Hanami 逐渐在 Ruby 社区中积累了一批追求代码可维护性和架构清晰度的开发者。Hanami 3.0 是该框架的一次重大版本更新，标志着其功能集趋于完整，同时在性能和开发者体验上实现了显著跃升。

核心内容

Hanami 3.0 以"In Full Bloom"（全面盛开）为主题，带来了三大全新功能——邮件发送（Mailers）、国际化（i18n）和 Minitest 测试支持——并在性能、日志、资源监控、请求体解析和视图层等多个维度进行了深度优化。

一等公民的邮件发送（First-class Mailers）

Hanami 应用现在内置了完整的邮件发送能力。Mailer 类作为独立对象，与 Action、View、Operation 并列，可以通过 Deps mixin 注入到任何需要的地方。调用 .deliver 方法时，Mailer 会根据传入参数准备邮件头部并渲染邮件正文模板，模板体系完全复用了 Hanami 的视图层。

Mailer 支持多种投递方式。开箱即用的 SMTP 投递只需配置环境变量即可工作；测试环境下邮件会累积在内存中供开发者检查。如果需要自定义投递方式，Hanami Mailer 提供了干净的接口和钩子机制，允许将投递选项贯穿整个 Mailer 链路，充分利用邮件服务商的特殊功能。

值得注意的是，Hanami Mailer 本身也可以作为独立 gem 在非 Hanami 项目中使用。底层依赖了成熟的 mail gem 处理所有底层邮件操作。

内置国际化（Built-in i18n）

Hanami 3.0 将 i18n 直接集成到框架中。引入 i18n gem 后，Hanami 会在应用和每个 Slice 中自动搭建自包含的翻译后端，translate 和 localize 辅助方法在 Action 和 View 中随处可用。

翻译文件存放在应用或 Slice 的 config/i18n/ 目录下，采用 YAML 格式。在视图中可以直接调用 t(".title") 这样的辅助方法，在 Action 中同样如此。对于其他场景，只需通过 Deps mixin 注入 "i18n" 组件即可使用。

本地化（Localization）方面，localize 方法会根据当前 locale 格式化日期和时间，并内置了英语的合理默认值。与 Hanami 一贯的设计哲学一致，i18n 开箱即用、配置极简，同时也提供了丰富的自定义选项。

正式支持 Minitest

Hanami 一直以来默认提供 RSpec 测试环境。3.0 版本终于补齐了 Minitest 支持，在生成应用时可以通过 --test=minitest 参数选择测试框架。选择 Minitest 后会获得一套完整且与 RSpec 同等完善的测试配置，无需开发者自行搭建。Minitest 本身随 Ruby 自带，Hanami 将其正式纳入框架生态。

默认更快（Faster by Default）

Hanami 3.0 在性能上实现了显著提升，且这些提升对现有应用完全免费——无需修改任何代码即可享受。

核心变化在于组件默认记忆化（memoization）。此前每次需要组件时都会重新构建，现在每个组件在容器中只解析一次，之后直接复用。以一个解析了九个组件并渲染视图的 Action 为例，3.0 版本相比 2.3 版本：每次请求的内存分配减少为原来的 1/14，HTTP 吞吐量提升近 3 倍（进程内测量接近 9 倍）。尾延迟（p99）从 89ms 骤降至 4ms，原因是每次请求的分配抖动和 GC 暂停被消除。

框架最热路径也获得了针对性优化：

• Hanami Action：改为预先快照 Action 配置，而非每次请求重新计算。最小 Action 的内存分配从 88 次降至 17 次（减少 80%），独立运行速度提升约 3.7 倍。
• Hanami View：同样采用配置快照，且默认不再装饰 exposures。最小渲染的内存分配从 100 次降至 42 次，速度提升约 2.9 倍。

更清晰、更有用的日志

Hanami 3.0 对日志系统进行了全面改进，覆盖开发和生产环境：

• 开发环境下日志默认启用彩色输出。
• SQL 语句格式化后与请求日志风格一致，若引入 rouge gem 还会进行语法高亮。
• SQL 语句的日志级别从 :info 调整为 :debug，生产环境日志更安静，可通过 config.db.log_level 调节。
• 新增 HANAMI_LOG_LEVEL 环境变量，优先级高于应用类中的配置。
• 底层保证了一致的 Logger 接口（即使配置了第三方替代方案），始终支持结构化日志（通过关键字参数传递）和标签日志（通过 #tagged 块）。

更流畅的资源监控

hanami assets watch 命令现在能更好地跟上开发节奏：自动检测新增和删除的入口点（entry points），响应图片、字体等静态资源的变化。此前这些操作都需要重启监控进程，现在则无缝衔接，不打断开发心流。

同时，Hanami 发布了一份规范文档，定义了任何资源打包工具如何干净地接入 Hanami。Hanami 自带的打包工具基于 esbuild，但框架并不希望开发者被锁定于此，鼓励社区带来自己喜欢的打包工具。

请求体解析进入 Hanami Action

Hanami 的请求体解析逻辑从中间件层移到了 Hanami Action 内部，现在由 formats 配置驱动。Action 只解析它明确接受的格式，且该配置可以与其他内容协商设置放在一起统一管理。

multipart 表单和 JSON 的解析器开箱即用。如果需要其他格式，可以自行注册：

formats.register(:custom, "application/custom", parser: ->(body, env) { ... })

更简洁的视图：默认不装饰 Exposures

View 的 exposures 现在默认不进行装饰（undecorated）。模板接收到的就是被暴露的原始对象，除非显式要求装饰。这是一个更可预测的默认行为，在不需要装饰时避免了额外的工作开销。

关键要点

• Hanami 3.0 是功能集趋于完整的里程碑版本，补齐了邮件发送、国际化和 Minitest 三大核心能力。
• 组件默认记忆化是本次性能飞跃的关键，每次请求的内存分配减少至 1/14，HTTP 吞吐量提升近 3 倍，尾延迟从 89ms 降至 4ms。
• 零代码改动即可享受性能提升，所有优化对现有应用完全透明。
• Mailer 支持 SMTP 开箱即用，同时提供自定义投递方式的扩展接口，且可作为独立 gem 使用。
• i18n 内置到框架，应用和每个 Slice 自动获得自包含的翻译后端，translate 和 localize 随处可用。
• Minitest 获得与 RSpec 同等的官方支持，生成应用时可通过 --test=minitest 选择。
• 日志系统全面升级：彩色输出、SQL 语法高亮、日志级别可调、支持结构化日志和标签日志。
• 资源监控更智能，自动响应入口点和静态资源变化