Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Функции и помощники Sprig

Шаблонизатор Aggrega подключает библиотеку функций Sprig v3, а также собственные помощники Aggrega (optional и capitalizedWords) к каждому шаблону Go, который вычисляет рендерер, и заменяет index из Go версией, которая останавливает работу на ключе, отсутствующем в карте. Авторам, которые пишут valuesMapping: для Recipe, injectMapping: для FeatureRecipe или любую другую шаблонную поверхность, вычисляемую рендерером, доступен полный набор помощников Sprig наряду со встроенными функциями Go text/template и полями контекста времени выполнения, описанными в template-context-contract.md.

🔴 Понимайте «вычисляемую рендерером» буквально, как границу области: одна поверхность для авторов лежит за её пределами. Структурированная координата source: разрешается, чтобы зафиксировать артефакт, на который она указывает, и это разрешение не является проходом рендеринга: оно регистрирует собственные помощники Aggrega и ничего больше, поэтому вызов Sprig в поле source: или в записи locals:, которую это поле читает, останавливает загрузку. Запись, которую не читает ни одно поле source:, вычисляется только при рендеринге, с полным набором. Разрешение координаты определяет, что будет зафиксировано, а не создаёт артефакт, поэтому набор функций для него намеренно уже — см. errors/fatal-halts.md, раздел «Resolving a source: coordinate registers a narrower function set (Разрешение координаты регистрирует более узкий набор функций)», где описаны остановка и переносимая форма, которую следует использовать вместо этого.

Набор Sprig регистрируется отдельно для интерполяции параметров, а на поверхностях шаблонов значений рендерера — вместе с собственными вспомогательными функциями Aggrega.

Что подключено

Sprig v3 открывает доступ ко всему своему набору вспомогательных функций — примерно 200 функций в перечисленных ниже категориях. На этой странице категории описаны кратко, с наиболее распространёнными функциями каждой; основной справочник по отдельным функциям — исходная документация Sprig.

  • Строки — upper, lower, title, trim, trimAll, trimPrefix, trimSuffix, replace, contains, hasPrefix, hasSuffix, substr, quote, squote, cat, indent, nindent, repeat, функции преобразования регистра (snakecase, camelcase, kebabcase), функции сокращения (abbrev, abbrevboth, trunc), функции контрольных сумм (sha1sum, sha256sum, sha512sum, adler32sum), toString.
  • Списки — list, tuple, first, last, rest, initial, append/push, prepend, concat, reverse, uniq, without, has, slice, chunk, join, splitList, split, splitn, sortAlpha, compact.
  • Словари — dict, get, set, unset, hasKey, keys, values, pick, omit, pluck, merge, mergeOverwrite, dig, deepCopy.
  • Математика — add, sub, mul, div, mod, add1, min, max, ceil, floor, round, а также десятичные варианты с суффиксом f (addf, subf, mulf, divf, minf, maxf).
  • Преобразование — int, int64, float64, atoi, toString, toDecimal, seq, until, untilStep.
  • Кодирование — b64enc, b64dec, b32enc, b32dec, toJson, toPrettyJson, toRawJson, fromJson, а также JSON-варианты с префиксом must, которые сообщают об ошибках декодирования, а не молча возвращают нулевое значение.
  • Проверки типов — typeOf, typeIs, typeIsLike, kindOf, kindIs, deepEqual, empty.
  • Значения по умолчанию и управление потоком — default, coalesce, all, any, ternary, fail (вызывает ошибку шаблона с произвольным сообщением — стандартный способ прервать рендеринг с защитным сообщением).
  • Регулярные выражения — regexMatch, regexFind, regexFindAll, regexReplaceAll, regexReplaceAllLiteral, regexSplit, regexQuoteMeta, а также строгие варианты с префиксом must.
  • Пути — base, dir, clean, ext, isAbs (в стиле Unix); osBase, osClean, osDir, osExt, osIsAbs (с учётом ОС).
  • SemVer — semver, semverCompare.
  • URL — urlParse, urlJoin.
  • Даты — ago, date, dateInZone, dateModify, duration, durationRound, htmlDate, htmlDateInZone, now, toDate, unixEpoch.

