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

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

Содержание

• Правила валидации (шпаргалка)
• Типичные подводные камни

Правила валидации (шпаргалка)

• type обязателен и должен быть одним из задокументированных значений.
• type: shell требует ровно одного из cmd / argv; service_* требует ровно одного из cmd / argv плюс service.
• type: script требует блок script: в простой форме (path) или фазовой форме (run + опциональные plan / cleanup).
• type: workflow требует непустой steps: и запрещает поля, специфичные для типов (cmd, argv, service, script, workdir и т. д.).
• type: builtin требует cmd: (имя builtin) и отвергает поля, специфичные для других типов (argv, script:, steps:, service, compose_args, workdir / workdir_from, user, mode, runner:).
• У каждого шага workflow ровно одно из command / confirm / parallel; with / continue_on_error допустимы только на command-шагах (и на контейнере блока parallel — см. Параллельные подшаги).
• Имена env-переменных должны быть уникальны по params.*.env, context.*.env, files.*.env и блоку env:.
• File ID должны соответствовать ^[a-zA-Z_][a-zA-Z0-9_]*$.
• Файловые спецификации отвергают конфликтующие поля (например, mkdir вне write, path + candidates, match / sort без glob).
• workdir_from допустим только для service_exec / service_run / daemon.
• compose_args допустим только для service_exec / service_run / daemon.
• mode на service_run должен быть пустым или run.
• notify: true отвергается на type: daemon (ошибка). notify: true на прямом подшаге внутри блока parallel: создаёт info-диагностику; runtime его подавляет.
• Блок args: требует ссылки ${args} в cmd: или argv:. Без неё блок инертен (его prefix / default никогда не применятся), поэтому он отвергается на загрузке, а не игнорируется молча.
• В argv: ${args} должен быть целым элементом. --filter=${args} отвергается: аргументы вставляются отдельными элементами, и встроенный токен никто не переразбивает.
• argv_append_from допустим только для shell / service_exec / service_run, требует argv: и отвергается вместе с cmd: — дописывание вычисленных значений к shell-строке вклеило бы их в текст программы. Он отвергается для type: daemon (пустой вывод означает «пропуск», что для демона читается как молчаливый отказ его запустить) и для любого другого типа (нет вектора аргументов, к которому можно дописывать).
• argv_append_from не должен ссылаться на ${args}. Сквозные аргументы передаются позиционными параметрами и намеренно не видны выражению; ссылайтесь на них из argv:. См. Вычисляемые аргументы.

Типичные подводные камни

• Не шеллите в ./bin/dwe — используйте type: dwe или $DWE_BIN (в скриптах). Любая из этих форм подхватывает запущенный бинарник, даже когда путь сборки меняется.
• Не помещайте секреты в argv — используйте env:, чтобы значения внедрялись через окружение контейнера, а не через командную строку.
• Не переиспользуйте env-имена между источниками — объявление MYSQL_PWD одновременно в params.x.env и env: — ошибка во время загрузки.
• Не пишите в путь без mkdir: true — режим write не создаёт родителей сам по себе.
• Не ожидайте ${...} внутри params.*.default_from / context.*.from — это обычные точечные пути, не шаблонизированные.
• Не запускайте приватную команду напрямую — ссылайтесь на неё из workflow или пайплайна, либо временно переключите private: false для отладки.