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.

Pipeline biên dịch (tổng quan)

Chương này trình bày chi tiết cơ chế vận hành nội bộ của trình biên dịch Go, xác định cách YAML trừu tượng được chuyển thành các cấu hình vật lý xuyên suốt pipeline biên dịch, đồ thị biểu diễn trung gian (IR) và các socket thực thi WebAssembly (Wasm).

Pipeline biên dịch & luồng thực thi

Aggrega chạy một pipeline trình biên dịch biên dịch trước (AOT) nghiêm ngặt, có thứ tự cố định thay vì logic điều phối được mã hóa cứng. Được kích hoạt bởi aggrega build, trình biên dịch chuyển đồ thị phẳng giữa các socket WebAssembly (Wasm) cô lập để đánh giá kiến trúc trước khi kết xuất các artifact vật lý.

Các socket Wasm chạy trên một host nhúng — bộ công cụ Extism trên nền engine Wazero — đằng sau một tường lửa thuần AOT từ chối cấp cho plugin bất kỳ năng lực truy cập runtime nào (mạng, hệ thống tệp, đồng hồ thực, môi trường, I/O chuẩn), nên một plugin không thể phá vỡ đảm bảo tất định, biên dịch trước. Host chạy publishing-linter ngoài băng, thông qua aggrega lint. Các cổng trong băng được mô tả dưới đây — vai trò label-transform của socket quản trị khi xây dựng cấu trúc liên kết và vai trò IR-verdict của nó trong phân tích tĩnh, cùng với pipeline plugin khép lại giai đoạn kết xuất — chạy trong mọi bản build: một vai trò quản trị ở bất cứ đâu workspace gắn plugin vào nó, và pipeline plugin cho mọi Recipe khai báo các bước. Trạng thái của ngôn ngữ theo dõi trạng thái của từng giai đoạn pipeline.

Pipeline thực thi hoàn toàn trong bộ nhớ theo một thứ tự cố định, nghiêm ngặt:

Phân giải — Bộ phân giải & bộ kiểm tra cú pháp

  • Cơ chế: Hợp nhất kế thừa, nội suy Go Template và xác thực JSON Schema 2020-12.
  • Hành động: CLI tải về mọi thực thể được yêu cầu (Components, Features, Releases). Trước tiên, nó kiểm tra các định nghĩa này để tìm từ khóa extends. Với các thực thể Catalog, nó hợp nhất sâu siêu dữ liệu YAML, và hai loại tách nhau ở các trụ dữ liệu: schema: của một Feature được kết hợp với phần tương ứng của lớp cơ sở theo cơ chế kết hợp của JSON Schema 2020-12, trong khi một Component mở rộng chỉ kết hợp cấu trúc — các slot đính kèm, các socket topo, danh sách cho phép tự tiêm và các khẳng định có tên — và nhận khối schema: của lớp cơ sở đúng như lớp cơ sở đã viết. Một Release mở rộng được gộp theo cùng quy tắc: giá trị của con thắng theo từng khóa, xuống tới giá trị không thể chia nhỏ đầu tiên — một scalar, một danh sách, một template — vốn được thay thế toàn bộ, và một khóa mà con ghi là null sẽ bị xóa. Vì vậy toàn bộ bề mặt soạn thảo của nó được mang theo — cây ranh giới cùng infra theo từng thành phần và các đính kèm Feature, khối parameters, các annotation và con trỏ Manifest — trong khi không trường metadata nào được mang theo, vì danh tính và nguồn gốc là riêng cho từng Release. Tiếp theo, nó thực hiện nội suy trong bộ nhớ qua ba bước con: kiểm tra hợp đồng tham số dựa trên các khai báo parameters: có kiểu của Aggregate; nội suy các giá trị đã phân giải vào các chuỗi values: bao quanh; rút bản đồ .parameters khỏi mọi ngữ cảnh template giá trị, để nó chỉ còn đọc được bởi các template đường dẫn do người vận hành viết. Cuối cùng, nó tiêm các khối infra đã phân giải vào payload của các thành phần đích. Khi bản thiết kế đã hoàn toàn cụ thể, trình biên dịch dùng khai báo schema: hợp nhất từ Catalog (dạng rút gọn hoặc JSON Schema 2020-12 đầy đủ) để kiểm tra nghiêm ngặt các cấu hình values và infra của nhà phát triển ngay tại chỗ.
    • Xác thực schema Feature của Release: Các Features được gắn thông qua Release (cả trên toàn ranh giới lẫn riêng cho thành phần) được phân giải theo các thực thể Catalog của chúng trong bước này. Trình biên dịch xác thực các khối infra do Release cung cấp theo khai báo schema: của từng Feature ngay sau khi phân giải catalog, đảm bảo an toàn kiểu trước khi cấu trúc liên kết được xây dựng.
    • Giai đoạn con mở rộng Feature dựa trên annotation: Sau khi phân giải Manifest, liên kết Recipe/Provider và xác thực đích liên kết của Manifest (các đường dẫn khai báo dưới mappings.features.annotations.<key>.maps tồn tại trong spec.schema của Feature được tham chiếu), trình biên dịch chạy một giai đoạn con mở rộng annotation trước bộ xây dựng cấu trúc liên kết. Giai đoạn con này duyệt các ranh giới Release từ ngoài vào trong và các hệ thống con Aggregate từ ngoài vào trong, tính tập annotation hiệu lực cho từng thành phần thông qua hợp nhất cascade + ghi đè + null-opt-out; phân tích mỗi giá trị annotation dưới dạng YAML thành một scalar, một giá trị có cấu trúc hoặc null; định tuyến mỗi giá trị (scalar hoặc có cấu trúc theo từng khóa con) qua khai báo maps của liên kết Manifest tới trụ schema Feature đích với việc thực thi phía-so-với-trụ (phía Aggregate kích hoạt maps.values; phía Release kích hoạt maps.infra); xác thực kiểu theo từng lá với spec.schema của Feature; và chèn các phần gắn kèm Feature tổng hợp mà đồ thị IR đánh dấu bằng origin: annotation. Các schema được biên dịch một lần mỗi bản build và được tái sử dụng qua các lần duyệt cascade. Việc mở rộng chạy sau xác thực đích liên kết và trước khi xây dựng cấu trúc liên kết, nên các giai đoạn phía sau xử lý các phần gắn kèm tổng hợp giống hệt về mặt cấu trúc như các phần gắn kèm tường minh (ngoại trừ qua việc kiểm tra nguồn gốc). Xem 13-catalog-and-registry.md §“Mở rộng Feature dựa trên annotation” và language-reference/providers/well-known-annotations.md để biết hình dạng liên kết, ngữ nghĩa cascade và các quy tắc kết hợp giữa hai phía.

