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.

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ínhLoạiBắt buộcMô tả
apiVersionconst “aggrega.ai/v1beta1”cóHằng số: "aggrega.ai/v1beta1"
kindconst “Component”cóHằng số: "Component"
metadataobjectcó
specobjectcó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ínhLoạiBắt buộcMô tả
namestringcóDài ít nhất 1 ký tự.
versionstringcó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-]+)*))?$.
descriptionstringkhôngThự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.
maintainersobject[]khôngDanh sách những người bảo trì sở hữu thực thể này.
licensestringkhôngMã đị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.
repositorystringkhôngURL đến kho Git chứa các tệp nguồn.
homestringkhôngURL của trang chủ, wiki hoặc tài liệu của thực thể này.
keywordsstring[]khôngDanh 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.
labelsobjectcó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’.
annotationsmap của stringkhôngCá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ínhLoạiBắt buộcMô tả
namestringcó
emailstringkhông
urlstringkhô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ínhLoạiBắt buộcMô tả
component.aggrega.ai/typestring (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ínhLoạiBắt buộcMô tả
extendsstringkhôngURI 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ó.
featuresSchemamap của objectkhôngCá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.
injectstring[]khôngCá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.
usesSchemamap của objectkhôngCá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_-]+$.
schemaanykhôngNộ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: }, viết tại spec.schema để cung cấp toàn bộ hợp đồng từ một tệp hoặc tại một trụ cột duy nhất để chỉ cung cấp trụ cột đó, với đường dẫn tương đối được đọc theo thư mục chứa thực thể đã khai báo nó; (3) tham chiếu liên tài liệu qua {$ref: #/schemas/} vào một mục của SchemaLibrary theo định danh tên trần (phiên bản do lockfile của từng Release cung cấp; không có máy chủ registry nào xuất hiện trong tham chiếu); (4) chuỗi trần inherited, là dạng duy nhất mà một Component khai báo extends được phép viết — nó cho biết ba trụ cột đến từ Component cơ sở đúng như cơ sở đã soạn. Các chế độ 1 đến 3 soạn nội dung và chỉ dành cho Component không khai báo extends; chế độ 4 không soạn nội dung nào và là bắt buộc với mọi Component có khai báo extends. Các trường đi kèm usesSchema và featuresSchema bao quát các trụ cột có hình dạng cố định (socket phụ thuộc, slot gắn kết); trình biên dịch kết hợp ba phần này thành một schema duy nhất mà một instance được xác thực theo.
assertionsmap của stringkhôngXá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ínhLoạiBắt buộcMô tả
schemaconst “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ínhLoạiBắt buộcMô tả
schemaobjectkhôngNộ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ả.