Проверка и форматирование кода

Повысьте эффективность процесса разработки, интегрировав популярные линтеры и форматтеры, такие как SQLFluff, sqlfmt, Black и Prettier. Используйте эти мощные инструменты напрямую в Studio IDE, не прерывая рабочий процесс разработки.

Что такое линтеры и форматтеры?

Линтеры анализируют код на наличие ошибок, багов и проблем со стилем, в то время как форматтеры исправляют правила стиля и форматирования. Подробнее о том, когда использовать линтеры или форматтеры, читайте в Часто задаваемых вопросах.

В Studio IDE вы можете выполнять линтинг, автоисправление и форматирование для пяти различных типов файлов:

• SQL: Проверка и исправление с помощью SQLFluff, а также форматирование с помощью sqlfmt
• YAML, Markdown и JSON: Форматирование с помощью Prettier
• Python: Форматирование с помощью Black

Каждый тип файла имеет свои уникальные правила проверки и форматирования. Вы можете настроить процесс проверки, чтобы добавить больше гибкости и улучшить обнаружение проблем и стиля.

По умолчанию IDE использует правила sqlfmt для форматирования вашего кода, что делает его удобным для использования сразу. Однако, если у вас есть файл с именем .sqlfluff в корневом каталоге вашего проекта dbt, IDE будет использовать правила SQLFluff по умолчанию.

Используйте SQLFluff для проверки/форматирования SQL-кода и просматривайте ошибки кода на вкладке Качество кода.

Используйте sqlfmt для форматирования SQL-кода.

Форматируйте файлы YAML, Markdown и JSON с помощью Prettier.

Используйте кнопку Config для выбора инструмента.

Настройте линтинг с помощью собственных правил проверки кода, включая линтинг/оформление по стандарту dbtonic.

Проверка

В Studio IDE вы можете без труда использовать SQLFluff, настраиваемый SQL-линтер, который предупреждает о сложных функциях, ошибках синтаксиса, форматирования и компиляции. Эта интеграция позволяет запускать проверки, исправлять и отображать любые ошибки кода непосредственно в Studio IDE:

• Работает с Jinja и SQL.
• Поставляется со встроенными правилами линтинга. Вы также можете настроить собственные правила линтинга.
• Позволяет включить линтинг с такими опциями, как Lint (отображает ошибки линтинга и рекомендует действия) или Fix (автоматически исправляет ошибки в Studio IDE).
• Предоставляет вкладку Качество кода для просмотра результатов линтинга и форматирования. Некоторые диагностические сообщения редактора также отображаются на вкладке Проблемы.

Особенности линтинга

• Studio IDE выполняет линтинг с помощью движка dbt v1, даже если ваша среда разработки использует канал выпусков v2 Stable. Подробнее см. в разделе Ограничения dbt v2.
• Линтинг не поддерживает эфемерные модели в dbt v1.5 и более ранних версиях. Подробнее см. в разделе Часто задаваемые вопросы.

Включение проверки

Линтинг доступен во всех ветках, включая защищённую основную ветку git. Поскольку Studio IDE не позволяет делать коммиты в защищённую ветку, он предложит зафиксировать эти изменения в новой ветке.

1. Чтобы включить линтинг, откройте файл .sql и нажмите вкладку Качество кода.
2. Нажмите кнопку </> Config в правой части раздела консоли, под Редактором файлов.
3. В диалоговом окне Настройка инструмента проверки качества кода выберите SQLFluff (линтинг & форматирование).
4. Нажмите Сохранить.
5. После сохранения на панели инструментов над консолью (под Редактором файлов) выберите Проверить файл или Проверить и исправить файл:
   • Проверить: Показывает проблемы, обнаруженные при линтинге в Studio IDE, в виде волнистого подчёркивания в Редакторе файлов. Наведите указатель на подчёркнутую проблему, чтобы просмотреть подробности и доступные действия, включая опцию Быстрое исправление для исправления всех или отдельных проблем. После линтинга появится сообщение с результатом. Линтинг не запускается повторно после сохранения. Нажмите Проверить ещё раз, чтобы повторно запустить линтинг.
   • Исправить: Автоматически исправляет ошибки линтинга в Редакторе файлов. После завершения исправления появится сообщение с результатом.
   • Используйте вкладку Качество кода для просмотра результатов линтинга и журналов. Проверяйте вкладку Проблемы на наличие связанных диагностических сообщений редактора.