Xây dựng cấu trúc liên kết — Bộ xây dựng cấu trúc liên kết & cổng biến đổi

  • Cơ chế: Mở rộng AST + vai trò label-transform của socket quản trị.
  • Hành động: Trình biên dịch đọc nguyên bản các khối uses được khai báo tường minh từ các thành phần đã xác thực để vẽ một cách tất định các cạnh cấu trúc liên kết giữa các nút trong đồ thị, để khối values hoàn toàn mờ đục. Sau đó nó đánh giá Cổng biến đổi, chuyển một phép chiếu của đồ thị — nhãn của mỗi nút và values mà instance của nút khai báo, được trình biên dịch chuyển đi mà không đọc — cùng với tên và môi trường của Release tới một plugin quản trị được gắn ở vai trò label-transform. Plugin đánh giá ngữ cảnh và trả về các JSONPatch để tự động gắn thẻ đồ thị một cách động (ví dụ: chèn nhãn compliance.aggrega.ai/data-class: restricted dựa trên môi trường của Release, hoặc datastore.aggrega.ai/engine: vector dựa trên các extension mà một cơ sở dữ liệu khai báo); các bản vá chỉ tác động tới nhãn.

Hoàn thiện đồ thị

  • Cơ chế: Chuẩn hóa.
  • Hành động: Trình biên dịch hoàn thiện đồ thị biểu diễn trung gian (IR) phẳng, giữ nguyên các cạnh cấu trúc liên kết tường minh mà bộ xây dựng cấu trúc liên kết đã vẽ. Sau đó nó chuẩn hóa các Features được gắn và payload values của chúng thành một từ điển phẳng ánh xạ theo ID nút, chuẩn bị đồ thị không phụ thuộc vào năng lực cho bước xác thực.
    • Chuẩn hóa payload IR: Hình dạng cấu trúc của IR áp đặt một nguồn sự thật duy nhất cho cấu hình: lớp cấu trúc liên kết chỉ mang cấu trúc đồ thị (danh tính nút, cạnh, nhãn metadata), và trạng thái cấu hình đã chuẩn hóa nằm trong một từ điển trong bộ nhớ riêng biệt mà trình biên dịch chuyển cho các plugin ở phía sau. Các mutator thay đổi cấu hình sẽ thay đổi nó tại một nơi; provider đọc trạng thái đã chuẩn hóa mà không có nguy cơ sai lệch do lưu trữ dư thừa.

