Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

Các hàm và helper của Sprig

Template engine của Aggrega gắn thư viện hàm Sprig v3 cùng các helper riêng của Aggrega (optional và capitalizedWords) vào mọi Go template mà renderer đánh giá, và thay thế index của Go bằng một phiên bản dừng lại khi gặp một khóa map mà map không chứa. Tác giả viết valuesMapping: của Recipe, injectMapping: của FeatureRecipe, hoặc bất kỳ bề mặt template nào khác mà renderer đánh giá đều có sẵn toàn bộ bộ helper của Sprig, bên cạnh các built-in của Go text/template và các trường ngữ cảnh runtime được mô tả trong template-context-contract.md.

🔴 Hãy hiểu “mà renderer đánh giá” đúng như phạm vi của nó, vì có một bề mặt soạn thảo nằm ngoài phạm vi đó. Một tọa độ source: có cấu trúc được phân giải để artifact mà nó chỉ định có thể được ghim, và việc phân giải đó không phải là một lượt render: nó đăng ký các helper riêng của Aggrega và không gì khác, vì vậy một lời gọi Sprig trong một trường source:, hoặc trong một mục locals: mà trường đó đọc, sẽ làm dừng thao tác pull. Một mục mà không trường source: nào đọc chỉ được đánh giá bởi lượt render, với toàn bộ bộ hàm. Việc phân giải một tọa độ xác định thứ được ghim chứ không tạo ra artifact, đó là lý do bộ hàm của nó được chủ ý thu hẹp hơn — xem errors/fatal-halts.md “Resolving a source: coordinate registers a narrower function set (Việc phân giải một tọa độ đăng ký một bộ hàm hẹp hơn)” để biết về điểm dừng và dạng khả chuyển nên dùng thay thế.

Bộ Sprig được đăng ký riêng cho nội suy tham số, và cùng với các helper riêng của Aggrega tại các bề mặt value-template của renderer.

Những gì được kết nối

Sprig v3 cung cấp toàn bộ tập hàm trợ giúp của nó — khoảng 200 hàm thuộc các nhóm dưới đây. Trang này phác họa các nhóm cùng những hàm trợ giúp thông dụng trong mỗi nhóm; tài liệu tham khảo chính thức cho từng hàm là tài liệu Sprig gốc.

  • Chuỗi — upper, lower, title, trim, trimAll, trimPrefix, trimSuffix, replace, contains, hasPrefix, hasSuffix, substr, quote, squote, cat, indent, nindent, repeat, các hàm trợ giúp về kiểu chữ (snakecase, camelcase, kebabcase), các hàm trợ giúp rút gọn (abbrev, abbrevboth, trunc), các hàm trợ giúp checksum (sha1sum, sha256sum, sha512sum, adler32sum), toString.
  • Danh sách — list, tuple, first, last, rest, initial, append/push, prepend, concat, reverse, uniq, without, has, slice, chunk, join, splitList, split, splitn, sortAlpha, compact.
  • Từ điển — dict, get, set, unset, hasKey, keys, values, pick, omit, pluck, merge, mergeOverwrite, dig, deepCopy.
  • Toán học — add, sub, mul, div, mod, add1, min, max, ceil, floor, round, cùng các biến thể số thập phân có hậu tố f (addf, subf, mulf, divf, minf, maxf).
  • Chuyển đổi — int, int64, float64, atoi, toString, toDecimal, seq, until, untilStep.
  • Mã hóa — b64enc, b64dec, b32enc, b32dec, toJson, toPrettyJson, toRawJson, fromJson, cùng các biến thể JSON có tiền tố must, vốn báo lỗi giải mã thay vì âm thầm trả về giá trị rỗng.
  • Kiểm tra kiểu — typeOf, typeIs, typeIsLike, kindOf, kindIs, deepEqual, empty.
  • Giá trị mặc định và luồng điều khiển — default, coalesce, all, any, ternary, fail (gây ra lỗi template với thông báo tùy chỉnh — cách chuẩn để hủy một lần render bằng thông báo kiểm tra).
  • Biểu thức chính quy — regexMatch, regexFind, regexFindAll, regexReplaceAll, regexReplaceAllLiteral, regexSplit, regexQuoteMeta, cùng các biến thể nghiêm ngặt có tiền tố must.
  • Đường dẫn — base, dir, clean, ext, isAbs (kiểu Unix); osBase, osClean, osDir, osExt, osIsAbs (tùy theo hệ điều hành).
  • SemVer — semver, semverCompare.
  • URL — urlParse, urlJoin.
  • Ngày giờ — ago, date, dateInZone, dateModify, duration, durationRound, htmlDate, htmlDateInZone, now, toDate, unixEpoch.

