Các bất biến kiến trúc
Tám bất biến này là các quy tắc nền tảng của Aggrega. Chúng có hiệu lực qua mọi bản phát hành, trong lõi trình biên dịch, tầng lược đồ, danh mục và bề mặt plugin Wasm. Mọi quyết định thiết kế, mọi tính năng và mọi thực thể được soạn thảo đều tôn trọng chúng.
Các chương kiến trúc khác tham chiếu các bất biến theo số thứ tự. Khi một chương sau nói “theo Bất biến 2” hoặc “theo quy tắc String Pipe (Bất biến 3)”, nó trỏ về đây.
1. Trình biên dịch trung lập về nội dung, không có quan điểm riêng và không phụ thuộc vào ý định của người dùng
Trình biên dịch Aggrega là một bộ định tuyến văn bản Ahead-Of-Time (AOT). Nó phân tích YAML, duyệt đồ thị, đánh giá giao của các nhãn và chuyển chuỗi từ nguồn đến đích. Nó không kiểm soát những gì tác giả đặt vào values, parameters, infra, provides hoặc locals. Nó không áp đặt các quy ước đặt tên, quy ước cổng hay các nhãn ngữ nghĩa mà một Architect nghĩ ra.
Nhiều quy tắc nghe như quy tắc của trình biên dịch — hợp đồng Zero-Port, phong cách danh mục Naked-Base / Flavored-Edges, việc chọn nguyên hàm vận hành nào phù hợp với một thành phần nhất định — thực chất là khế ước xã hội: các thực hành tốt nhất có lối thoát, được các kiến trúc sư nền tảng soạn danh mục thư viện chuẩn duy trì. Trình biên dịch không diễn giải chúng.
Bất biến này nói về những gì trình biên dịch suy ra từ nội dung bạn viết, và phạm vi đó là toàn bộ nội dung của nó. Một số ít khóa thuộc về chính Aggrega — được dành riêng, với các giá trị chúng chấp nhận được ghi trong schema đã công bố — và schema kiểm tra chúng giống như kiểm tra mọi trường được khai báo khác. component.aggrega.ai/type là một trong số đó: tập giá trị của nó là đóng, và tài liệu mang giá trị nằm ngoài tập đó bị từ chối khi được tải. Đó là nền tảng tuyên bố ý nghĩa của khóa riêng của nó, chứ không phải trình biên dịch gán ý nghĩa cho một chuỗi bạn viết, và mọi khóa của riêng bạn vẫn hoàn toàn không bị kiểm soát đúng như bất biến này nói. Một catalog phân loại các thành phần theo một trục mà Aggrega không định nghĩa sẽ viết khóa nhãn riêng, được schema chấp nhận với bất kỳ giá trị chuỗi nào và được mọi bề mặt bộ chọn đọc giống hệt nhau.
Những gì trình biên dịch thực sự áp đặt là hẹp: xác thực lược đồ, phân tích cú pháp YAML, xây dựng đồ thị, đánh giá mẫu và việc định tuyến văn bản thuần túy của hợp đồng tiêm. Mọi thứ khác là quy ước, được áp dụng tại thời điểm soạn danh mục hoặc bên trong socket quản trị Wasm tùy chọn.
Các doanh nghiệp viết catalog nội bộ của riêng mình được tự do một cách rõ ràng để phá vỡ các quy ước của thư viện chuẩn. Trình biên dịch chấp nhận bất cứ thứ gì họ viết miễn là nó vượt qua xác thực schema. Kiến trúc khuyến khích các thực hành tốt nhất; nó không xây nhà tù.
2. Tính thuần khiết AOT: trình biên dịch không truy cập được thông tin runtime
Aggrega là một trình biên dịch Ahead-Of-Time. Tại thời điểm biên dịch:
- Nó không xác thực với các API đám mây.
- Nó không lấy địa chỉ IP thực tế, tên DNS hay URL do đám mây tạo ra.
- Nó không phân giải secret thành văn bản thuần — secret vẫn là con trỏ siêu dữ liệu xuyên suốt Biểu diễn trung gian (Intermediate Representation).
- Nó không biết trạng thái runtime của các cluster hay dịch vụ đích.
- Nó không thể lấy dữ liệu chưa tồn tại (endpoint sau khi cấp phát, cổng được gán động, tên tài nguyên được tạo tự động).
Bất cứ thứ gì phụ thuộc vào trạng thái runtime đều được biểu diễn dưới dạng chuỗi con trỏ tất định — một tên DNS ổn định, một chuỗi nội suy Terraform, một tham chiếu tài nguyên CloudFormation — do Ops Recipe cung cấp. Trình biên dịch chuyển tiếp con trỏ mà không phân giải nó. Môi trường runtime (cluster, trình quản lý trạng thái IaC) phân giải dữ liệu vật lý cuối cùng.
Đây là Đảo ngược điều khiển thực sự (True Control Inversion): nhà phát triển quy định một Injection Contract trong Aggregate, trình biên dịch nối các con trỏ tất định từ trước, và môi trường runtime phân giải dữ liệu vật lý cuối cùng. Các yêu cầu thực sự cần phân giải lúc runtime thuộc về pipeline Wasm của một Ops Recipe, không thuộc lõi trình biên dịch.
3. String Pipe: trình biên dịch không thể suy ra ý nghĩa
Trình biên dịch không diễn giải ý nghĩa của các giá trị được truyền qua. Khi Component A sử dụng Component B, trình biên dịch lấy giá trị vô hướng mà Recipe của Component B tạo ra qua provides — một chuỗi, một số hoặc một giá trị boolean — và truyền nó vào ngữ cảnh Recipe của Component A, được chuyển thành chuỗi một cách tất định tại ranh giới tiêm. Giá trị đó là FQDN, tên máy chủ cục bộ, địa chỉ IP dạng chữ, số cổng hay DSN được định dạng bởi Wasm đều không tạo ra khác biệt: trình biên dịch không xác thực khả năng định tuyến, tính đúng đắn của giao thức hay sự phù hợp ngữ nghĩa.
Có hai hệ quả:
- Trình biên dịch không đoán mục đích của thành phần từ tên. Một thành phần tên là
database-productionkhông được nhận diện là cơ sở dữ liệu. Các nhãn loại ngữ nghĩa nhưcomponent.aggrega.ai/type(khi có) là siêu dữ liệu mờ dùng để khớp nhãn, không phải logic rẽ nhánh của trình biên dịch. - Trình biên dịch không phân biệt hostname với tên cơ sở dữ liệu, với số cổng hay với một giá trị mờ tùy ý. Tất cả đều là các mục vô hướng trong ngữ cảnh tiêm, được chuyển giao dưới dạng chuỗi.
Bộ ba topology — provides trên Recipe sản xuất, uses trên Aggregate tiêu thụ, inject trên cạnh — chính là Injection Contract. Trình biên dịch đánh giá nhãn và chuyển chuỗi; việc diễn giải là hợp đồng biên soạn giữa Recipe và Component.
4. Không có hạ tầng ma: trình biên dịch không bao giờ tự bịa ra tài nguyên tính toán hay tính năng
Trình biên dịch không bao giờ âm thầm chèn tài nguyên tính toán, Features, chú thích, proxy định tuyến hay bất kỳ tài nguyên nào khác mà tác giả không khai báo rõ ràng. Vi phạm chính sách tạo ra rào chắn ồn ào (Loud Guardrails) — bản build dừng lại với một lỗi cụ thể cho tác giả biết cần sửa gì, trong chính tài liệu họ đã viết — chứ không phải những thay đổi âm thầm gây ra bí ẩn hạ tầng khi gỡ lỗi.
Tài nguyên đi vào đồ thị thông qua các khai báo rõ ràng tại thời điểm biên soạn:
- Aggregate của nhà phát triển (các thành phần, các cạnh
uses, các liên kết Feature). - Các liên kết Feature của Release (phần bổ sung ở cấp vận hành viên).
- Mở rộng theo chú thích (Manifest khai báo các ràng buộc chú thích → Feature; chú thích trên một Component hoặc một ranh giới là khai báo rõ ràng).
- Sản xuất tài nguyên ở cấp Recipe: việc kết xuất
sourcecủa Recipe tạo ra artifact chính; quá trình tổng hợpworkloadphát ra dạng triển khai đặc thù của provider (Pod spec, dịch vụ Compose, v.v.); các mụcartifacts:(nội tuyến hoặc nạp bằng$import:) phát ra các manifest phụ trợ nội tại của Recipe; Tạo tài nguyên FeatureRecipe phát ra các tài nguyên phụ trợ theo từng Feature, được kích hoạt bởi một liên kết Feature rõ ràng.
Các đường dẫn ở cấp Recipe là khai báo tại thời điểm biên soạn cách một bước: tác giả Recipe viết source / workload / artifacts / valuesMapping theo một hợp đồng Component, và Aggregate của nhà phát triển chọn những Components nào tham gia. Một tài nguyên xuất hiện trong đầu ra đã kết xuất đều truy ngược được về một khai báo trong Aggregate, trong Release hoặc trong một ràng buộc chú thích, hoặc về phần biên soạn Recipe mà các loại thành phần của Aggregate đã chọn.
Tổng hợp biến đổi các dạng do tác giả khai báo thành các định dạng đầu ra đặc thù của provider. Một Workload spec được viết dưới dạng một map các container có thể được kết xuất thành Kubernetes Pod spec, một khối dịch vụ Compose hoặc một module Terraform — phép biến đổi do provider điều khiển, nhưng tài nguyên vẫn truy ngược được về khai báo Workload của tác giả.
Socket quản trị mang một vai trò cho mỗi liên kết, và chính vai trò — không phải loại plugin — quyết định một liên kết được phép làm gì với một bản build. Một plugin quản trị được liên kết ở vai trò phán quyết — xem xét đồ thị IR (ir-verdict) hoặc các artifact đã kết xuất (render-verdict) — có thể từ chối một bản build nhưng không thể thay đổi nó. Nếu một phán quyết như vậy muốn thêm một tài nguyên, nó làm bản build thất bại kèm chỉ dẫn khắc phục để tác giả tự thêm tài nguyên đó; host chỉ đọc đầu ra của phán quyết như chấp nhận hoặc từ chối và không bao giờ áp dụng nó như một thay đổi, vì vậy việc viết lại đồ thị cho tuân thủ mà không được mời — chính là hạ tầng ma mà bất biến này cấm — không thể đến từ vai trò phán quyết. Một plugin quản trị được liên kết ở vai trò biến đổi (label-transform hoặc annotation-transform) là ngoại lệ hẹp và rõ ràng: vận hành viên liên kết nó — theo lựa chọn, thông qua cấu hình plugins.governance của workspace — đã khai báo phép biến đổi đó, nên các thay đổi nó tạo ra là khai báo rõ ràng, có cùng vị thế với mở rộng theo chú thích, không phải chèn âm thầm. Điểm phân biệt là lời mời: một phán quyết không được yêu cầu thì không được viết lại bản build, còn một phép biến đổi được liên kết rõ ràng thì được, vì vận hành viên đã yêu cầu nó. Vì phép biến đổi định hình đầu ra đã kết xuất, nó được ghim trong lockfile như mọi plugin định hình đầu ra — phép biến đổi được áp dụng được cố định tại thời điểm pull, nên thay đổi nó nghĩa là pull lại chứ không phải một sự dịch chuyển âm thầm giữa các bản build; phán quyết không định hình đầu ra nào và không được ghim.
5. Aggregate là bề mặt biên soạn; Release không thể khai báo values:
Schema của Release cấm một khối values: một cách cơ học. Vận hành viên không thể viết values lên một Component hay một Feature từ một Release. Đây là sự áp đặt của schema ở cấp JSON Schema — không phải khế ước xã hội, không phải quy ước — và nó ồn ào: mọi tài liệu thực thể đều được xác thực theo schema của loại của nó khi được tải, nên một Release mang values: sẽ dừng bản build với một chẩn đoán nêu rõ tệp và khóa vi phạm, thay vì bị bỏ qua âm thầm.
Điều này không có nghĩa là các giá trị giống hệt nhau ở mọi môi trường. Con đường được hỗ trợ cho biến thể theo môi trường là Nâng tham số (Parameter Hoisting):
- Nhà phát triển cung cấp một trường có kiểu
parameters.*trong Aggregate. - Template
valuescủa Component tham chiếu đến nó:storage_size: "{{ .parameters.db_size }}". - Release cung cấp giá trị cho tham số:
parameters: { db_size: "100Gi" }. - Đầu ra đã kết xuất phản ánh giá trị đặc thù của môi trường.
Aggregate vẫn là Nguồn sự thật duy nhất về việc giá trị nào được cung cấp cho biến thể theo môi trường (khai báo parameters) và cách chúng chảy vào các giá trị của thành phần (tham chiếu trong template). Release cung cấp giá trị; nó không ghi đè.
Hai ràng buộc khác bảo vệ cùng bất biến này:
- Khi một Release dùng
extends, việc khai báo một con trỏaggregate:bị schema cấm. Release con phải triển khai cùng Ý định của nhà phát triển (Developer Intent) với Release cha. - Release không thể đưa vào tài nguyên tính toán mà Aggregate chưa khai báo, và không thể đổi đích của một cạnh mà nhà phát triển đã khai báo. Trong phạm vi các socket mà Architect đã khai báo, Release có thể nối và cấu hình các cạnh giữa các thành phần hiện có: nó đặt
infratheo cạnh trên một cạnh do nhà phát triển nối, hoặc nối một cạnh đi vào socket đã khai báo nhưng chưa ràng buộc tới một thành phần hiện có. Nó không thể khai báovaluestheo cạnh (chúng vẫn nằm trong Aggregate), ràng buộc một socket màusesSchemacủa Component không khai báo, hay trỏ một cạnh tới một thành phần không tồn tại — mỗi trường hợp đều dừng bản build. Hãy lưu ý mệnh đề ở giữa muốn nói đến khai báo nào: socket phải xuất hiện trongusesSchemacủa Component trong catalog. Tác giả Aggregate có thể đặt tên một socket mà loại thành phần của họ không khai báo, còn bề mặt Release cố ý không được mở theo cùng cách — vận hành viên nối và cấu hình bên trong một kiến trúc thay vì tự nghĩ ra một kiến trúc.
Cấu hình kết nối theo cạnh có phạm vi ở phía tiêu thụ: values và infra mang trên một cạnh chỉ xuất hiện trong ngữ cảnh kết xuất của nút đã viết cạnh đó, không bao giờ trong ngữ cảnh của đích. Vì vậy, đầu ra đã kết xuất của chính một thành phần là bất biến đối với các kết nối mà các thành phần khác tạo tới nó — việc nối hay cấu hình một cạnh tới một đích không bao giờ làm xáo trộn những gì Recipe của đích kết xuất. Nơi duy nhất các kết nối đó hiển thị là một Feature được liên kết với đích: FeatureRecipe của nó có thể đọc những thành phần nào dùng đích, nên các tài nguyên nó phát ra — chẳng hạn một chính sách cho phép đúng những bên gọi đã khai báo — đi theo các kết nối, còn đầu ra của chính đích thì không. Ngay cả ở đó, values và infra theo cạnh vẫn ở lại với phía tiêu thụ.
6. Ranh giới ABI WebAssembly: trí tuệ đặc thù miền nằm trong Wasm
Tệp nhị phân host Go không chứa bất kỳ logic nào đặc thù cho đám mây hay hạ tầng. Mọi trí tuệ đặc thù miền, việc kết xuất template và định dạng đều nằm nghiêm ngặt bên trong các plugin WebAssembly do runtime Wazero nhúng thực thi. Host Go điều phối pipeline và chuyển payload qua ABI tới các guest Wasm dưới dạng con trỏ bộ nhớ, theo kiểu mã hóa mà mỗi socket mang.
Có hai hệ luận:
- Logic đặc thù Provider (kết xuất đặc thù Helm, định dạng đặc thù Terraform, gộp đặc thù Compose) không bao giờ nằm trong lõi trình biên dịch Go. Trình biên dịch phân giải tên provider mà một Recipe khai báo trong
spec.capabilitythành Plugin kết xuất provider phục vụ nó và điều phối nút tới plugin đó; bản thân việc chuyển đổi chạy hoàn toàn trong guest Wasm. Host không chứa mã Go riêng cho từng provider đối với một provider chuẩn, nên trong tiến trình không có gì để dự phòng — một tên provider không phân giải được tới Plugin nào phục vụ nó sẽ dừng bản build thay vì kết xuất một mặc định tích hợp nào đó. - Logic chính sách (quy tắc bảo mật, kiểm tra tuân thủ, tính toán FinOps) không bao giờ nằm trong lõi trình biên dịch Go. Chính sách thuộc về socket quản trị Wasm mà các doanh nghiệp chọn bật — một plugin được liên kết ở vai trò phán quyết (
ir-verdict/render-verdict) để chấp nhận hoặc từ chối một bản build, hoặc ở vai trò biến đổi (label-transform/annotation-transform) để định hình nhãn hoặc chú thích.
Ranh giới ABI giữ cho lõi Go gọn nhẹ, kiểm toán được và không phụ thuộc đám mây. Thay logic kết xuất của một provider là thay một artifact Wasm, không phải biên dịch lại chính Aggrega.
7. Tách biệt mối quan tâm (phân chia bốn miền) — định hướng, không phải nhà tù
Định hướng thiết kế của Aggrega tách việc biên soạn thành bốn miền:
- Developer Intent — Aggregate.
- Platform Architect — các thực thể catalog Component và Feature.
- Platform Ops — Recipe, FeatureRecipe, Plugin (bao gồm Plugin kết xuất provider).
- Platform Operator — Manifest, Release.
Một bản triển khai điển hình và vận hành tốt tuân theo sự phân chia này: nhà phát triển viết ý định ứng dụng, không viết hạ tầng vật lý; đội Ops viết hạ tầng vật lý, không viết logic ứng dụng. Aggrega được thiết kế để dùng theo cách này, và tài liệu chính thức, các ví dụ cùng catalog thư viện chuẩn đều được biên soạn theo sự phân chia này.
Phân chia bốn miền là định hướng và khung thiết kế, không phải sự áp đặt của trình biên dịch. Trình biên dịch (theo Bất biến 1) không có quan điểm riêng. Người dùng được tự do:
- Gộp vai trò (một người viết cả Aggregates lẫn Recipes).
- Trộn lẫn mối quan tâm (các Architect gán cứng nhãn tuân thủ trực tiếp lên các Components
core/*khi catalog doanh nghiệp đòi hỏi). - Vượt qua ranh giới miền (nhà phát triển dùng Nâng tham số để đưa các mối quan tâm hạ tầng vào Aggregate khi mã cũ đòi hỏi).
Trình biên dịch chấp nhận mọi mẫu biên soạn vượt qua xác thực schema. Kiến trúc khuyến khích các thực hành tốt nhất; các ràng buộc ở cấp schema (như lệnh cấm values: trong Release ở Bất biến 5) là những lần vượt miền duy nhất mà trình biên dịch thực sự từ chối. Mọi sự tách biệt khác là một khế ước xã hội do các tác giả catalog duy trì, và ở nơi doanh nghiệp chọn bật, do socket quản trị Wasm duy trì.
8. Đầu ra tất định
Với đầu vào giống hệt nhau, trình biên dịch tạo ra đầu ra giống hệt nhau đến từng byte. Hai lần biên dịch cùng một Aggregate + Release + Manifest với cùng một catalog cho ra các artifact đã kết xuất bằng nhau từng byte.
Đây là hợp đồng mà các công cụ GitOps và quy trình review dựa trên diff dựa vào. Một pull request không thay đổi đầu vào thì không nên tạo ra diff nào trong đầu ra đã kết xuất. Một pull request có thay đổi đầu vào chỉ nên hiển thị diff mà thay đổi đó hàm ý — không sắp xếp lại giả tạo, không xáo trộn dấu thời gian, không có tạp phẩm do duyệt map.
Đầu ra tất định được duy trì qua ba nguyên tắc:
- Map theo thứ tự của tác giả: mọi map có thứ tự duyệt có thể ảnh hưởng đến đầu ra đã kết xuất đều dùng một container map có thứ tự, để việc duyệt theo thứ tự khai báo của tác giả thay vì thứ tự băm.
- Không có nội dung theo đồng hồ thực hay ngẫu nhiên trong các artifact đã kết xuất, trừ khi tác giả chủ động chèn vào qua đầu vào template.
- Kết xuất là thuần túy: cùng một lần gọi guest Wasm với cùng đầu vào cho ra cùng đầu ra.
Cờ --trace của trình biên dịch (xem language-reference/cli/aggrega-build.md) cho tác giả và vận hành viên một bề mặt xác minh cho bất biến này. Hai lần biên dịch cùng đầu vào với --trace được bật tạo ra các bản dump trace giống hệt nhau từng byte; bất kỳ diff nào ở một lượt đều khoanh vùng một lỗi hồi quy. Tính tất định không chỉ là thuộc tính tại thời điểm phát hành — nó quan sát được ở mọi trạng thái trung gian của trình biên dịch thông qua bố cục trace theo từng nút.
Đầu ra tất định là hợp đồng giúp Aggrega an toàn khi dùng làm nguồn sự thật trong một vòng lặp GitOps.
Phạm vi bất biến qua các tầng phân giải
Bảo đảm đầu ra giống hệt từng byte áp dụng cho các artifact được ghim trong lockfile — các thực thể được phân giải thông qua các artifact registry có digest được lockfile ghi lại (tầng registry trong mô hình phân giải thực thể ba tầng). Khi một bản build đọc các tệp mà một Release nêu theo đường dẫn (đường dẫn cục bộ bắt đầu bằng ./ hoặc ../) hoặc các thực thể trong thư mục catalog của workspace (catalog_dirs:, ở tầng workspace và bộ nhớ đệm), tính bất biến phụ thuộc vào việc các tệp đó không thay đổi giữa các bản build. Lockfile ghi lại một thực thể trong thư mục catalog của workspace bằng digest của tài liệu của nó và các tệp nó khai báo, nên bản build sẽ dừng lại ở một thực thể đã thay đổi kể từ lần pull thay vì kết xuất nó — với một ngoại lệ: một Recipe hoặc FeatureRecipe mà Manifest đặt tên bằng một tham chiếu đồng thời là tên của một Component hoặc Feature sẽ được ghi dưới tham chiếu đó như Component hoặc Feature đó, nên các đầu vào của nó chỉ được giữ bởi các ghim bên cạnh nó trong lock, và một chỉnh sửa trên chính tài liệu của nó không bị phát hiện. Giữ nguyên các tệp như cũ là trách nhiệm của hệ thống quản lý mã nguồn (thường là Git).
Một tham chiếu đường dẫn cục bộ có tệp nền thay đổi giữa hai lần biên dịch sẽ tạo ra một diff hợp lệ trong đầu ra đã kết xuất dù hình dạng đầu vào của trình biên dịch không đổi — bảo đảm đầu ra tất định vẫn được giữ (cùng đầu vào byte → cùng đầu ra byte), nhưng các đầu vào khác nhau vì tệp cục bộ đã thay đổi. Những catalog cần tính bất biến giữa các bản build cho mọi nguồn sẽ kéo artifact từ registry vào bộ nhớ đệm được lockfile ghim thay vì đọc chúng từ một đường dẫn cục bộ hoặc một thư mục workspace; lockfile là mỏ neo của tính đồng nhất từng byte.