Phân tích tĩnh — Bộ phân tích tĩnh & cổng xác thực

  • Cơ chế: Kiểm tra tính thuần khiết cấu trúc liên kết + vai trò ir-verdict của socket quản trị.
  • Hành động: Trình biên dịch chạy phân tích tĩnh trừu tượng trên đồ thị IR. Thứ nhất, nó trích xuất các chuỗi selector từ các định nghĩa usesSchema và đánh giá chúng bằng một bộ máy so khớp nhãn Go nguyên bản (hỗ trợ ngữ nghĩa kiểu Kubernetes AND, OR qua in(), và NOT qua !=) trên các cạnh đồ thị được định nghĩa tường minh để đảm bảo an toàn kiểu xuyên nút trên các socket được khai báo. Một cạnh trên socket ad-hoc — socket mà tác giả Aggregate đặt tên và catalog không khai báo — không có mục catalog và do đó không có selector, nên không có gì để kiểm tra này đánh giá và không có gì bị thiếu; mỗi cạnh ghi lại nó thuộc loại nào trong hai loại, và những gì một cạnh ad-hoc có thể mang thay vào đó bị giới hạn bởi provides được khai báo của đích. Nó cũng đánh giá các selector appliesTo và appliesToAnyOf của Feature để xác minh rằng các tính năng được gắn tương thích với nhãn của thành phần đích, và selector riêng của mỗi khe gắn kèm đã được lấp đầy với nhãn của Feature lấp đầy nó. Thứ hai, nó đánh giá mọi yêu cầu bắt buộc hiện diện mà Component của một nút khai báo — mỗi annotation features.aggrega.ai/requiredType.<label> — với tập phần gắn kèm cuối cùng của nút đó. Bộ phân tích là nơi kiểm tra này thuộc về vì đó là giai đoạn đầu tiên nắm giữ cả hai nửa của quy tắc: các annotation của thực thể Component đã phân giải và tập phần gắn kèm mà cascade 5 tầng tạo ra, tính cả các phần gắn kèm được gắn ở Aggregate, ở hệ thống con, ở Release và được mở rộng từ annotation như nhau. Một yêu cầu bắt buộc không được phần gắn kèm nào thỏa mãn sẽ dừng bản build; một yêu cầu bắt buộc có khai báo sai định dạng sẽ dừng với một chẩn đoán riêng, để một khai báo hỏng không bao giờ bị hiểu là một yêu cầu đã được thỏa mãn. Thứ ba, nó thực thi Cổng xác thực, chuyển toàn bộ cấu trúc đồ thị (bao gồm mọi nút, cạnh, tính năng được gắn và các đường DFS được tính trước) tới một plugin quản trị được gắn ở vai trò ir-verdict. Chính sách Wasm tùy chỉnh của doanh nghiệp đánh giá cấu trúc liên kết. Nếu plugin Wasm trả về một mảng lỗi (ví dụ: phát hiện một đường liên tục từ một nút public tới một nút restricted mà không có một tính năng proxy cụ thể), bản build sẽ dừng.