Используйте кнопку Проверить или Исправить в разделе консоли для линтинга или автоматического исправления кода.

Линтинг нескольких файлов

Вы можете выполнять линтинг нескольких SQL-файлов одновременно в зависимости от того, как вы работаете с dbt. Поведение различается в Studio IDE, dbt v1 и dbt platform CLI.

• Studio IDE: По умолчанию линтинг выполняется для всех изменённых файлов .sql в проекте в текущей ветке. Подробнее см. в разделе Линтинг снимков.

• dbt v1: Не включает встроенный линтер. Для линтинга SQL-файлов в проекте используйте сторонний линтер, например SQLFluff, настроенный на использование шаблонизатора dbt. Вы можете выполнять линтинг нескольких файлов, указав один или несколько путей к файлам или каталогам в качестве аргументов команды.

• dbt platform CLI: Поддерживает те же команды линтинга, что и dbt v1:

  dbt sqlfluff lint [PATHS]... [flags]

  Сообщить об ошибке в коде

  Если путь не указан (например, dbt sqlfluff lint), линтинг выполняется для всех SQL-файлов в проекте.

Настройка проверки

SQLFluff — это настраиваемый SQL линтер, что означает, что вы можете настроить свои собственные правила проверки вместо использования настроек проверки по умолчанию в IDE. Вы можете исключить файлы и каталоги, используя стандартный файл .sqlfluffignore. Узнайте больше о синтаксисе в документации по синтаксису .sqlfluffignore.

Чтобы настроить свои собственные правила проверки:

1. Создайте новый файл в корневом каталоге проекта (родительском каталоге или каталоге верхнего уровня для ваших файлов). Примечание: Корневой каталог проекта — это каталог, в котором находится файл dbt_project.yml.
2. Назовите файл .sqlfluff (обязательно добавьте . перед sqlfluff).
3. Создайте и добавьте свой пользовательский код конфигурации.
4. Сохраните изменения и закоммитьте их.
5. Перезапустите Studio IDE.
6. Протестируйте и приятного линтинга!

Линтинг снапшотов

По умолчанию dbt выполняет линтинг всех изменённых файлов .sql в вашем проекте, включая снапшоты. Snapshots могут быть определены как в YAML, так и в файлах .sql, однако их SQL не подлежит линтингу и может вызывать ошибки в процессе линтинга.

Чтобы SQLFluff не выполнял линтинг файлов снапшотов, добавьте директорию снапшотов в файл .sqlfluffignore (например, snapshots/).

Обратите внимание, что вам необходимо явно исключить снапшоты в файле .sqlfluffignore, поскольку dbt не игнорирует снапшоты автоматически на стороне бэкенда.

Настройка правил линтинга dbtonic

Обратитесь к файлу конфигурации SQLFluff для Jaffle shop для dbt-специфичных (или dbtonic) правил проверки, которые мы используем для наших собственных проектов:

Пример кода конфигурации dbtonic от dbt Labs

[sqlfluff]
templater = dbt
# This change (from Jinja to dbt templater) will make linting slower
# because linting will first compile dbt code into data warehouse code.
runaway_limit = 10
max_line_length = 80
indent_unit = space

[sqlfluff:indentation]
tab_space_size = 4

[sqlfluff:layout:type:comma]
spacing_before = touch
line_position = trailing

[sqlfluff:rules:capitalisation.keywords] 
capitalisation_policy = lower

[sqlfluff:rules:aliasing.table]
aliasing = explicit

[sqlfluff:rules:aliasing.column]
aliasing = explicit

[sqlfluff:rules:aliasing.expression]
allow_scalar = False

[sqlfluff:rules:capitalisation.identifiers]
extended_capitalisation_policy = lower