Оговорка о детерминированности

Aggrega гарантирует побайтно идентичный вывод для побайтно идентичного ввода. Часть функций Sprig читает внешнее состояние и нарушает эту гарантию при вызове из шаблона. Авторам следует избегать следующих функций в шаблонах, которые участвуют в формировании отрисовываемых артефактов:

  • Чтение системных часов — now, date, dateInZone, dateModify, htmlDate, htmlDateInZone, ago при вызове без зафиксированного опорного времени.
  • Генераторы случайных значений — randAlpha, randAlphaNum, randAscii, randNumeric, randBytes, randInt, uuidv4.
  • Чтение окружения — env, expandenv (читают переменные окружения процесса, которые различаются на рабочих станциях операторов и в CI-раннерах).
  • Сетевое разрешение имён — getHostByName.

Движок не блокирует эти функции: они входят в набор Sprig v3. Дисциплину отказа от них в шаблонах, участвующих в отрисовке, поддерживают рецензенты и гарантия детерминированного вывода, на которую опираются авторы и каталог стандартной библиотеки.

Числа в шаблоне значений

Число, записанное автором, доходит до шаблона значений как число. Целое число является integer и выводится целым: 1000000 выводится как 1000000. Любое другое число выводится в кратчайшей точной десятичной форме, никогда в экспоненциальной: записанное 0.0000001 выводится как 0.0000001, а записанное 1e21 — как 1000000000000000000000, независимо от того, пишет ли шаблон значение напрямую или превращает его в текст с помощью toString, quote, printf "%v" или toJson. Число, которое возвращает математическая функция, — mulf, float64, round и подобные им, — является собственным значением этой функции и выводится в её собственной форме, которая для очень малого или очень большого значения экспоненциальная: для записанного 0.0000001 выражение {{ mulf .values.ratio 1 }} выводит 1e-07.

Сравнения — eq, ne, lt, le, gt и ge — читают два числа по значению, каким бы видом ни было представлено каждое, поэтому записанное автором целое сравнивается с десятичным числом, записанным в шаблоне, и 3 равно 3.0:

{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true
{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → true

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

{{ eq .values.port "8080" }} # halts: cannot compare a number with text
{{ eq .values.port 8080 }} # .values.port = 8080 → true
{{ eq (toString .values.port) "8080" }} # .values.port = 8080 → true

Эта остановка — A value template failed while it ran (Шаблон значений завершился сбоем во время выполнения). Утверждение читает записанное автором число так же; см. Числа на этой поверхности.

Наличие и пустота — два разных вопроса

Шаблон задаёт о значении один из двух вопросов, и у каждого вопроса свои вспомогательные функции.

  • Записал ли это автор? hasKey и optional отвечают по наличию. Ключ, записанный автором, присутствует, что бы он ни содержал, — включая 0, "" и false, — и отсутствует только ключ, который автор опустил.
  • Пусто ли это? default, with, if и empty отвечают по пустоте. 0, "", false, пустой список, пустая карта и отсутствующее значение там считаются пустыми, как и в Helm.
.values.replicashasKey .values "replicas"optional .values "replicas" 1.values.replicas | default 1if .values.replicas
отсутствуетfalse11false
0true01false
3true33true

Значение, которое может законно быть 0, "" или false, — нулевое число реплик, нулевой тайм-аут, выключенный флаг, — проверяется через hasKey или optional, чтобы 0 автора дошёл до вывода как 0. default, with и if подходят для значения, пустая форма которого сама по себе ничего не означает и где «пусто» и «не записано» можно считать одним и тем же. Читайте каждый ключ в шаблоне одним способом: ключ, который шаблон также читает как путь через точку, считается присутствующим, как описано в разделе об ограничении optional.

Вспомогательные функции Aggrega

optional — значение по умолчанию с учётом наличия ключа

optional <map> <key> <fallback> возвращает значение по ключу <key> в <map>, если ключ присутствует, иначе возвращает <fallback>. В отличие от default из Sprig, optional различает «ключ отсутствует» и «ключ присутствует с нулевым, пустым или ложным значением».

Сигнатура принимает карту и ключ отдельными аргументами, потому что значение, переданное через оператор | шаблонов Go, теряет доступ к родительской карте. Без родительской карты в области видимости проверить наличие ключа невозможно.

У проверки наличия есть одно ограничение, и исходит оно от шаблона, а не от вспомогательной функции: шаблон значений читает отсутствующий ключ как пустоту, подставляя пустое значение для каждого отсутствующего ключа, который шаблон называет точечным путём и читает как значение. Поэтому шаблон, который читает один ключ и через optional, и как такой путь, находит этот ключ присутствующим и пустым и получает пустое значение, а не значение по умолчанию. Читайте ключ в шаблоне одним способом — и оба ответа совпадут.

# Present and non-zero: returns 3
{{ optional .infra `replicas` 1 }} # .infra.replicas = 3 → 3
# Absent: returns the fallback
{{ optional .infra `replicas` 1 }} # .infra.replicas unset → 1
# Present but authored zero: returns 0 (the discriminator)
{{ optional .infra `replicas` 1 }} # .infra.replicas = 0 → 0

Последний случай — это различие, которое default из Sprig провести не может. {{ .infra.replicas | default 1 }} возвращает 1 независимо от того, задан ли replicas как 0 или опущен, — смешение, которое мешает законным сценариям масштабирования до нуля, отказа от повторов, отсутствия тайм-аута и ложных флагов.

Соглашение о кавычках для ключа: предпочитайте обратные кавычки. Шаблоны Go принимают для аргумента-ключа строковые литералы как в двойных кавычках ("replicas"), так и в обратных (`replicas`); при вычислении шаблона оба дают одну и ту же строку. В примерах каталога и документации единообразно используется форма с обратными кавычками, поскольку она безопасна для YAML в любом контексте кавычек. Ключ в двойных кавычках внутри YAML-скаляра в двойных кавычках обрывает строку YAML посреди шаблона:

# BROKEN — the inner " closes the outer YAML string:
service_port: "{{ optional .infra "port" 8080 }}"
# WORKS — backticks are not a YAML escape character:
service_port: "{{ optional .infra `port` 8080 }}"

Когда шаблон находится внутри блочного скаляра YAML (форма |) или является скаляром без кавычек, обе формы отображаются правильно. Когда шаблон встроен в YAML-скаляр в двойных кавычках (шаблон field: "{{ ... }}", где значение поля является шаблоном), обратные кавычки обязательны. Единое соглашение (всегда обратные кавычки) полностью исключает ловушку с кавычками YAML.

Когда предпочесть optional, а не default. Используйте optional, когда поле может законно быть нулевым, пустым или ложным и автору каталога нужно отличать «автор это не задал» от «автор задал ложное значение». Используйте default, когда смешение допустимо (например, строковые поля, где пустое значение недопустимо; числовые поля, где ноль недопустим).

Доступность по поверхностям. optional зарегистрирована на каждой поверхности, которую вычисляет рендерер: поверхностях шаблонов значений (valuesMapping в Recipe, injectMapping в FeatureRecipe, provides, pipeline.with, тело Workload), в вычислителе утверждений и в шаблонах путей (directory: / subDirectory: на границах Release). На поверхности шаблонов путей отличается не набор функций, а политика отсутствующих ключей: шаблон пути считает отсутствующий ключ ошибкой, а не пустым значением, потому что незаметно пустой сегмент пути даёт сломанную структуру файловой системы, которая обнаруживается только после сборки. optional читает ключ до срабатывания этой строгой политики, что и делает её пригодной там.

capitalizedWords — свёртка имени в буквы и цифры

capitalizedWords <string> читает аргумент как слова, разделённые последовательностями любых символов, кроме букв и цифр ASCII, делает первую букву каждого слова заглавной и соединяет их. Каждый символ результата — буква или цифра.

Функция существует потому, что некоторые целевые платформы допускают только буквы и цифры в именах, по которым они обращаются к ресурсам, тогда как идентификатор компонента может законно содержать точку, дефис или подчёркивание. Ручная запись такого преобразования в каждом Recipe, где оно нужно, порождает несколько написаний одной идеи; единая функция даёт всем авторам один ответ.

# separators become word boundaries
{{ capitalizedWords `payments-db` }} # → PaymentsDb
{{ capitalizedWords `payments_db` }} # → PaymentsDb
{{ capitalizedWords `payments.db` }} # → PaymentsDb
# a run of separators is one boundary, and leading or trailing ones add nothing
{{ capitalizedWords `-payments--db-` }} # → PaymentsDb
# characters already inside a word keep the case they were authored with
{{ capitalizedWords `MY-app` }} # → MYApp
# a word beginning with a digit is carried as authored
{{ capitalizedWords `1st-app` }} # → 1stApp
# anything outside the alphabet is a boundary, including a non-ASCII letter
{{ capitalizedWords `café-app` }} # → CafApp

🔴 Результат не идентифицирует имя, из которого он получен. Все разделители отбрасываются, поэтому два идентификатора, различающиеся только расположением разделителей, дают один результат: payments-db и payments_db оба дают PaymentsDb. Функция не может это обнаружить, потому что видит одно имя за раз; выявлять это — задача того, что обращается к ресурсам по результату. Целевая платформа, которая так делает, отвергает коллизию, а не выпускает развёртывание без одного из двух: при сборке для CloudFormation два компонента, идентификаторы которых сворачиваются в одно имя, останавливают сборку, и сообщение называет каждый такой идентификатор. Выбирайте идентификаторы, различающиеся не только пунктуацией, и вопрос не возникнет.

Доступность по поверхностям. capitalizedWords зарегистрирована везде, где и optional: на каждой поверхности, которую вычисляет рендерер, и при разрешении структурированной координаты source:. Она недоступна в интерполяции параметров Aggregate, где предоставляется только набор Sprig.

index — ключ, который карта обязана содержать

index <collection> <key>... читает коллекцию по позиции или по ключу, как собственная index в Go, — с одним отличием. Когда коллекция — карта и карта не содержит ключа, index останавливает сборку и называет ключ, тогда как функция Go отвечает пустым значением, которое выводится как буквальный текст <no value>.

# Present: returns the value
{{ index .values `replicas` }} # .values.replicas = 3 → 3
# A position in a list, or in a string, reads as Go's does
{{ index .values.zones 0 }} # .values.zones = [a, b] → a
# Absent: halts, naming the key
{{ index .values `replicas` }} # .values.replicas unset → halts: (key "replicas")

Это способ чтения для случаев, когда ключ обязан быть, — учётные данные, читаемые под именем переменной, вычисленным Recipe, ключ, публикуемый другим шаблоном, — чтобы отсутствующий ключ останавливал сборку, а не попадал в артефакт как <no value>. Если ключ может законно отсутствовать, сначала проверьте его: {{ optional .values `replicas` 1 }} подставляет значение по умолчанию, get из Sprig возвращает пустую строку, а hasKey проверяет без чтения. Чтение через index с последующим default не даёт значения по умолчанию, потому что остановка происходит до выполнения default. Ключ, который присутствует и содержит null, не отсутствует: index возвращает его, и он выводится как <no value>.

Остановка — свойство только index, и она одинакова на каждой поверхности: в шаблонах значений, вычислителе утверждений, шаблонах путей, структурированной координате source:, интерполяции параметров Aggregate, предикате validate: параметра и предикатах x-aggrega-when: / x-aggrega-validate: схемы. Чтение незаданного ключа через точку следует собственной политике отсутствующих ключей своей поверхности и не затрагивается. Остановка описана в errors/fatal-halts.md «A template indexes a map with a key the map does not hold (Шаблон индексирует карту ключом, которого карта не содержит)».

Распространённые хелперы, которые НЕ доступны

Helm расширяет text/template из Go хелперами шаблонов чартов, которые часто ошибочно принимают за общие хелперы Sprig. Ни один из них не зарегистрирован в рендерере Aggrega. Шаблоны, которые вычисляет рендерер Aggrega (valuesMapping: в Recipe, injectMapping: в FeatureRecipe, provides, тело Workload, вычислитель утверждений), не могут их вызывать:

  • include — предпочтительная в Helm форма вызова определённого фрагмента шаблона со строковым выводом, который можно передать по конвейеру. Рендерер Aggrega его не регистрирует. Вместо него используйте стандартный для шаблонов Go {{ template "name" . }} (форма только с побочным эффектом); для вывода, передаваемого по конвейеру, составляйте композицию из фрагментов MappingLibrary и директив $import:.
  • tpl — повторно вычисляет строку как вложенный шаблон в текущем контексте. Aggrega его не регистрирует; вложенное повторное вычисление не входит в поверхность шаблонов. Авторам, которым нужны вычисляемые значения, следует составлять их с помощью строковых хелперов Sprig и выводить итоговое значение напрямую.
  • required — прерывает рендеринг чарта с пользовательским сообщением, если указанное значение отсутствует. Aggrega его не регистрирует. Проверка обязательных полей в Aggrega выполняется на уровне типизированного контракта параметров (слот parameters: в Aggregate с required: true, который Release оставляет незаполненным, останавливает сборку с E0165, называя слот и место, где Aggregate его объявляет); проверки обязательных маркеров в отдельных шаблонах используют fail из Sprig, чтобы вызвать фатальную ошибку шаблона с переданной строкой.
  • warn — выводит нефатальное примечание в терминал оператора. Aggrega его не регистрирует. Шаблонам, которым нужно остановить рендеринг с поясняющим сообщением, следует использовать fail из Sprig; шаблонам, которым нужно перейти к запасному варианту без остановки, следует опираться на стандартные ветви if/else в Go.

Перечень хелперов в разных движках (важно для авторов MappingLibrary)

Фрагменты MappingLibrary могут быть предназначены для одного из двух мест потребления:

  • Потребление на стороне Aggrega (valuesMapping: в Recipe, injectMapping: в FeatureRecipe и т. д., вычисляемые рендерером Aggrega). Доступные хелперы: полный Sprig v3 (default, coalesce, quote, nindent, indent, b64enc и т. д.) плюс собственные хелперы Aggrega (optional, capitalizedWords), а index останавливает сборку на ключе, которого нет в карте. Хелперы шаблонов чартов (include, tpl, required, warn) НЕ доступны.
  • Потребление внутри чарта Helm (содержимое values.yaml чарта или templates/*.yaml чарта, которые затем рендерит собственный движок шаблонов Helm). Доступные хелперы: полный Sprig v3 плюс хелперы шаблонов чартов Helm (include, tpl, required, warn). Собственные хелперы Aggrega НЕ доступны, а index там — собственный из Go, который на отсутствующий ключ отвечает пустым значением, а не остановкой.

Два набора хелперов разделяют поверхность Sprig, но расходятся в расширениях, специфичных для движка. Записи MappingLibrary, предназначенные для потребления внутри чарта Helm, следуют соглашениям Helm (корень .Values.<key> с заглавной V, | default, композиция на основе include); записи, предназначенные для потребления на стороне Aggrega, следуют соглашениям Aggrega (.values.<key> в нижнем регистре, optional для запасного значения с учётом наличия ключа). Сущность библиотеки хранит фрагменты дословно; форма при написании определяется тем, где фрагмент должен рендериться.

Собственные вспомогательные функции Aggrega поверх Sprig — это optional и capitalizedWords, обе описаны выше, а её index заменяет одноимённую функцию Go, как описано выше. Остальная часть набора вспомогательных функций — это в точности набор Sprig v3.

Перекрёстные ссылки

  • template-context-contract.md — поля времени выполнения, которые шаблоны читают наряду с хелперами Sprig.
  • expansion-matrix.md — порядок вычисления для каждого места шаблона.
  • 05-templates.md — обзор шаблонизации и соглашения о написании шаблонов.
  • Документация Sprig v3 — канонический справочник по каждой функции.