Lưu ý về tính tất định

Aggrega đảm bảo đầu ra giống hệt nhau từng byte cho đầu vào giống hệt nhau từng byte. Một tập con các helper của Sprig đọc trạng thái môi trường xung quanh và phá vỡ sự đảm bảo đó khi được gọi từ một template. Tác giả nên tránh các helper sau trong những bề mặt template góp phần tạo ra các artifact được render:

  • Bộ đọc đồng hồ thực — now, date, dateInZone, dateModify, htmlDate, htmlDateInZone, ago khi được gọi mà không có thời điểm tham chiếu cố định.
  • Bộ sinh ngẫu nhiên — randAlpha, randAlphaNum, randAscii, randNumeric, randBytes, randInt, uuidv4.
  • Bộ đọc môi trường — env, expandenv (đọc các biến môi trường của tiến trình, vốn khác nhau giữa các máy trạm của người vận hành và các CI runner).
  • Bộ phân giải mạng — getHostByName.

Các helper này không bị engine chặn; chúng là một phần của bộ Sprig v3. Kỷ luật tránh dùng chúng trong các template trên đường render được duy trì bởi người review và bởi sự đảm bảo đầu ra tất định mà các tác giả và catalog thư viện chuẩn dựa vào.

Số trong một value template

Một số do tác giả viết đến value template dưới dạng một số. Một số nguyên là integer và được in nguyên: 1000000 in ra 1000000. Mọi số khác được in ở dạng thập phân chính xác ngắn nhất, không bao giờ ở dạng số mũ: một 0.0000001 do tác giả viết in ra 0.0000001 và một 1e21 do tác giả viết in ra 1000000000000000000000, dù template viết giá trị trực tiếp hay chuyển nó thành văn bản bằng toString, quote, printf "%v" hoặc toJson. Một số mà hàm toán học trả về — mulf, float64, round và các hàm cùng loại — là giá trị riêng của hàm đó và được in theo dạng riêng của hàm đó, tức dạng số mũ đối với một giá trị rất nhỏ hoặc rất lớn: {{ mulf .values.ratio 1 }} in ra 1e-07 với một 0.0000001 do tác giả viết.

Các phép so sánh — eq, ne, lt, le, gt và ge — đọc hai số theo giá trị, bất kể kiểu nào mang mỗi số, nên một số nguyên do tác giả viết được so sánh với một số thập phân viết trong template, và 3 bằng 3.0:

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

Một số không bao giờ được so sánh với một đoạn văn bản: bất kỳ phép nào trong sáu phép so sánh, khi nhận một số và văn bản trong dấu ngoặc kép, đều dừng build và nêu tên cả hai kiểu. Hãy so sánh số đó với một số viết không có dấu ngoặc kép, hoặc chuyển nó thành văn bản trước:

{{ 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

Điểm dừng đó là A value template failed while it ran (Một value template đã thất bại khi đang chạy). Một assertion đọc một số do tác giả viết theo cùng cách; xem Số trên bề mặt này.

Sự hiện diện và tính rỗng — hai câu hỏi khác nhau

Một template đặt một trong hai câu hỏi về một giá trị, và mỗi câu hỏi có các helper riêng.

  • Tác giả có viết nó không? hasKey và optional trả lời theo sự hiện diện. Một khóa mà tác giả đã viết thì hiện diện dù nó chứa gì — kể cả 0, "" và false — và chỉ khóa mà tác giả bỏ qua mới vắng mặt.
  • Nó có rỗng không? default, with, if và empty trả lời theo tính rỗng. 0, "", false, một danh sách rỗng, một map rỗng và một giá trị vắng mặt đều được coi là rỗng ở đó, như trong Helm.
.values.replicashasKey .values "replicas"optional .values "replicas" 1.values.replicas | default 1if .values.replicas
vắng mặtfalse11false
0true01false
3true33true

Một giá trị có thể hợp lệ là 0, "" hoặc false — số replica bằng không, timeout bằng không, một cờ bị tắt — được kiểm tra bằng hasKey hoặc optional, để 0 của tác giả đến đầu ra dưới dạng 0. default, with và if phù hợp với một giá trị mà dạng rỗng của nó không mang ý nghĩa riêng, nơi “rỗng” và “không được viết” có thể được xử lý như nhau. Hãy đọc một khóa nhất định theo một cách duy nhất trong mỗi template: một khóa mà template cũng đọc dưới dạng đường dẫn có dấu chấm sẽ được coi là hiện diện, như giới hạn của optional mô tả.

Các helper riêng của Aggrega

optional — giá trị dự phòng có nhận biết sự hiện diện

optional <map> <key> <fallback> trả về giá trị tại <key> trong <map> nếu khóa có mặt, ngược lại trả về <fallback>. Khác với default của Sprig, optional phân biệt “khóa vắng mặt” với “khóa có mặt với giá trị không, rỗng hoặc false.”

Chữ ký nhận map và khóa làm hai đối số riêng vì một giá trị được truyền qua toán tử | của Go template đã mất quyền truy cập vào map cha của nó. Khi không có map cha trong phạm vi, không thể kiểm tra sự hiện diện.

Có một giới hạn đối với việc kiểm tra sự hiện diện, và nó đến từ template chứ không phải từ helper: một value template đọc một khóa vắng mặt là không có gì, bằng cách cung cấp một giá trị rỗng tại mỗi khóa vắng mặt mà template nêu dưới dạng đường dẫn có dấu chấm và đọc như một giá trị. Vì vậy, một template đọc một khóa cả qua optional lẫn dưới dạng đường dẫn như thế sẽ thấy khóa đó có mặt và rỗng, và nhận giá trị rỗng thay vì giá trị dự phòng. Hãy đọc một khóa theo một cách duy nhất trong mỗi template, khi đó hai câu trả lời sẽ khớp nhau.

# 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

Trường hợp cuối là sự phân biệt mà default của Sprig không làm được. {{ .infra.replicas | default 1 }} trả về 1 dù replicas được viết là 0 hay bị bỏ qua — sự gộp lẫn này ngăn cản các mẫu hợp lệ như scale-to-zero, không thử lại, không timeout và cờ false.

Quy ước trích dẫn khóa: ưu tiên dấu backtick. Go templates chấp nhận cả chuỗi literal trong dấu nháy kép ("replicas") lẫn trong dấu backtick (`replicas`) cho đối số khóa; cả hai tạo ra cùng một chuỗi khi đánh giá template. Các ví dụ trong catalog và tài liệu đều dùng dạng backtick vì nó an toàn với YAML trong mọi ngữ cảnh trích dẫn. Một khóa trong dấu nháy kép nằm bên trong một scalar YAML có dấu nháy kép sẽ kết thúc chuỗi YAML giữa chừng template:

# 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 }}"

Khi template nằm trong một block-scalar YAML (dạng |) hoặc là một scalar giá trị trần, cả hai dạng đều hiển thị đúng. Khi template được nhúng trong một scalar YAML có dấu nháy kép (mẫu giá-trị-trường-làm-template field: "{{ ... }}"), bắt buộc phải dùng backtick. Quy ước duy nhất (luôn dùng backtick) tránh hoàn toàn cái bẫy trích dẫn YAML.

Khi nào nên ưu tiên optional thay vì default. Dùng optional khi trường có thể hợp lệ mang giá trị không, rỗng hoặc false và tác giả catalog cần phân biệt “tác giả không đặt giá trị này” với “tác giả đặt giá trị này thành một giá trị falsy.” Dùng default khi sự gộp lẫn là chấp nhận được (ví dụ: trường chuỗi mà giá trị rỗng là không hợp lệ; trường số mà giá trị không là không hợp lệ).

Khả dụng theo từng bề mặt. optional được đăng ký trên mọi bề mặt mà renderer đánh giá: các bề mặt value template (Recipe valuesMapping, FeatureRecipe injectMapping, provides, pipeline.with, phần thân Workload), bộ đánh giá assertion, và path template (directory: / subDirectory: trên các ranh giới Release). Điểm khác biệt trên bề mặt path template không phải là tập helper mà là chính sách khóa thiếu: một path template coi khóa vắng mặt là lỗi thay vì là rỗng, vì một đoạn đường dẫn rỗng một cách âm thầm tạo ra bố cục hệ thống tệp bị hỏng mà chỉ được phát hiện sau khi build. optional đọc một khóa mà chính sách nghiêm ngặt đó không kích hoạt trước, và đó là điều khiến nó dùng được ở đây.

capitalizedWords — gộp một tên thành chữ cái và chữ số

capitalizedWords <string> đọc đối số của nó như các từ được phân tách bởi các chuỗi ký tự bất kỳ nằm ngoài chữ cái và chữ số ASCII, viết hoa chữ cái đầu của mỗi từ, rồi nối chúng lại. Mọi ký tự của kết quả đều là chữ cái hoặc chữ số.

Helper này tồn tại vì một số đích chỉ chấp nhận chữ cái và chữ số trong tên dùng để định danh tài nguyên, trong khi id của một component có thể hợp lệ chứa dấu chấm, dấu gạch nối hoặc dấu gạch dưới. Tự viết phép chuyển đổi đó trong mỗi Recipe cần đến nó sẽ tạo ra nhiều cách viết cho cùng một ý tưởng; một helper duy nhất cho mọi tác giả cùng một câu trả lời.

# 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

🔴 Kết quả không xác định được tên mà nó bắt nguồn. Mọi ký tự phân tách đều bị loại bỏ, nên hai id chỉ khác nhau ở vị trí các ký tự phân tách sẽ cho cùng một kết quả — payments-db và payments_db đều cho PaymentsDb. Helper không thể phát hiện điều đó, vì nó chỉ thấy từng tên một; việc phát hiện thuộc về bất cứ thứ gì định danh tài nguyên bằng kết quả. Một đích làm như vậy sẽ từ chối sự trùng lặp thay vì xuất ra một bản triển khai thiếu một trong hai: khi build cho CloudFormation, hai component có id gộp thành cùng một tên sẽ dừng build, và thông báo nêu tên mọi id dẫn đến tên đó. Hãy chọn các id khác nhau không chỉ ở dấu câu, khi đó vấn đề sẽ không phát sinh.

Khả dụng theo từng bề mặt. capitalizedWords được đăng ký ở mọi nơi optional được đăng ký: mọi bề mặt mà renderer đánh giá, và việc phân giải một tọa độ source: có cấu trúc. Nó không khả dụng trong phép nội suy tham số của Aggregate, nơi chỉ cung cấp tập Sprig.

index — một khóa mà map phải chứa

index <collection> <key>... đọc một collection theo vị trí hoặc theo khóa, như index của chính Go — với một điểm khác biệt. Khi collection là một map và map không chứa khóa, index dừng build và nêu tên khóa, trong khi bản của Go trả về một giá trị rỗng được in ra dưới dạng văn bản literal <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")

Đây là cách đọc nên dùng khi khóa phải có mặt — một thông tin xác thực được đọc theo tên biến mà Recipe đã tính, một khóa mà template khác công bố — để khóa bị thiếu sẽ dừng build thay vì đi vào artifact dưới dạng <no value>. Khi khóa có thể hợp lệ vắng mặt, hãy kiểm tra trước: {{ optional .values `replicas` 1 }} cung cấp giá trị dự phòng, get của Sprig trả về chuỗi rỗng, và hasKey kiểm tra mà không đọc. Đọc qua index rồi áp dụng default không cung cấp giá trị dự phòng, vì việc dừng xảy ra trước khi default chạy. Một khóa có mặt và mang giá trị null thì không phải vắng mặt: index trả về nó, và nó được in ra là <no value>.

Việc dừng là thuộc tính của riêng index, và nó giống nhau trên mọi bề mặt — các value template, bộ đánh giá assertion, path template, một tọa độ source: có cấu trúc, phép nội suy tham số của Aggregate, vị từ validate: của một tham số và các vị từ x-aggrega-when: / x-aggrega-validate: của một schema. Việc đọc bằng dấu chấm một khóa chưa được đặt tuân theo chính sách khóa thiếu của bề mặt đó và không bị ảnh hưởng. Việc dừng được ghi lại tại errors/fatal-halts.md “A template indexes a map with a key the map does not hold (Một template truy cập map bằng một khóa mà map không chứa)”.

Các helper phổ biến KHÔNG có sẵn

Helm mở rộng text/template của Go bằng các helper chart-template thường bị nhầm là helper Sprig chung. Không helper nào trong số này được đăng ký trong renderer của Aggrega. Các template mà renderer của Aggrega đánh giá (Recipe valuesMapping:, FeatureRecipe injectMapping:, provides, phần thân Workload, bộ đánh giá assertion) không thể gọi chúng:

  • include — dạng Helm ưa dùng để gọi một đoạn template đã định nghĩa với đầu ra chuỗi có thể pipe. Renderer của Aggrega không đăng ký nó. Thay vào đó, hãy dùng {{ template "name" . }} của Go template chuẩn (dạng chỉ có tác dụng phụ); để có đầu ra có thể pipe, hãy kết hợp các đoạn MappingLibrary và các chỉ thị $import:.
  • tpl — đánh giá lại một chuỗi như một template lồng nhau trên ngữ cảnh hiện tại. Aggrega không đăng ký nó; việc đánh giá lại lồng nhau không thuộc bề mặt template. Tác giả cần giá trị được tính toán nên kết hợp chúng bằng các helper chuỗi của Sprig và xuất trực tiếp giá trị cuối cùng.
  • required — làm thất bại quá trình render chart với một thông báo tùy chỉnh khi giá trị được nêu tên bị thiếu. Aggrega không đăng ký nó. Việc bắt buộc trường của Aggrega nằm ở tầng hợp đồng tham số có kiểu (một slot parameters: của Aggregate với required: true mà Release để trống sẽ dừng build với E0165, nêu tên slot và nơi Aggregate khai báo nó); các kiểm tra đánh dấu bắt buộc theo từng template dùng fail của Sprig để phát sinh một lỗi template nghiêm trọng mang chuỗi được cung cấp.
  • warn — xuất một ghi chú không nghiêm trọng ra terminal của người vận hành. Aggrega không đăng ký nó. Các template cần dừng quá trình render với một thông báo giải thích nên dùng fail của Sprig; các template cần dùng giá trị dự phòng mà không dừng nên dựa vào các nhánh if/else chuẩn của Go.

Danh mục helper giữa các engine (quan trọng đối với tác giả MappingLibrary)

Các đoạn MappingLibrary có thể nhắm tới một trong hai nơi tiêu thụ:

  • Tiêu thụ phía Aggrega (Recipe valuesMapping:, FeatureRecipe injectMapping:, v.v., được renderer của Aggrega đánh giá). Các helper có sẵn là: toàn bộ Sprig v3 (default, coalesce, quote, nindent, indent, b64enc, v.v.) cộng với các helper riêng của Aggrega (optional, capitalizedWords), và index dừng lại khi gặp một khóa mà map không chứa. Các helper chart-template (include, tpl, required, warn) KHÔNG có sẵn.
  • Tiêu thụ bên trong chart Helm (nội dung values.yaml của chart hoặc templates/*.yaml của chart được engine template riêng của Helm render ở phía sau). Các helper có sẵn là: toàn bộ Sprig v3 cộng với các helper chart-template của Helm (include, tpl, required, warn). Các helper riêng của Aggrega KHÔNG có sẵn, và index ở đó là của chính Go, trả về giá trị rỗng cho khóa vắng mặt thay vì dừng lại.

Hai tập helper chia sẻ bề mặt Sprig nhưng khác nhau ở các phần mở rộng riêng của từng engine. Các mục MappingLibrary nhắm tới việc tiêu thụ bên trong chart Helm dùng các quy ước của Helm (gốc .Values.<key> với chữ V hoa, | default, kết hợp dựa trên include); các mục nhắm tới việc tiêu thụ phía Aggrega dùng các quy ước của Aggrega (.values.<key> viết thường, optional cho giá trị dự phòng có nhận biết sự hiện diện). Thực thể thư viện lưu các đoạn nguyên văn; hình dạng soạn thảo tuân theo nơi đoạn đó được dự định render.

Các helper tùy chỉnh mà Aggrega bổ sung trên Sprig là optional và capitalizedWords, cả hai đều được mô tả ở trên, và index của nó thay thế hàm index của Go, như đã mô tả ở trên. Phần còn lại của bề mặt helper đúng là bộ Sprig v3.

Tham chiếu chéo