Kết xuất

  • Cơ chế: Chặn trước kết xuất (injectMapping), liên kết muộn (valuesMapping) và các socket kết xuất Wasm (pipeline).
  • Hành động: Giai đoạn sinh artifact cuối cùng được chia thành các giai đoạn con theo thời gian nghiêm ngặt, chạy theo thứ tự cố định, điều này giữ cho việc thực thi tất định:
    • Inject mapping (chặn trước kết xuất): Trình biên dịch Go phân giải hợp đồng .context.inject trừu tượng của Developer. Sau đó nó thực thi các template Go injectMapping từ tất cả FeatureRecipes được gắn theo thứ tự thực thi nghiêm ngặt của Mô hình củ hành 5 tầng (Sub-Aggregate — các phần gắn kèm của chính thành phần trong module, rồi đến các phần gắn kèm mà các hệ thống con của module đó khai báo, từ ngoài vào trong → thành phần Aggregate gốc → hệ thống con Aggregate gốc → ranh giới Release từ ngoài vào trong → riêng cho thành phần trong Release). Trình biên dịch hợp nhất sâu nguyên bản các từ điển kết quả lên đường ống bộ nhớ .context.inject của Caller. Điều này ghi lại một cách an toàn các biến môi trường và chuỗi kết nối cho Caller trước khi Recipe cơ sở nhìn thấy chúng. Một mapping có thể ghi lại những gì khối inject: của chính Caller hoặc một trong các kết nối của nó đã cung cấp; một khóa mà một Feature được gắn khác đã cung cấp — thông qua mapping của chính nó hoặc khối inject: của chính nó — sẽ dừng bản build và nêu tên cả hai phần gắn kèm, để thứ tự thực thi không bao giờ phải quyết định giữa giá trị của hai phần gắn kèm.
    • Phần mở đầu locals: Trước khi bất kỳ template provides nào chạy, trình biên dịch đánh giá các mục .locals của Recipe theo thứ tự chúng được viết, mỗi mục với một ngữ cảnh cục bộ nút khép kín — .context.instance_id, .values, .infra, và các mục của cùng khối đã được phân giải cho đến lúc đó, nhưng không có .context.inject hay .context.uses. Do đó một mục có thể đọc một mục anh em được định nghĩa phía trên nó và nhận giá trị đã phân giải của mục đó; thứ tự của tác giả là một phần của hợp đồng ở bất cứ đâu một mục đọc mục khác, và khối này không bao giờ được sắp xếp lại để làm một tham chiếu phân giải được. Việc phân giải locals trước là điều cho phép một template provides đọc .locals. Template .source của Recipe được đánh giá với cùng ngữ cảnh đó sau khi các locals đã được phân giải, điều này giữ cho .locals có thể tái sử dụng như dạng viết tắt trên các template của một Recipe và cho phép tác giả tham số hóa .source (phiên bản chart, đường dẫn, registry) theo từng ranh giới.
    • Kết xuất cơ sở (valuesMapping của Recipe cơ sở): Trình biên dịch đánh giá template valuesMapping của Recipe cơ sở. Template đọc các chuỗi đã bị chặn từ đường ống .context.inject (được ghi lại trong inject mapping), và từ điển giá trị kết quả được đưa tới provider mà capability của Recipe nêu tên — các provider helm và helm-chart đều kết xuất thông qua Helm — để kết xuất các artifact hạ tầng cơ sở.
    • Phân tích và xác thực Workload: Một Recipe khai báo workload: — nội dung khối inline, hoặc workload: { $import: <path> } nêu tên một tệp — sẽ có tài liệu đó được đánh giá như một template với ngữ cảnh kết xuất của nút, sau đó được phân tích dưới dạng YAML thành hình dạng Workload và được kiểm tra: các byte đã kết xuất được xác thực theo schema Workload, giá trị đã giải mã cũng được xác thực theo schema đó (các byte mang những khóa mà quá trình giải mã loại bỏ, và quá trình giải mã bỏ qua một trường được cung cấp rỗng, nên mỗi bên từ chối điều mà bên kia không thấy được), mọi mục attachments được kiểm tra với các khe mà featuresSchema của Component được liên kết khai báo, và mọi tham chiếu tài nguyên được kiểm tra với provides đã phân giải của khe mà nó nêu tên. Một lỗi ở đây sẽ dừng bản build. Workload đã phân tích được đặt vào ngữ cảnh template dưới dạng .workload, để một template được đánh giá sau đó trên cùng nút có thể đọc nó.
    • Đánh giá artifacts: Mọi mục mà một Recipe khai báo dưới artifacts: — nội dung inline, hoặc một tệp được nêu tên bởi $import: của chính mục đó — được đọc, phân tích template, đánh giá với toàn bộ ngữ cảnh template, và mang thông tin nguồn gốc của bản build. Hình chiếu kết quả được giao cho provider, vốn quyết định định dạng đầu ra, nơi đặt thông tin nguồn gốc, đường dẫn đầu ra và các byte cuối cùng. Mỗi tệp được phát ra ghi lại nó đến từ dạng soạn thảo nào, để một xung đột tên tệp có thể nêu tên mọi bên đóng góp.
    • Tổng hợp Workload: Workload đã phân tích được giao cho provider mà capability của Recipe nêu tên, provider này chuyển nó thành các tài nguyên gốc của chính provider đó. Một Recipe không khai báo workload: thì không có gì để tổng hợp ở đây; các tệp của nó thay vào đó đến từ việc kết xuất source.
    • Kết xuất Feature (sinh tài nguyên FeatureRecipe): Mọi phần gắn kèm trên nút mà FeatureRecipe được liên kết của nó mang source, workload, artifacts và/hoặc valuesMapping riêng — mô hình sinh tài nguyên, được dùng cho các manifest phụ trợ như ServiceMonitor, NetworkPolicy, ConfigMap của sidecar hoặc một tài nguyên cung cấp thông tin xác thực — được đánh giá trong một lượt, theo cùng thứ tự Mô hình củ hành 5 tầng mà inject mapping tuân theo. Có một trình tự duy nhất trên một tập phần gắn kèm duy nhất: một Feature vận hành và một Feature thông tin xác thực đi cùng một đường, và điều khác nhau giữa chúng là những gì FeatureRecipe của chúng phát ra. .values và .infra của mỗi phần gắn kèm được hoán đổi sang phạm vi riêng của nó; nó kế thừa .locals đã đánh giá của Recipe cơ sở; .attachment_name nêu tên instance đang được kết xuất và .provides mang các provides đã phân giải riêng của phần gắn kèm, cùng túi dữ liệu mà bên tiêu thụ đọc. Từ điển giá trị kết quả được đưa tới provider được nêu tên bởi capability riêng của FeatureRecipe, và các tệp đã kết xuất được nối vào đầu ra của ranh giới mang theo hai tọa độ — thành phần mà Feature được gắn vào, rồi tên mà nó được gắn dưới đó — để một tên Feature được gắn vào nhiều thành phần giữ mỗi lần gắn riêng biệt. Dạng mà các tọa độ đó mang tùy theo bố cục riêng của provider host: một thư mục <component>--<instance>/ bên cạnh thư mục của chính thành phần, khi đích cung cấp cho mỗi bên đóng góp một vị trí riêng, và một tiền tố tên tệp <component>--<instance>-- khi đích chỉ đọc các tệp nằm trực tiếp trong một thư mục. Các FeatureRecipes chỉ chèn — những FeatureRecipe chỉ mang injectMapping, đã được xử lý trong inject mapping — bị bỏ qua ở đây. Giống như các giai đoạn con trước đó, kết xuất feature chạy cho từng thành phần một, nên một phần gắn kèm thường được đánh giá ngay sau thành phần mà nó được gắn vào. Một phần gắn kèm có FeatureRecipe khai báo readsCallerRenderFacts: true hoặc readsTargetRenderFacts: true thì thay vào đó được đánh giá sau khi mọi thành phần, và mọi phần gắn kèm không khai báo cái nào trong hai, đã kết xuất xong — để mỗi thành phần kết nối tới host của nó, và mỗi thành phần mà host của nó được nối tới, đều đã kết xuất vào lúc đó — và đầu ra của nó được đặt ở nơi mà lẽ ra nó sẽ được đặt.
    • Pipeline plugin (thực thi bước Wasm): Trình biên dịch đọc mảng pipeline của Recipe và thực thi các bước theo thứ tự đã khai báo. Nó điều phối plugin Wasm được nêu tên của mỗi bước trên các tài liệu đã kết xuất của nút, áp dụng các thao tác JSON Patch RFC 6902 mà bước trả về lên các tài liệu mà các thao tác đó nhắm tới, và phát ra các hiệu ứng phụ của bước cùng với chúng — đây là bề mặt đứng sau các thay đổi chính xác như chèn một sidecar Envoy hoặc gắn một VolumeMount secret. Một bước có cổng when: kết xuất ra giá trị falsy sẽ bị bỏ qua như một bước chuyển tiếp, giữ nguyên tập tài liệu cho bước tiếp theo. URI plugin của mỗi bước được phân giải trước khi thực thi thành các byte artifact đã xác minh mà lockfile ghim theo digest. Các bước pipeline của một FeatureRecipe thực thi theo cùng cách, trên các tài liệu đã kết xuất riêng của phần gắn kèm và, với một phần gắn kèm ở phạm vi thành phần, cả các tài liệu của thành phần host cùng với chúng.

