Lược đồ Aggrega Catalog (Component)
Tài liệu tham khảo được sinh tự động. Không chỉnh sửa thủ công — hãy sinh lại từ JSON Schema đã xuất bản.
Id lược đồ: https://aggrega.ai/schemas/component-v1beta1.schema.json
Định nghĩa trừu tượng của một khối xây dựng nguyên tử.
Xem tài liệu tham khảo về cách soạn Component để có hướng dẫn bằng văn xuôi về việc soạn các thực thể Component; trang này mô tả lược đồ cấu trúc mà tài liệu tham khảo đó trình bày.
Kiểu cấp cao nhất: object
Thuộc tính
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | có | Hằng số: "aggrega.ai/v1beta1" |
kind | const “Component” | có | Hằng số: "Component" |
metadata | object | có | |
spec | object | có | Các định nghĩa xác thực và schema chi phối payload values không trong suốt của nhà phát triển. |
Không cho phép thuộc tính bổ sung.
component.metadata
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | Dài ít nhất 1 ký tự. |
version | string | có | Phiên bản theo Semantic Versioning nghiêm ngặt của giao diện (ví dụ: 1.0.0). Mẫu: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
description | string | không | Thực thể này là gì và dùng để làm gì, được viết cho người đang quyết định có dùng nó hay không. Mở đầu bằng một câu gọi tên nó, sau đó bổ sung những gì người đọc cần để chọn và dùng nó đúng cách — nó mong đợi gì từ Release triển khai nó, và bất cứ điều gì bất ngờ trong cách nó hoạt động. Độ dài thông thường là một đoạn ngắn. |
maintainers | object[] | không | Danh sách những người bảo trì sở hữu thực thể này. |
license | string | không | Mã định danh SPDX cho giấy phép của phần mềm mà thực thể này mô tả, chẳng hạn MIT hoặc AGPL-3.0. Nó ghi lại các điều khoản của phần mềm đó, không phải các điều khoản của tệp này. |
repository | string | không | URL đến kho Git chứa các tệp nguồn. |
home | string | không | URL của trang chủ, wiki hoặc tài liệu của thực thể này. |
keywords | string[] | không | Danh sách các từ khóa mô tả giúp dễ tìm kiếm trên giao diện người dùng. |
labels | object | có | Các nhãn duck-typing để khai báo đặc tính. Phải bao gồm khóa dành riêng ‘component.aggrega.ai/type’. |
annotations | map của string | không | Các đặc tính nội tại, bất biến của component do Platform Architect soạn trong Domain 2. Được truyền xuống bucket .context.annotations.catalog. |
Không cho phép thuộc tính bổ sung.
component.metadata.maintainers[]
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
name | string | có | |
email | string | không | |
url | string | không |
Không cho phép thuộc tính bổ sung.
component.metadata.labels
Các nhãn duck-typing để khai báo đặc tính. Phải bao gồm khóa dành riêng ‘component.aggrega.ai/type’.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
component.aggrega.ai/type | string (enum) | có | Trục dành riêng cho biết component này thuộc loại gì. Aggrega định nghĩa khóa này và các giá trị nó chấp nhận, nên tập giá trị là đóng; để phân loại các component theo một trục của riêng bạn, hãy thêm khóa nhãn của riêng bạn bên cạnh khóa này. Các giá trị cho phép: "server", "worker", "task", "function", "stateful-server", "resource" |
component.spec
Các định nghĩa xác thực và schema chi phối payload values không trong suốt của nhà phát triển.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
extends | string | không | URI của một Component cơ sở mà Component này mở rộng. Việc mở rộng kết hợp cấu trúc: các nhãn và annotation metadata của cơ sở, các khe gắn (featuresSchema), danh sách cho phép self-inject (inject) và các socket topology (usesSchema) của nó được kế thừa, và Component này có thể bổ sung vào chúng hoặc thay thế một mục được kế thừa theo từng khóa. Các trụ dữ liệu của cơ sở KHÔNG được kết hợp — khối schema của cơ sở được kế thừa đúng như cơ sở đã soạn, nên một Component mở rộng viết schema: inherited và không soạn nội dung trụ nào của riêng nó. |
featuresSchema | map của object | không | Các định nghĩa khe gắn khai báo: các điểm liên kết có tên mà tại đó thực thể này kỳ vọng một Feature được gắn vào. Một khe ràng buộc phần lấp nào có thể liên kết với nó (selector) và cách vật liệu của phần lấp có thể được chuyển giao (inject); chính Feature của phần lấp sở hữu values và hợp đồng infra của nó. Việc khai báo một khe không bao giờ đóng khối gắn — tác giả có thể gắn một Feature dưới một tên mà không khe nào khai báo, nhờ đó một thực thể phục vụ cả một attachment lấp vào khe lẫn một thông tin xác thực được chia sẻ ở phạm vi rộng hơn. Một khe là một điểm liên kết, không phải một socket phụ thuộc: usesSchema khai báo bề mặt topology riêng biệt. |
inject | string[] | không | Các cơ chế chuyển giao self-inject được cho phép (ví dụ: [‘env’, ‘file’, ‘arg’]). Khi có mặt, nhà phát triển có thể dùng khối inject: ở cấp component trong Aggregate để inject trực tiếp values hoặc các khóa provides của chính họ vào đường ống chuyển giao. Nếu bị bỏ qua, self-inject ở cấp component bị cấm (mẫu Black-Box — Recipe xử lý toàn bộ việc kết nối nội bộ). Ngữ nghĩa giống usesSchema[].inject nhưng chi phối values của chính component thay vì topology giữa các component. Có thể liệt kê bất kỳ tên cơ chế nào trừ all, tên mà không khối inject nào có thể dùng. |
usesSchema | map của object | không | Các socket phụ thuộc mà thực thể này khai báo, với khóa là tên socket; mỗi kết nối được tạo qua một socket được kiểm tra theo khai báo của socket đó — selector của nó, các cơ chế inject mà nó cho phép và các hợp đồng theo từng kết nối của nó. Khóa: một hoặc nhiều chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch ngang. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
schema | any | không | Nội dung JSON Schema 2020-12 bao quát các trụ cột dạng tự do: values (miền của Developer — các tham số định hình ứng dụng mà Developer cấu hình cho từng thực thể Component trong Aggregate); infra (miền của Operator — các nút điều chỉnh kích thước vật lý do Release cung cấp); và provides (các khóa ngữ cảnh hạ nguồn mà Component này cung cấp cho bên sử dụng qua đường ống topology). Chấp nhận bốn chế độ soạn thảo thông qua cơ chế phân phối theo hình dạng nội dung: (1) nội dung nội tuyến (một map YAML mang dạng rút gọn, JSON Schema YAML, hoặc kết hợp); (2) thay thế bằng tệp qua {$import: |
assertions | map của string | không | Xác thực chéo trường tại thời điểm build. Mỗi mục là một assertion có tên: khóa là định danh quy tắc ổn định hiển thị trong thông báo lỗi; giá trị là một chuỗi Go template với ngữ nghĩa dừng {{ fail "message" }}. Nhiều assertion có tên trên mỗi thực thể được đánh giá cho từng thể hiện theo thứ tự tác giả khai báo; assertion thất bại đầu tiên sẽ dừng build. Các assertion của Component được đánh giá sau phân giải và phân tích tĩnh, trước render, và biểu đạt các bất biến kiến trúc của hợp đồng luôn đúng bất kể Recipe nào liên kết. Ngữ cảnh template: .values / .infra / .uses / .features / .metadata. Bộ đánh giá dùng missingkey=error: các tham chiếu đến khóa chưa định nghĩa sẽ dừng với chẩn đoán no-such-key. Vì tham chiếu trần dừng trước khi bất kỳ giá trị dự phòng nào có thể chạy, một default đơn thuần không cung cấp giá trị dự phòng cho trường tùy chọn trên bề mặt này — hãy chặn tham chiếu bằng hasKey, hoặc dùng helper optional, vốn thực hiện trực tiếp việc kiểm tra sự tồn tại. Đọc khóa qua index cũng không cung cấp được: index dừng khi gặp khóa map mà map không chứa, kèm tên khóa. Kế thừa mang tính cộng dồn: một Component khai báo extends được đánh giá theo các assertion nó kế thừa cũng như của chính nó, với các quy tắc kế thừa đứng trước, và một chuỗi ở bất kỳ độ sâu nào tích lũy từ gốc chuỗi đi xuống — nên khi có nhiều hơn một quy tắc thất bại, quy tắc được khai báo xa nhất về phía trên chuỗi là quy tắc được báo cáo. Việc dùng lại một tên được kế thừa để khai báo một quy tắc khác bị từ chối khi chuỗi extends được phân giải theo catalog, kèm tên của cả hai Components và tên dùng chung — nên lỗi xuất hiện khi Component cơ sở có mặt, chứ không chỉ từ tài liệu mở rộng; một Component mở rộng bổ sung quy tắc và không bao giờ thay thế quy tắc nào. Việc khai báo lại nguyên văn từng byte một quy tắc được kế thừa dưới chính tên của nó được chấp nhận như một thao tác không có tác dụng. Không có gì kiểm tra liệu hai quy tắc có thể cùng đúng hay không: một cặp loại trừ lẫn nhau là lỗi soạn thảo, xuất hiện như một lỗi assertion thông thường khi một thể hiện kích hoạt quy tắc nào chạy trước, không bao giờ là một cảnh báo từ trước. |
Không cho phép thuộc tính bổ sung.
Định nghĩa
extending-component-must-declare-schema-inherited
Áp dụng khi có spec.extends. Một Component mở rộng nhận values / infra / provides của base đúng như base đã viết, vì vậy nó khai báo spec.schema: inherited và không viết nội dung pillar nào. Cả hai kết quả còn lại đều là lỗi, và chúng là những sai lầm khác nhau: bỏ hẳn spec.schema, điều này khiến người đọc không thể phân biệt một khối pillar được kế thừa với một khối bị quên; và viết nội dung pillar dưới spec.schema, điều này sẽ yêu cầu một hợp đồng thứ hai, khác biệt, trên một Component mà hợp đồng của nó là hợp đồng của base.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
schema | const “inherited” | có | Dấu hiệu kế thừa, và là giá trị duy nhất mà spec.schema nhận trên một Component khai báo extends. Nó cho biết các pillar đến từ đâu; bản thân nội dung pillar là của Component base. Hằng số: "inherited" |
non-extending-component-authors-its-own-schema
Áp dụng khi không có spec.extends. Một Component không mở rộng base nào sẽ tự viết nội dung values / infra / provides của mình dưới spec.schema, vì vậy trường này chứa nội dung được viết thay vì dấu hiệu kế thừa: dấu hiệu đó cho biết các pillar đến từ một base, và Component này không có base nào.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
schema | object | không | Nội dung pillar được viết — một map, theo bất kỳ chế độ nào trong ba chế độ viết nội dung mà spec.schema mô tả. |