generating-sorbet

Sorbet RBI 生成技能

在单独的 .rbi 文件中生成或更新 Sorbet 类型签名。支持从头完整生成，也支持针对单个已更改文件进行部分更新。当你无法或不应修改原始 Ruby 源代码时（例如处理 gem、生成的代码或旧版代码库），可以使用 RBI 文件。

说明

生成 Sorbet RBI 签名时，务必遵循以下步骤。

复制此检查清单并跟踪进度：

Sorbet RBI Generation Progress:
- [ ] Step 1: Analyze the Ruby source
- [ ] Step 2: Generate RBI files
- [ ] Step 3: Eliminate `T.untyped` in signatures
- [ ] Step 4: Review and refine signatures
- [ ] Step 5: Validate signatures with Sorbet

规则

• 你绝不能运行项目的 Ruby 代码。
• 你绝不能使用 T.untyped。请推断出合适的类型。
• 你绝不能使用 T.unsafe——它会完全绕过类型检查。
• 你绝不能使用 T.cast——它会在未经验证的情况下强制指定类型。
• 如果有任何内容不清楚，你必须要求用户提供更多详情。
• 如果项目包含 Gemfile，你必须在每条命令前加上 bundle exec。
• 方法签名必须使用 sig { } 块语法。
• 在使用 sig 前，必须在类／模块中添加 extend T::Sig。
• RBI 文件中绝不能添加方法体——只能包含签名和空方法定义。
• RBI 文件必须放在 ./rbi 目录中。
• 处理多个文件时，必须使用跟踪文件，确保不遗漏任何文件。

多文件处理

处理多个 Ruby 文件时，请创建跟踪文件，确保涵盖所有文件：

1. 创建跟踪文件 .sorbet-rbi-generation-todo.tmp：

   [ ] app/models/user.rb
   [ ] app/models/post.rb
   [ ] app/services/auth_service.rb
   

2. 逐个处理文件：

   • 取下一个待处理的 [ ] 条目
   • 完成该文件的全部步骤（1–5）
   • 标记为已处理 [x]
   • 保存跟踪文件
   • 继续处理下一个待处理条目

3. 清理：处理完所有文件后，删除跟踪文件：

   rm .sorbet-rbi-generation-todo.tmp
   

如果处理中断，可以通过跟踪文件从上次停止的位置继续。

1. 分析 Ruby 源代码

务必执行此步骤。

阅读并理解 Ruby 源文件：

• 识别所有类、模块、方法、常量和实例变量。
• 记录继承关系、模块包含情况，以及基于元编程定义的内容。
• 记录可见性修饰符：public、private、protected。
• 记录泛型类的类型参数。

2. 生成 RBI 文件

务必执行此步骤。

1. 确定正确的 RBI 目录：

   将 RBI 文件放在 ./rbi 目录中。Sorbet 会读取此位置的所有 .rbi 文件。

   以下代码需要 RBI 文件进行描述，因为 Sorbet 无法通过静态分析理解：

   • Gem 定义
   • 使用 define_method 或 method_missing 创建的方法
   • 来自 const_get／const_set 的常量
   • 通过 extend 添加的动态祖先
   • DSL 生成的方法（Rails、ActiveRecord 等）

2. 使用类型声明创建 RBI 文件：

   # typed: strict
   

3. 在每个类／模块中添加 extend T::Sig：

   class MyClass
     extend T::Sig
   end
   

4. 添加带签名的方法桩（不含方法体）：

示例——Ruby 源代码：

class User
  attr_reader :name, :age

  def initialize(name, age)
    @name = name
    @age = age
  end

  def greet(greeting)
    "#{greeting}, #{@name}!"
  end
end

示例——RBI 文件（rbi/user.rbi）：

# typed: strict

class User
  extend T::Sig

  sig { returns(String) }
  attr_reader :name

  sig { returns(Integer) }
  attr_reader :age

  sig { params(name: String, age: Integer).void }
  def initialize(name, age); end

  sig { params(greeting: String).returns(String) }
  def greet(greeting); end
end

• RBI 文件应镜像原有结构，但只包含签名和空方法桩
• 完整的 Sorbet RBI 语法指南请参阅 syntax.md

3. 在签名中消除 T.untyped

务必执行此步骤。

• 检查所有签名，并用合适的类型替换 T.untyped。
• 使用代码上下文、方法调用和测试来推断类型。
• 只有在无法确定类型时，才将 T.untyped 作为最后手段。

4. 检查并完善签名

务必执行此步骤。

• 确认签名正确、一致且完整。
• 删除不必要的 T.untyped 类型。
• 确保所有方法和属性都有签名。
• 确认类层次结构和模块包含关系与源代码一致。
• 修复所有错误，并重复检查，直至签名正确。

5. 使用 Sorbet 验证签名

始终执行此步骤。

运行 Sorbet 类型检查器以验证签名：

srb tc

或使用 bundle：

bundle exec srb tc

此检查包括：

• 签名语法是否正确
• 类型是否一致
• 方法参数/返回类型是否匹配
• 类/模块结构是否与源代码匹配

修复报告的所有错误，并重复此过程，直到验证通过。

参考资料

• syntax.md - Sorbet RBI 语法指南
• references/ - 来自 stripe-ruby 的真实 RBI 示例
• Sorbet RBI 文档 - RBI 官方文档