Cả ba loại đầu vào của Recipe đều đến được trình biên dịch: source: + valuesMapping: qua kết xuất cơ sở, workload: qua phân tích workload và tổng hợp workload, và artifacts: qua đánh giá artifacts. Việc một provider nhất định có thể được giao loại nào không được quyết định theo từng giai đoạn con — nó được xác định một lần cho mỗi nút, trước bất kỳ lần điều phối kết xuất nào, từ hợp đồng được khai báo của chính provider, nên một Recipe có loại đầu vào mà provider được liên kết không chấp nhận sẽ bị từ chối ở đó thay vì giữa chừng quá trình kết xuất. Xem 16-recipe-input-composition.md để biết mô hình kết hợp ba loại đầu vào, kind Workload và cơ chế Artifacts, và Trạng thái của ngôn ngữ để biết provider nào chấp nhận loại nào.

Đầu ra thuần GitOps

Để giữ hoàn toàn không có quan điểm riêng về cách đầu ra của nó được áp dụng, các plugin kết xuất xuất các artifact đã sinh vào một cấu trúc thư mục sạch, cô lập theo ranh giới (ví dụ: dist/boundaries/aws-core-cluster/, dist/boundaries/gcp-data-cluster/). Điều này cho phép các GitOps controller bên ngoài (như ArgoCD hoặc Flux) đồng bộ và áp dụng hạ tầng mà trình biên dịch Aggrega không bao giờ cần thông tin xác thực API của cụm đang chạy.

graph TD
    subgraph CLI_Orchestrator ["The Aggrega Compiler Pipeline"]
        direction TB
        A["Resolution — The Resolver & Syntax Validator<br/>(Inheritance Merge + Parameter Interpolation + JSON Schema 2020-12 Validation)"] --> B["Topology construction — The Topology Builder<br/>(AST Expansion + governance label-transform)"]
        
        B -->|"Emits IR Graph"| C["Graph finalization<br/>(Normalization)"]
        
        C -->|"Flat IR Graph"| D["Static analysis — The Static Analyzer<br/>(Selectors + governance ir-verdict Gate)"]
        
        D -->|"Validated Topology"| E["Rendering<br/>Inject mapping: Pre-Render Interception (injectMapping)<br/>Base rendering (valuesMapping)<br/>The plugin pipeline: Wasm Mutation (pipeline)"]
    end