[sqlfluff:rules:capitalisation.functions]
capitalisation_policy = lower

[sqlfluff:rules:capitalisation.literals]
capitalisation_policy = lower

[sqlfluff:rules:ambiguous.column_references]  # Number in group by
group_by_and_order_by_style = implicit

Сообщить об ошибке в коде

Подробнее о рекомендациях по оформлению см. в разделе Как мы оформляем SQL.

Настройте линтинг с помощью собственных правил проверки кода, включая линтинг/оформление по стандарту dbtonic.

Форматирование

В Studio IDE вы можете форматировать код в соответствии с руководствами по стилю одним нажатием кнопки. Studio IDE интегрируется с такими форматтерами, как sqlfmt, Prettier и Black, для автоматического форматирования кода в файлах пяти типов: SQL, YAML, Markdown, Python и JSON.

• SQL: Форматирование с помощью sqlfmt, который предоставляет единый способ форматирования SQL и Jinja в dbt.
  • Примечание: Пользовательская конфигурация sqlfmt в Studio IDE не поддерживается.
• YAML, Markdown и JSON: Форматирование с помощью Prettier.
• Python: Форматирование с помощью Black.

Интеграции Studio IDE с форматтерами берут на себя ручные задачи, такие как форматирование кода, позволяя вам сосредоточиться на создании качественных моделей данных, совместной работе и достижении значимых результатов.

Форматирование SQL

Чтобы форматировать ваш SQL-код, dbt интегрируется с sqlfmt — это строгий форматтер SQL-запросов, который предлагает единый, однозначный способ форматирования SQL и Jinja.

По умолчанию Studio IDE использует правила sqlfmt для форматирования кода, поэтому кнопка Форматировать доступна и готова к использованию сразу. Однако если в корневом каталоге проекта dbt есть файл с именем .sqlfluff, Studio IDE по умолчанию использует правила SQLFluff.

Форматирование доступно во всех ветках, включая защищённую основную git‑ветку. Поскольку Studio IDE не позволяет делать коммиты напрямую в защищённую ветку, он предложит закоммитить эти изменения в новую ветку.

1. Откройте файл .sql и нажмите вкладку Качество кода.
2. Нажмите кнопку </> Config в правой части консоли.
3. В диалоговом окне Настройка инструмента проверки качества кода выберите sqlfmt (только форматирование).
4. Нажмите Сохранить.
5. После сохранения на панели инструментов над консолью (под Редактором файлов) выберите кнопку Форматировать.
6. Кнопка Format автоматически форматирует ваш код в Редакторе файлов. После автоматического форматирования вы увидите сообщение, подтверждающее результат.

Используйте sqlfmt для форматирования SQL-кода.

Форматирование YAML, Markdown, JSON

Чтобы форматировать код YAML, Markdown или JSON, dbt интегрируется с Prettier — форматировщиком кода с жёстко заданными правилами. Форматирование доступно во всех ветках, включая защищённую основную git-ветку. Поскольку Studio IDE не позволяет выполнять коммиты в защищённую ветку, он предлагает зафиксировать эти изменения в новой ветке.

1. Откройте файл .yml, .md или .json.
2. На панели инструментов над консолью (под Редактором файлов) выберите кнопку Форматировать, чтобы автоматически отформатировать код в Редакторе файлов. Используйте вкладку Качество кода для просмотра результатов форматирования.
3. После автоматического форматирования вы увидите сообщение, подтверждающее результат.

Форматируйте файлы YAML, Markdown и JSON с помощью Prettier.

Вы можете добавить конфигурационный файл для настройки правил форматирования для файлов YAML, Markdown или JSON с помощью Prettier. IDE ищет конфигурационный файл на основе порядка приоритета. Например, сначала она проверяет наличие ключа "prettier" в вашем файле package.json.

Подробнее о порядке приоритетов и настройке файлов см. в документации Prettier. Обратите внимание, файлы .prettierrc.json5, .prettierrc.js и .prettierrc.toml в настоящее время не поддерживаются.

Форматирование Python

