Ví dụ chạy được
Để bắt đầu, Bắt đầu cài đặt Aggrega và đi qua hai trong số các ví dụ này từng bước một.
Các workspace hoàn chỉnh, có thể fork, mà bạn biên dịch được bằng CLI aggrega. Mỗi ví dụ là một thư mục khép kín — một Aggregate do Developer viết và một hoặc nhiều cặp Release/Manifest — build được mà không cần thiết lập gì ngoài những gì trang của nó nêu. Để tìm một ví dụ theo sản phẩm nó triển khai hoặc theo những gì nó minh họa, hãy dùng Ví dụ theo sản phẩm và khả năng, trang liệt kê mọi ví dụ ở đây.
Các ví dụ có hai chế độ — hai đầu của cùng một lộ trình học:
-
Sử dụng — workspace tham chiếu các thực thể catalog của thư viện chuẩn và chỉ tự viết cục bộ nội dung riêng phục vụ việc giảng dạy. Nó build mà không cần cờ
--catalog:Terminal window aggrega build --release release.yamlCác thực thể được tham chiếu đó được đọc từ đâu tùy thuộc vào workspace. Một thư mục
catalog/ở gốc workspace luôn được đọc, dù có gì nêu tên nó hay không, nên một workspace tự viết nội dung giảng dạy có thể đơn giản giữ nội dung đó ở đó. Một workspace có.aggrega-config.yamlcũng đọc mọi thư mục liệt kê dướicatalog_dirs, mỗi thư mục là một nơi nó giữ thực thể. Các thư mục được liệt kê được tìm trước vàcatalog/sau cùng, và chồng tìm kiếm theo kiểu khớp-đầu-tiên-thắng, nên một thực thể trong một thư mục được tìm sớm hơn sẽ che khuất thực thể cùng định danh trong thư mục sau. Những gì không thư mục cục bộ nào khai báo — các thực thể của thư viện chuẩn — được phân giải từ registry mà cấu hình nêu làdefault_registry, tứchub.aggrega.ai. Một workspace không tự viết gì cục bộ thì không cần mục cục bộ nào, và một workspace không có cả thư mụccatalog/lẫn.aggrega-config.yamlsẽ phân giải hoàn toàn qua registry đã cấu hình. Viếtcatalog_dirslà một danh sách rỗng nghĩa là workspace không có catalog cục bộ nào. Mọi đường dẫn trongcatalog_dirsđều chỉ tới một thư mục bên trong workspace, nên một bản sao của toàn bộ workspace đặt ở nơi khác vẫn build được nguyên trạng.Một workspace nhiều đích giữ một catalog riêng cho mỗi đích sẽ nêu các thư mục của từng đích dưới
workspace.releases, với khóa là tệp Release của nó, để mọi Release đều được build dựa trên catalog riêng của mình. -
Viết — workspace xây dựng các thực thể catalog (Components, Features, Recipes) từ đầu trong các thư mục
catalog-*/cục bộ.mariadb-adminerlà ví dụ viết mẫu; các thực thể nó xây dựng cùng loại với những thực thể mà các ví dụ sử dụng dùng đến.
Mỗi lần chạy, build một release bằng aggrega build --release <release file>; trang của mỗi ví dụ đưa ra các lệnh riêng của nó. Workspace cung cấp catalog của nó như mô tả ở trên; hãy tự truyền --catalog cho một thư mục catalog mà workspace không chỉ định, như các trang cần đến điều đó trình bày.
Lockfile được sinh ra chứ không được phát hành kèm, nên một bản clone mới không có lockfile và lần build đầu tiên cần một lockfile. aggrega build mặc định chỉ đọc: khi không có lockfile nó dừng lại và nêu hai cách tiếp tục. Truyền --auto-pull cho lần build đầu đó — aggrega build --release release.yaml --auto-pull — để phân giải lockfile trong lúc build; chạy aggrega pull --release <release file> một lần trước đó cũng có tác dụng như vậy và cho mọi lần build sau chạy mà không cần cờ.
Trong một bản checkout của kho tài liệu, phần lớn các workspace còn mang theo một script trợ giúp build-release.sh mà các bước kiểm tra của chính kho dùng để build. Nó chạy aggrega build cho một release, in ra lệnh trước, và báo cáo đã dùng binary aggrega nào cùng nguồn gốc của binary đó; đặt AGGREGA_BIN để chọn binary. Một bản sao do aggrega scaffold --example ghi ra mang theo script trợ giúp nhưng không có script dùng chung mà nó gọi, vì vậy hãy build bản sao như vậy trực tiếp bằng aggrega build.
Khi một ví dụ ở đây nêu một bản checkout catalog thư viện chuẩn, Nhập cho biết nơi lấy bản đó.
Những ví dụ này bổ sung cho các trang khái niệm được mô tả trong Tổng quan ví dụ: một trang khái niệm giải thích một ý tưởng và liên kết tới workspace thể hiện ý tưởng đó; các workspace ở đây là những stack hoàn chỉnh mà bạn có thể build, đọc và điều chỉnh.
Khi một trang in ra những gì một bản build tạo ra, khối đó được sao chép từ một lần chạy thật để bạn có thể so sánh kết quả của mình với nó — và mọi dòng bị lược bỏ đều được đánh dấu. Đọc kết quả trên các trang này nêu quy ước đó và dấu mà nó dùng.
Không phải mọi thư mục ở đây đều là một workspace. Các ví dụ quickstart chứa một workspace cho mỗi bước, và các ví dụ import chứa một workspace cho mỗi giai đoạn của một lần import, như đoạn tiếp theo mô tả. Một thư mục hoàn toàn không chứa workspace nào: policy-in-ci chứa hai script quy tắc đọc thư mục kết quả của một bản build và từ chối nó khi nó vi phạm một quy tắc, kèm bước pipeline cho mỗi script. Chúng chạy trên kết quả của các workspace ở đây, và trên kết quả của bạn.
Mỗi ví dụ import-* — được liệt kê dưới khả năng import trong Ví dụ theo sản phẩm và khả năng — giữ một dự án được viết bằng định dạng khác đúng như aggrega import gặp nó, trong hai thư mục: source/, dự án, .aggrega-config.yaml biến nó thành một workspace và tệp câu trả lời mà lần import đọc các giá trị không nguồn nào có thể chứa; và draft/, các tệp mà lần import đã ghi, không thay đổi, một workspace build được đúng như đã viết, cùng với những gì nó in ra đầu ra chuẩn (stdout.txt) và lỗi chuẩn (import.txt). Hướng dẫn từng bước của nó trong Import dạy từng giai đoạn. check.sh của nó chạy scripts/check-import-example.sh dùng chung của kho mã này, script này import lại, so sánh những gì nó ghi và in ra với draft/ và các khối mà hướng dẫn trích dẫn với các tệp của ví dụ, rồi xác thực và build Release đã được soạn thảo.
Thứ tự học
Mỗi ví dụ ở đây có một vị trí trong một thứ tự học duy nhất, được xác định bởi tier và position trong phần header của nó: theo từng tầng, theo thứ tự mà danh sách tầng đưa ra, và trong mỗi tầng thì ví dụ đơn giản nhất đứng trước. Theo thứ tự học liệt kê mọi ví dụ theo cách đó, và mục Ví dụ của thanh bên cũng theo cùng thứ tự. Hãy đọc các tầng từ trên xuống dưới, hoặc chuyển thẳng tới tầng phù hợp với việc bạn đang làm; để tìm một ví dụ theo thứ nó triển khai hoặc thứ nó thể hiện, cùng trang đó liệt kê các ví dụ theo sản phẩm và theo khả năng.
Một bản build cũng có thể chạy plugin trên những gì nó render — xem Khi nào nên dùng một bước pipeline.
Phần đầu của mỗi ví dụ
README của mỗi ví dụ mở đầu bằng một phần đầu ngắn, viết dưới dạng YAML front matter, cho biết ví dụ là gì: cấp độ của nó, vị trí của nó trong thứ tự học, các sản phẩm nó triển khai và những gì nó minh họa. Ví dụ theo sản phẩm và khả năng được sinh ra từ các phần đầu này.
---example: level: start tier: catalog-only position: 1 products: [core/datastore/mariadb, core/devtool/adminer] shows: [connections, credentials]---level là một trong các cấp độ sau:
start— cấp “Chỉ catalog”: được lắp ráp từ các thực thể catalog, không viết gì ngoài Aggregate, Manifest và Release.authoring— cấp “Soạn thảo”: tạo một Component, một Feature hoặc một Recipe, hoặc cho thấy cấu trúc của chúng.advanced— cấp “Nâng cao”: boundary, chính sách quản trị, Features dựa trên annotation và các stack đám mây được lắp ráp.
tier là phần của thứ tự học mà ví dụ thuộc về, một trong các nhóm sau, được dạy theo thứ tự này:
start-here— Bắt đầu tại đây: hai ví dụ mà hướng dẫn “Bắt đầu” phát triển từng bước một, sau đó là hai ví dụ khởi đầu cho đám mây.catalog-only— Chỉ dùng catalog: được lắp ráp từ các thực thể catalog, không viết gì ngoài Aggregate, Manifest và Release.authoring— Soạn thảo: viết một Component, một Feature hoặc một Recipe của riêng nó, hoặc cho thấy cấu trúc của một thực thể như vậy.advanced— Nâng cao: ranh giới, chính sách quản trị, các Features điều khiển bằng chú thích và các stack đám mây được lắp ráp, nhiều thứ trong số đó được kết hợp trong một lần build.importers— Trình nhập: một dự án viết ở định dạng khác, đượcaggrega importsoạn nháp thành các tệp Aggrega, rồi được xem xét và build.
position là vị trí của ví dụ trong nhóm của nó, một số nguyên dương mà không ví dụ nào khác của nhóm đó dùng; một nhóm liệt kê các ví dụ của nó từ vị trí thấp nhất trở lên, ví dụ đơn giản nhất trước.
products liệt kê mỗi Component của catalog mà ví dụ triển khai, theo tên mà mục catalog của nó mang. Một component tính toán chung (chẳng hạn core/compute/server) và một thực thể mà ví dụ tự khai báo cho mình không được liệt kê, nên một ví dụ có thể không liệt kê gì.
shows liệt kê những gì ví dụ minh họa, mỗi mục lấy từ danh sách này:
multi-target— một Aggregate được build cho hai đích trở lên, hoặc được hiện thực theo hai cách trở lên.recipe-selection— Manifest chọn Recipe nào hiện thực một component, hoặc FeatureRecipe nào hiện thực một attachment: theo loại, theo instance hoặc theo đích.modules— một Aggregate trong catalog được nhập dưới dạng module.connections— các component được nối qua socketuses, với giá trị được chuyển qua mỗi cạnh.credentials— các attachment thông tin xác thực và cách mỗi đích phân phối chúng.parameters— các giá trị được nâng lên thành tham số mà một Release đáp ứng.features— các Features được đính kèm cho mục đích khác ngoài thông tin xác thực, chẳng hạn định tuyến, giám sát, ngân sách, cache hoặc che dữ liệu.boundaries— các component hoặc module được đặt trong boundary, và những gì đi qua giữa chúng.policy— chính sách quản trị chấp nhận hoặc từ chối một bản build, trong quá trình build hoặc trên đầu ra của nó.guardrails— một Release được thiết kế để dừng, và thông báo mà nó đưa ra khi dừng.catalog-authoring— một Component, Feature hoặc Recipe được viết cho ví dụ, đặt cạnh nó hoặc công bố lên catalog.cloud-infrastructure— đầu ra Terraform hoặc CloudFormation cho các dịch vụ đám mây được quản lý.external-sources— một Recipe tải về những gì nó render: một chart thượng nguồn, một kho git hoặc một module.import— một dự án được viết ở định dạng khác, đượcaggrega importsoạn nháp thành các tệp Aggrega, rồi được xem xét và build.
Một ví dụ liệt kê ít nhất một sản phẩm hoặc một khả năng, để chỉ mục có thể xếp nó vào. README của nó cũng có một mục ## Scaffold the example, chứa aggrega scaffold --example <name> trong khối lệnh đầu tiên và cd <name> trong khối thứ hai, theo ngay sau là một mục ## Build có khối lệnh đầu tiên là những gì aggrega scaffold --example in ra để chạy tiếp theo sau lệnh cd đó. scripts/gen-examples-index.sh --check, chạy từ thư mục gốc của kho này, kiểm tra mọi phần đầu theo các danh sách này, từ chối ví dụ thiếu một trong hai mục, cũng như ví dụ không có check.sh thực thi được lẫn build-release.sh, và xác nhận chỉ mục là mới nhất; chạy nó không kèm --check để ghi lại chỉ mục.