graph LR
    E["Rendering"]
    E -->|"Stringified Artifacts"| F["Helm Charts"]
    E -->|"Stringified Artifacts"| G["Docker Compose"]
    E -->|"Stringified Artifacts"| H["Kubernetes Manifests"]
    E -->|"Stringified Artifacts"| I["Terraform Configuration"]
    E -->|"Stringified Artifacts"| J["CloudFormation Templates"]

Bản đồ nguồn hạ tầng

Aggrega biên dịch một Aggregate.yaml khoảng 30 dòng thành hàng nghìn dòng cấu hình JSON hoặc YAML vật lý. Nếu không có cách truy ngược một tài nguyên đang chạy về nguồn của nó, việc gỡ lỗi một sự cố tại “main.tf.json dòng 4.032” buộc nhà phát triển phải tự tái dựng ánh xạ. Các plugin kết xuất của Aggrega giải quyết điều này bằng cách hợp nhất các định danh truy vết vào bề mặt metadata gốc của provider — metadata.labels và metadata.annotations cho Kubernetes, một chú thích nguồn gốc cho Terraform, và các quy ước tương đương theo từng provider — để mỗi đối tượng được kết xuất mang một con trỏ trở về nguồn mà nó xuất phát. Nhãn aggrega.ai/compiler-version (được mô tả trong governance-and-compliance §5) là một khóa truy vết trong họ này; bên cạnh nó, dấu nguồn gốc còn mang aggrega.ai/aggregate-name, aggrega.ai/component-id, aggrega.ai/boundary-path, aggrega.ai/recipe-uri và aggrega.ai/environment, và các provider helm, helm-chart, compose, terraform và cloudformation đều phát ra nó — provider helm-chart trên các tệp template mà một Recipe thêm vào chart, vì nó sao chép nguyên vẹn các template của chính chart.

Dấu nguồn gốc không mang khóa nào xác định nguồn gốc tính năng hay loại danh mục.

Trình biên dịch còn đi kèm hai bề mặt gỡ lỗi khác. aggrega build --trace ghi trạng thái trung gian của mỗi nút, từng lượt một, vào .trace/ bên cạnh dist/, dành cho tác giả Recipe muốn xem mỗi giai đoạn đã nhận và tạo ra gì; và một chẩn đoán dừng bản build mang danh mục của bề mặt soạn thảo mà nó thuộc về — DEVELOPER_ERROR, OPS_ERROR, CATALOG_ERROR và các danh mục khác — ở bất cứ đâu lỗi có danh mục, nên nó chỉ đúng tác giả. Các lỗi truy ngược một trường manifest được sinh ra bị lỗi về dòng template đã tạo ra nó không thuộc về trình biên dịch.

Pipeline trình kiểm tra

Giai đoạn kiểm tra lược đồ của quá trình phân giải dựa trên một pipeline trình kiểm tra chuyển nội dung đặc tả thực thể (dạng rút gọn, YAML JSON Schema hoặc kết hợp) thành một tài liệu JSON Schema 2020-12 thống nhất kèm nguồn gốc theo từng lá, rồi kiểm tra nội dung thể hiện do nhà phát triển viết dựa trên tài liệu đó. Năm bước chạy theo thứ tự như các phép biến đổi thuần; mỗi bước là một hàm xác định trên các đầu vào đã khai báo của nó.

Bước 1 — Biên dịch dạng rút gọn. Trình biên dịch duyệt cây YAML của nội dung schema:, parameters: và SchemaLibrary; phân nhánh theo từng nút (lá dạng rút gọn, YAML JSON Schema, tham chiếu $ref: hay phép kết hợp); xuất ra JSON Schema 2020-12 đã phân giải. Dạng rút gọn và YAML JSON Schema có thể trộn lẫn tại bất kỳ ranh giới nút nào thông qua cơ chế thoát $jsonschema:; trình biên dịch xử lý trường hợp trộn lẫn bằng cách duyệt cây và phân nhánh theo từng nút. Phép biến đổi là một hàm thuần: cùng một đầu vào dạng rút gọn luôn tạo ra cùng một đầu ra JSON Schema. Xem language-reference/vocabulary/compact-form-authoring.md để biết bộ từ khóa.

Bước 2 — Phân giải spec.templates và $instantiate:. Với các mục SchemaLibrary được viết dưới dạng tham chiếu template, trình biên dịch duyệt mọi mục thư viện gọi $instantiate: với $args:, thay thế giá trị tham số dưới dạng thay thế scalar nguyên văn và tạo ra các mục lược đồ cụ thể. Phép thay thế chạy một lần cho mỗi lần tải thư viện; các mục đã phân giải được lưu vào bộ nhớ đệm. Xem language-reference/entities/schemalibrary.md để biết hình dạng soạn thảo của thực thể thư viện.