Для форматирования вашего Python-кода dbt интегрируется с Black — строгим форматтером кода Python. Форматирование доступно во всех ветках, включая защищённую основную git-ветку. Поскольку Studio IDE не позволяет выполнять коммиты в защищённую ветку, он предлагает закоммитить эти изменения в новую ветку.

1. Откройте файл .py.
2. На панели инструментов над консолью (под Редактором файлов) выберите кнопку Форматировать, чтобы автоматически отформатировать код в Редакторе файлов.
3. После автоматического форматирования вы увидите сообщение, подтверждающее результат.

Форматируйте файлы Python с помощью Black.

Часто задаваемые вопросы

 Когда следует использовать SQLFluff, а когда sqlfmt?

SQLFluff и sqlfmt — это оба инструмента, используемые для форматирования SQL-кода, но некоторые различия могут сделать один из них предпочтительным в зависимости от вашего случая использования.

SQLFluff — это линтер и форматтер SQL-кода. Это означает, что он анализирует ваш код, чтобы выявить потенциальные проблемы и баги, и следует стандартам кодирования. Он также форматирует ваш код в соответствии с набором правил, которые настраиваемы, чтобы обеспечить согласованные практики кодирования. Вы также можете использовать SQLFluff, чтобы ваш SQL-код был хорошо отформатирован и следовал лучшим практикам стилизации.

sqlfmt — это форматтер SQL-кода. Это означает, что он автоматически форматирует ваш SQL-код в соответствии с набором правил форматирования, которые не настраиваемы. Он сосредоточен исключительно на внешнем виде и макете кода, что помогает обеспечить согласованное отступление, разрывы строк и пробелы. sqlfmt не анализирует ваш код на наличие ошибок или багов и не рассматривает проблемы кодирования за пределами форматирования кода.

Вы можете использовать либо SQLFluff, либо sqlfmt в зависимости от ваших предпочтений и того, что лучше всего подходит для вас:

• Используйте SQLFluff, чтобы ваш код был проверен и отформатирован (то есть проанализируйте и исправьте ваш код на наличие ошибок/багов и отформатируйте ваш стиль). Это позволяет вам гибкость в настройке собственных правил.

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

 Можно ли размещать файлы `.sqlfluff` во вложенных каталогах?

Для обеспечения оптимального качества кода, его единообразия и согласованности стилей настоятельно рекомендуется иметь один основной файл конфигурации .sqlfluff в корневой папке проекта. Наличие нескольких файлов может привести к использованию разных стилей SQL в проекте.

Однако вы можете настроить и включить дополнительный дочерний конфигурационный файл .sqlfluff в определенных подпапках вашего проекта dbt.

Вложив файл .sqlfluff в подпапку, SQLFluff будет применять правила, определенные в конфигурационном файле этой подпапки, к любым файлам, находящимся в ней. Правила, указанные в родительском файле .sqlfluff, будут использоваться для всех других файлов и папок за пределами подпапки. Этот иерархический подход позволяет использовать индивидуальные правила проверки, сохраняя при этом согласованность во всем проекте. Обратитесь к документации SQLFluff для получения дополнительной информации.

 Можно ли запускать команды SQLFluff из терминала?

В настоящее время запуск команд SQLFluff из терминала не поддерживается.

 Что следует учитывать при использовании линтинга dbt?

В настоящее время Studio IDE может выполнять линтинг или исправление файлов до определённого размера и уровня сложности. Если вы попытаетесь проверить или исправить слишком большие файлы, обработка которых на серверной стороне dbt занимает более 60 секунд, вы увидите ошибку 'Не удалось завершить линтинг этого файла'.

Чтобы избежать этого, разбейте вашу модель на более мелкие модели (файлы), чтобы они были менее сложными для проверки или исправления. Обратите внимание, что проверка проще, чем исправление, поэтому могут быть случаи, когда файл можно проверить, но не исправить.

Связанные документы

• Пользовательский интерфейс
• Сочетания клавиш
• SQL‑линтинг в CI‑задачах

Нашли ошибку?

Создать GitHub Issue