Sorbet: типизация в Ruby — практическое руководство и примеры

Sorbet типизация в Ruby — инструмент, который помогает сделать привычный динамический код более предсказуемым без отказа от гибкости языка. В этой статье я расскажу, как Sorbet работает, какие приёмы стоит использовать, с какими проблемами можно столкнуться и как внедрять типы по‑шагам, не разрушив рабочий процесс команды.

Кратко о том, что такое Sorbet и почему он появился

Sorbet — это набор инструментов от Stripe для статического и частично динамического анализа типов в Ruby. Он состоит из статического чекера и runtime‑библиотеки, которая позволяет проверять и приводить типы в рантайме там, где это нужно.

Идея проста: сохранить удобство Ruby, но упростить рефакторинг и отлов ошибок на ранних стадиях. Для крупных кодовых баз это часто означает меньше неожиданных регрессий и более понятные контракты между компонентами.

Как это работает: директивы, сигнатуры и сдвиг ответственности

В каждом файле Sorbet начинает работу с директивы в первой строке вида # typed: . Эта пометка задаёт, насколько строго Sorbet будет анализировать файл. Дальше для методов и классов используются сигнатуры — специальные объявления с помощью T::Sig.

Типы указываются явно: параметры, возвращаемое значение, структурированные коллекции и nullable‑типы. Сигнатуры пишутся прямо в коде, они понятны человеку и инструменту.

# typed: true
class Greeter
  extend T::Sig

  sig { params(name: String).returns(String) }
  def greet(name)
    "Hello, #{name}"
  end
end

Уровни строгости

Уровень строгости влияет на то, насколько Sorbet будет жаловаться на отсутствие аннотаций и на потенциально небезопасные конструкции. Ниже — краткая таблица для ориентира.

Уровень	Короткое описание
ignore	Sorbet полностью игнорирует файл.
false	Файл отмечен, но проверяется с минимальной строгостью.
true	Обычная проверка — Sorbet ожидает подписи у публичных методов.
strict	Строже: больше гарантий о типах внутри файла.
strong	Максимальная строгая проверка, рекомендуемый режим для критичных частей.

Типы, конструкции и полезные приёмы

Sorbet поддерживает простые скалярные типы, сложные коллекции и композиции типов. Часто используемые конструкции пригодны для реальных приложений и помогают выразить намерения автора кода.

Основные элементы, которые встречаются в повседневной работе: T.nilable, T.any, T::Array, T::Hash, T.untyped, T.let и T.cast. Также в наборе есть утилиты для описания структур данных и перечислений.

sig { params(ids: T::Array[Integer]).returns(T::Array[String]) }
def fetch_names(ids)
  ids.map { |id| "user_#{id}" }
end

sig { params(value: T.nilable(String)).returns(String) }
def normalized(value)
  value || ""
end

T.untyped полезен там, где тип неизвестен или слишком затратен для описания. T.let применяется для приведения и фиксации типа переменной в момент её создания; T.cast — для явного приведения, когда вы уверены в типе, но Sorbet не может вывести это автоматически.

Структуры и вспомогательные механизмы

T::Struct позволяет компактно описать неизменяемые структуры данных с валидацией типов. T::Enum пригодится для явных наборов значений. Для DSL и абстрактных базовых классов есть T::Helpers.

class Point < T::Struct
  const :x, Integer
  const :y, Integer
end

class State < T::Enum
  enums do
    New = new
    Running = new
    Finished = new
  end
end

Интеграция Sorbet в проект: минимальный практический план

Внедрение Sorbet лучше выполнять по этапам, чтобы не поглотить команду техническим долгом и не получить десятки нерешённых предупреждений сразу.

Добавьте gem ‘sorbet’ и ‘sorbet-runtime’ в проект, запустите srb init для базовой настройки.
Сгенерируйте RBI‑шаблоны для зависимостей и стандартной библиотеки (утилиты в sorbet помогают автоматизировать этот шаг).
Запустите srb tc — это статический анализ; исправляйте критичные ошибки по приоритету.
Переходите от # typed: false к более строгим файлам по мере добавления сигнатур, а не сразу ко всему коду.
Используйте T.untyped и «песочницы» в местах, где типы пока не достигают желаемого уровня.

Подводные камни и практические советы

Sorbet не волшебство: он улучшает предсказуемость, но требует дисциплины и времени. Частые источники трений — метапрограммирование, динамическая генерация методов и тесная интеграция с Rails, где многие сигнатуры приходится описывать вручную или генерировать в RBI.

Ниже — список типичных проблем и способов их смягчить:

Метапрограммирование. Решение — писать RBI для динамически созданных методов или избегать генерации, когда это возможно.
Большое количество T.untyped. Ставьте небольшие цели: локально заменяйте untyped на точные типы там, где это даёт ценность.
Производительность при использовании sorbet-runtime. Подключайте runtime‑проверки выборочно, ориентируясь на критичные области.
Поддержка библиотек. Регулярно обновляйте сгенерированные RBI и добавляйте недостающие подписи для внешних гемов.

Мой опыт: что сработало в реальном проекте

Я внедрял типизацию в средний Rails‑проект с несколькими сотнями моделей и большим количеством сервисов. Начали с инициализации и автоматической генерации RBI для гемов. Это снизило шум ошибок от внешних библиотек и дало спокойную базу для дальнейшей работы.

Затем мы выбрали несколько критичных областей: платежную логику и обработку вебхуков — и постепенно переводили их в строгие файлы. Это принесло реальное сокращение багов при рефакторинге, особенно в коде, где данные преобразуются между форматами.

Главный урок: не пытайтесь аннотировать всю кодовую базу сразу. Маленькие победы в важных модулях дают видимый эффект и повышают мотивацию команды.

Sorbet типизация в Ruby: как добавить уверенность к динамическому коду