gruf 从 1.x 升级到 2.x：Breaking Changes 与迁移指南

gruf 从 1.x 升级到 2.x：Breaking Changes 与迁移指南

【免费下载链接】grufgRPC Ruby Framework项目地址: https://gitcode.com/gh_mirrors/gr/gruf

如果你正在使用gruf搭建 gRPC 服务，那么gruf 1.x 升级 2.x一定是你绕不开的一道坎。gruf 是目前 Ruby 生态中最流行的gRPC Ruby 框架，它对 gRPC 官方库做了大量封装，让 Ruby 和 Rails 开发者能够快速构建高性能的 gRPC 服务。但 2.0 版本是一次"推倒重来"式的架构重构：Service 变成了 Controller、Hooks 被 Interceptor 全面替代、请求对象从无到有……本文将为你系统梳理 gruf 2.x 的Breaking Changes，并给出一份可直接照做的迁移指南，帮你少踩坑、平滑升级。

一、为什么说 gruf 2.x 是一次"大换血"？

gruf 2.0 放弃了 1.x 时代"Service + Hook"的简单模型，转而采用线程安全的 Controller 模型，核心目标是解决两个痛点：一是多线程并发下服务实例状态混乱的问题，二是为服务端与客户端的拦截能力提供统一、可组合的扩展点。

从 2.0 到现在的 2.22，gruf 陆续加入了客户端错误子类、内置 gRPC Health Check、Zeitwerk 自动加载、Rails 代码热重载等能力，但 2.0 确立的架构骨架至今未变。因此，理解 2.0 的变化就等于理解了整个 2.x 系列。

二、核心变化速览：一张表看懂 1.x 与 2.x 的区别

三、Breaking Change 1：Service 变身 Controller，方法签名彻底改变

这是迁移中改动量最大的一步。1.x 时代，你的业务代码直接写在 gRPC 生成的 Service 子类里，方法签名形如def get_thing(req, call)；而 2.x 要求你新建一个继承自Gruf::Controllers::Base的 Controller，并用bind将它绑定到对应的 gRPC Service 上：

• 方法不再接收req、call两个参数，所有请求数据都通过request对象访问；
• fail!方法不再需要传入req和call，直接调用即可抛出对应的 gRPC BadStatus；
• Controller 与 Service 分离后天然线程安全，多个并发请求可以复用同一个 Controller 实例。

具体实现可参考 lib/gruf/controllers/base.rb 中的Base类，以及 spec/pb/thing_controller.rb 中的示例控制器。

四、Breaking Change 2：全新 Request 对象，请求数据都在这里

2.x 新增的Gruf::Controllers::Request是迁移中最需要熟悉的新概念。它把一次 gRPC 调用的全部信息打包，并提供以下常用方法：

• request.message：请求的 protobuf 消息，替代原来第一个req参数；
• request.messages：客户端流式调用时，通过块逐个取出流消息；
• request.active_call：当前GRPC::ActiveCall的受控视图，可读取 metadata；
• request.method_key/request.method_name：当前执行的方法与"服务.方法"统计名；
• request.service_key：适合打点统计的服务名；
• request.context：一个可在拦截器之间传递信息的共享哈希。

值得注意的是，request.messages对普通一元调用会返回单元素数组，对客户端流会逐个 yield，对双向流则返回消息对象——不同 RPC 类型的处理方式完全不同，迁移流式接口时要格外小心。详细实现见 lib/gruf/controllers/request.rb。

五、Breaking Change 3：Hooks 退役，拦截器（Interceptor）时代来临

1.x 中你可能同时维护着认证 Hook、埋点 Hook、通用 Hook 三类扩展，它们签名各不相同、执行顺序混乱。2.x 将这一切统一为Gruf::Interceptors::ServerInterceptor：

• 拦截器的call方法没有参数，内部必须yield以放行后续调用；
• 所有拦截器按 FIFO 顺序执行，你可以完全掌控认证、埋点、日志的先后关系；
• 拦截器统一获得request、error、options三个注入对象，见 lib/gruf/interceptors/base.rb 与 lib/gruf/interceptors/server_interceptor.rb。

注册方式也变了：既可以在Gruf::Server.new后调用server.add_interceptor(MyInterceptor, key: 'value')，也可以统一写入配置Gruf.configure { |c| c.interceptors.use(MyInterceptor, key: 'value') }。另外，埋点场景建议使用 2.x 新增的Gruf::Interceptors::Timer工具类，它返回带elapsed（毫秒）和successful?的结果对象，比手动计时精准得多。

六、Breaking Change 4：Server 启动方式与配置项变化

Gruf::Server的初始化方式在 2.x 中有两处明显变化：

• 不再支持在构造函数中传入 services，必须通过server.add_service(SomeService)逐个注册（服务启动后禁止再改动，避免线程问题）；
• Gruf.servers_path配置项被移除，改用Gruf.controllers_path（默认app/rpc），见 lib/gruf/server.rb。

此外，服务器默认开启了 gRPC Health Check（可通过配置关闭），并对RESOURCE_EXHAUSTED、UNIMPLEMENTED等事件提供了event_listener_proc监听回调。

七、Breaking Change 5：客户端错误处理全面升级

从 2.5.0 起，gruf 客户端抛出的异常从单一的Gruf::Client::Error细化为与 gRPC 状态码一一对应的子类，例如Gruf::Client::Errors::InvalidArgument、NotFound、Unauthenticated、Internal等，完整清单见 lib/gruf/client/errors.rb。

两点迁移提示：一是兼容性有保障，原有异常仍可通过.error拿到原始 gRPC 异常；二是注意行为变化——客户端边界现在会捕获StandardError和GRPC::Core::CallError，统一包装为Internal错误，如果你之前依赖"底层异常直接抛出"，升级后需要调整捕获逻辑。

八、升级后还要注意这些坑（2.12 / 2.15 / 2.19）

主版本迁移完成后，还有几个高频踩坑点值得提前了解：

• 2.12 拦截顺序修正：早期版本拦截器实际按 FILO 执行（与文档不符），2.12 修正为 FIFO。如果你曾依赖后注册先执行的顺序，需要调整注册顺序；
• 2.15 Zeitwerk 自动加载：控制器目录必须符合"文件名与类名一致"的命名规范，否则启动时报加载错误。例如MyService::Rpc::ProductsController必须放在app/rpc/my_service/rpc/products_controller.rb；
• 2.19 停止支持 Ruby 2.x：升级前请确认 Ruby 版本在 3.x 及以上；
• 2.20 ActiveRecord 拦截器简化：Gruf::Interceptors::ActiveRecord::ConnectionReset移除了手动establish_connection的逻辑，数据库连接重置由 gRPC 回调自动处理。

九、gruf 2.x 迁移检查清单

结语：升级虽痛，收益长久

从 1.x 迁移到 gruf 2.x 确实需要投入精力，但换来的是线程安全、统一拦截体系、精细化客户端错误处理和持续更新的官方维护（当前 2.x 已支持 Ruby 4.x，详见 CHANGELOG.md）。完整的官方迁移说明可以查阅项目根目录的 UPGRADING.md，其中对每个大版本变化都有详细描述。按照本文的检查清单一步步走，相信你能平稳完成这次 gruf 升级迁移，让 gRPC 服务跑得更稳、更可控。🚀

【免费下载链接】grufgRPC Ruby Framework项目地址: https://gitcode.com/gh_mirrors/gr/gruf