Bước 3 — Mở rộng $ref: liên tài liệu. Với các tham chiếu SchemaLibrary qua $ref: (dạng danh tính <Library>#/schemas/<entry>), trình biên dịch duyệt chuỗi tham chiếu tại thời điểm biên dịch bằng cách truyền theo ngăn xếp phân giải; nội dung được tham chiếu được nhúng vào lược đồ của bên sử dụng. Phép mở rộng giữ nguyên cơ chế phát hiện chu trình (chu trình dừng bản dựng với một lỗi nêu tên chuỗi), rào chắn danh tính-không-phải-vị-trí (một tham chiếu mang host registry sẽ dừng bản dựng kèm hướng dẫn dùng dạng danh tính — tham chiếu xác định thư viện theo danh tính, không theo vị trí vật lý) và phép kết hợp một nguồn duy nhất (khối $ref: chỉ chấp nhận tham chiếu trần; các ghi đè phía bên sử dụng được kết hợp qua allOf: của JSON Schema). Xem language-reference/vocabulary/cross-document-ref.md để biết ngữ nghĩa phân giải.

Bước 4 — Tổng hợp cầu nối cho featuresSchema:. Trình biên dịch duyệt nội dung featuresSchema: của mỗi thực thể theo thứ tự của tác giả và xuất ra một đoạn JSON Schema mô tả hình dạng của một phần điền có thể gắn vào từng slot đính kèm, với từ khóa mở rộng x-aggrega-inject: trên slot khai báo danh sách cho phép inject. Đoạn đó được biên dịch và kiểm tra riêng, dựa trên khối đính kèm đã viết, thay vì được gộp vào nội dung schema: dành cho nhà phát triển; từ khóa mở rộng là siêu dữ liệu mà việc kiểm tra JSON Schema bỏ qua, và không bước nào sau đó đọc lại nó từ đoạn — một kiểm tra cần danh sách cho phép của một slot sẽ đọc chính slot đó. Bảng socket usesSchema: không được chiếu vào đoạn nào cả: selector: và inject: của một socket được đọc như YAML có kiểu mà Kiến trúc sư đã viết, còn valueSchema: / infraSchema: theo từng cạnh của một socket được biên dịch riêng. Phép tổng hợp là một hàm thuần trên các đầu vào của nó.

Bước 5 — Bộ hợp nhất tùy chỉnh kèm nguồn gốc. Với các thực thể khai báo extends:, trình biên dịch duyệt chuỗi cha; JSON Schema đã phân giải của cha trở thành nền; các ghi đè của con được áp dụng lên trên. Mỗi lá trong lược đồ đã phân giải mang một thẻ nguồn gốc theo từng lá (đường dẫn tệp, số dòng, nguồn từ cha hay con). Đầu ra của bộ hợp nhất là thứ mà công cụ kiểm tra tiêu thụ; công cụ kiểm tra là một bản triển khai bên thứ ba không chỉnh sửa, tuân thủ JSON Schema 2020-12, được bao quanh bởi một bộ duyệt xác định để xuất kết quả theo thứ tự.

Năm bước chạy trước khi công cụ kiểm tra nhìn thấy lược đồ. Công cụ nhận một tài liệu JSON Schema 2020-12 duy nhất đã phân giải cùng nội dung thể hiện của nhà phát triển; nó tạo ra một báo cáo kiểm tra. Bộ định dạng lỗi tham khảo các thẻ nguồn gốc để xuất các chẩn đoán cho người dùng nêu rõ vị trí trong mã nguồn — bao gồm cả tệp gốc của một ràng buộc mà một Feature kế thừa từ lớp cơ sở thay vì tự viết.

Pipeline trình xác thực chạy ở nơi mỗi payload lần đầu tiên hoàn chỉnh — values và infra của một thành phần trong lúc phân giải, các thành phần của một aggregate con khi việc xây dựng cấu trúc liên kết đưa chúng vào, và payload của một phần gắn khi hoàn tất đồ thị — nên một phát hiện của schema sẽ dừng bản build trước khi phân tích tĩnh đánh giá bất kỳ selector nào, và trước khi đánh giá assertion, điều này cho phép các template assertion dựa vào các payload đã được xác thực.

Duy trì tính xác định xuyên suốt pipeline

Mọi bước của pipeline biên dịch đều duy trì Bất biến Đầu ra Xác định: với cùng các tệp nguồn, cùng lockfile và cùng phiên bản trình biên dịch, bản dựng tạo ra đầu ra giống hệt nhau đến từng byte. Bất biến này là nền tảng — định địa chỉ theo nội dung trong lockfile đòi hỏi digest artifact ổn định; bản dựng tái lập được đòi hỏi một bản phát hành được viết trên laptop của nhà phát triển A phải biên dịch ra cùng đầu ra trên laptop của nhà phát triển B và trên CI; khả năng xem xét diff đòi hỏi các thay đổi mã nguồn xuất hiện như những thay đổi duy nhất trong đầu ra đã biên dịch.

Tính xác định được duy trì nhờ một số ít nguyên tắc mà mọi phép biến đổi đều tuân theo:

  • Thứ tự lặp cố định. Mọi lần duyệt qua YAML dạng map đều lặp theo thứ tự cố định, vì phép lặp map gốc của Go là ngẫu nhiên. Ở hầu hết các bước, trình biên dịch sắp xếp trước khi lặp (trình biên dịch dạng rút gọn, bộ hợp nhất, bộ phân giải spec.templates, bộ định dạng lỗi, bộ tuần tự hóa YAML); riêng phép chiếu slot đính kèm thì mang theo thứ tự của chính tác giả, nên thứ tự thuộc tính của một bảng slot là thứ tự nó được viết.
  • Không nhúng thời gian. Quá trình biên dịch không nhúng dấu thời gian vào đầu ra. Một bản dựng lúc 14:00 tạo ra cùng artifact như một bản dựng lúc 2:00. Siêu dữ liệu nguồn gốc của bộ hợp nhất dùng tệp:dòng, không phải tệp:dấu thời gian.
  • Đường dẫn tương đối theo workspace. Mọi đường dẫn trong đầu ra đã phân giải đều tương đối theo workspace; lớp phân giải đường dẫn chuẩn hóa chúng trước khi đường dẫn đi vào bất kỳ đầu ra nào.
  • Không có nguồn ngẫu nhiên, không có trạng thái bên ngoài. Các phép biến đổi là hàm thuần trên các đầu vào đã khai báo (nội dung thực thể, chuỗi cha, lockfile). Trạng thái bên ngoài chỉ được tham khảo trong quá trình phân giải (tải artifact OCI), và nội dung đã phân giải được định địa chỉ theo nội dung qua digest.
  • Tuần tự hóa YAML chuẩn tắc. Với một đầu vào, đầu ra được ghi theo một dạng cố định duy nhất: cùng một thứ tự khóa ở mọi cấp độ sâu trong mọi lần chạy, với mảng và mảng enum: theo thứ tự đầu vào; thụt lề 2 dấu cách; kết thúc dòng Unix LF; chuỗi không có dấu ngoặc kép ở những nơi YAML cho phép; dạng boolean true/false; null được lược bỏ với các trường vắng mặt.
  • Thứ tự bảng chữ cái của $defs:. Các mục $defs: của lược đồ được xuất theo thứ tự khóa bảng chữ cái trong JSON Schema đã phân giải. Về mặt khái niệm, $defs: là một từ điển, không phải danh sách có thứ tự; thứ tự bảng chữ cái giúp diff dễ dự đoán qua các lần tổ chức lại mã nguồn.
  • Song song không lộ ra ở đầu ra. Trình biên dịch có thể song song hóa các đơn vị độc lập (các thực thể khác nhau có thể biên dịch đồng thời). Kết quả song song được gom vào một cấu trúc xác định (ví dụ: sắp xếp theo tên thực thể) trước khi được tuần tự hóa.

Các bài kiểm thử đầu cuối của trình biên dịch biên dịch mỗi fixture nhiều lần trong một bài kiểm thử và khẳng định rằng mọi lần chạy đều xuất ra cùng các tệp với nội dung giống hệt từng byte. Chính việc lặp lại quá trình biên dịch mới bắt được rò rỉ thứ tự lặp map hoặc phép lặp trên một tập hợp chưa sắp xếp, vốn cho đầu ra ổn định ở hầu hết các lần chạy và thỉnh thoảng mới khác đi. Các bài kiểm thử chạy cùng phần còn lại của bộ kiểm thử của trình biên dịch.

Bất biến Đầu ra Xác định áp dụng tại thời điểm dựng: cùng các tệp nguồn + cùng lockfile + cùng phiên bản trình biên dịch cho ra đầu ra giống hệt nhau đến từng byte. Thuộc tính đi kèm tại thời điểm khóa (cùng các tệp nguồn + cùng trạng thái registry cho ra cùng lockfile) yếu hơn — registry có thể thay đổi (phiên bản mới có thể được phát hành; sidecar có thể được thêm vào; siêu dữ liệu theo từng thành phần có thể thay đổi), nên hai lần gọi khóa trên cùng các tệp nguồn ở những thời điểm khác nhau có thể tạo ra các lockfile khác nhau. Đó chính là mục đích của lockfile, giống các quy ước trong npm, Cargo và Go. Từ một lockfile mới, bản dựng tạo ra đầu ra xác định. Việc tách hai thời điểm này là điều khiến tính thay đổi phía registry có thể chấp nhận được: một sidecar được phát hành tại thời điểm T2 làm thay đổi lần gọi khóa tiếp theo; nó không làm thay đổi các bản dựng dựa trên lockfile được tạo tại T1.