Lược đồ Aggrega Catalog (Feature)
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 của lược đồ: https://aggrega.ai/schemas/feature-v1beta1.schema.json
Một tính năng vận hành dạng mô-đun, liên kết động với các thành phần.
Xem tài liệu tham khảo về cách viết Feature để có hướng dẫn dạng văn xuôi về cách viết các thực thể Feature; 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 “Feature” | có | Hằng số: "Feature" |
metadata | object | có | |
spec | object | có | Hợp đồng xác thực, nhắm mục tiêu và khả năng tương tác cho một Feature của catalog: các trụ cột dạng tự do (values, infra, provides) được định nghĩa qua schema, các trụ cột có hình dạng cố định (các socket phụ thuộc usesSchema, các slot gắn kết featuresSchema), việc nhắm mục tiêu component (appliesTo và appliesToAnyOf), và các điều khiển khả năng tương tác. |
Không cho phép thuộc tính bổ sung.
feature.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 feature (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 | không | Các nhãn duck-typing cho Feature. Nhãn dành riêng ‘feature.aggrega.ai/kind’ với giá trị ‘secret’ đánh dấu đây là một Feature thông tin xác thực, dành cho tác giả và cho công cụ hiển thị nó. Một Feature thông tin xác thực và một Feature thông thường được gắn theo cùng một cách, trên cùng một bề mặt gắn kết; kết quả mà một lần gắn kết tạo ra được quyết định bởi FeatureRecipe mà Manifest ánh xạ loại của nó tới, chứ không phải bởi nhãn. |
annotations | map của string | không | Các đặc tính nội tại, bất biến của feature do Platform Architect định nghĩa trong Domain 2. Được truyền xuống bucket .context.annotations.catalog. |
Không cho phép thuộc tính bổ sung.
feature.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.
feature.metadata.labels
Các nhãn duck-typing cho Feature. Nhãn dành riêng ‘feature.aggrega.ai/kind’ với giá trị ‘secret’ đánh dấu đây là một Feature thông tin xác thực, dành cho tác giả và cho công cụ hiển thị nó. Một Feature thông tin xác thực và một Feature thông thường được gắn theo cùng một cách, trên cùng một bề mặt gắn kết; kết quả mà một lần gắn kết tạo ra được quyết định bởi FeatureRecipe mà Manifest ánh xạ loại của nó tới, chứ không phải bởi nhãn.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
feature.aggrega.ai/kind | string (enum) | không | Nhãn loại của Feature. Giá trị ‘secret’ đánh dấu đây là một Feature thông tin xác thực. Các giá trị được phép: "secret" |
feature.spec
Hợp đồng xác thực, nhắm mục tiêu và khả năng tương tác cho một Feature của catalog: các trụ cột dạng tự do (values, infra, provides) được định nghĩa qua schema, các trụ cột có hình dạng cố định (các socket phụ thuộc usesSchema, các slot gắn kết featuresSchema), việc nhắm mục tiêu component (appliesTo và appliesToAnyOf), và các điều khiển khả năng tương tác.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
extends | string | không | Tham chiếu đến một Feature cơ sở mà Feature này kế thừa. Nó gọi tên Feature cơ sở bằng metadata.name của nó chứ không bằng tọa độ registry mà Feature được phát hành dưới đó, và nhận cùng ba dạng phiên bản mà mọi tham chiếu catalog đều nhận: dạng trần (core/queue) cho bản phát hành cao nhất hiện có, dạng chính xác (core/queue:1.0.0), hoặc một khoảng caret (core/queue:^1.0.0). Những gì được kế thừa không chỉ là metadata: metadata.labels và metadata.annotations của Feature cơ sở, các bộ chọn appliesTo và appliesToAnyOf của nó, khối interoperability của nó, usesSchema và featuresSchema của nó đều được hợp nhất xuống dưới, và các khai báo JSON Schema 2020-12 của nó trên schema được tự động hợp nhất. Giá trị riêng của Feature con thắng khi trùng khóa, và các trường định danh không bao giờ được kế thừa. |
featuresSchema | map của object | không | Định nghĩa khai báo các khe gắn kết: các điểm liên kết có tên mà tại đó Feature này mong đợi một Feature khác được gắn vào. Một khe ràng buộc phần lấp đầy nào có thể liên kết với nó (selector) và cách nội dung của phần lấp đầy có thể được chuyển giao (inject); Feature riêng của phần lấp đầy sở hữu hợp đồng values và infra của nó. Việc khai báo một khe không bao giờ đóng khối gắn kết — 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. Một khe là một điểm liên kết, không phải một ổ phụ thuộc: usesSchema khai báo bề mặt topology riêng biệt. |
appliesTo | string | không | Chuỗi bộ chọn nhãn kiểu Kubernetes để khớp các Components. Các yêu cầu phân tách bằng dấu phẩy đều phải thỏa mãn (AND). Các dạng được hỗ trợ: key=value, key!=value, key in (v1, v2), key notin (v1, v2), key trần (nhãn có mặt), !key (nhãn vắng mặt). Ví dụ: “tier in (critical, production), !legacy”. Một bộ chọn rỗng hoặc vắng mặt không khai báo ràng buộc nào. Bộ chọn được đọc theo các dạng này mỗi lần một lần gắn kết của Feature này được đánh giá, và một yêu cầu nằm ngoài các dạng đó sẽ dừng quá trình build, kèm theo tên của nó: một yêu cầu rỗng (dấu phẩy ở đầu, ở cuối hoặc lặp đôi), hoặc một key chứa khoảng trắng hay bất kỳ ký tự nào trong = ! ( ) và dấu phẩy — vì vậy “!tier=frontend” bị từ chối, và tier!=frontend là cách loại trừ một giá trị. Một giá trị là phần văn bản sau toán tử của nó, bất kể nó chứa ký tự nào. Mẫu trên trường này chỉ từ chối một vài dạng sai cấu trúc, trước khi bất kỳ lần gắn kết nào được đánh giá. Mẫu: ^(?:[^()]*[()][\s\S]*|[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?(?:,[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?)*)$. |
appliesToAnyOf | string hoặc map của string[] | không | Danh sách các bộ chọn; Feature được áp dụng nếu BẤT KỲ mục nào khớp (logic OR). Mỗi mục là một chuỗi bộ chọn nhãn (cùng ngữ pháp với appliesTo; các yêu cầu trong chuỗi kết hợp theo AND) hoặc một map key-value phẳng trong đó mọi cặp đều phải khớp (chỉ so sánh bằng). |
interoperability | object | không | Các điều khiển nâng cao về an toàn vận hành và khả năng tương tác. |
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ó và các cơ chế inject mà nó cho phép. 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 nối. Không cho phép dấu chấm. Mẫu: ^[a-zA-Z0-9_-]+$. |
schema | object | 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 lần gắn Feature trong Aggregate); infra (miền của Operator — các núm đ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à Feature này cung cấp cho bên tiêu thụ qua đường ống topology). Chấp nhận ba chế độ soạn thảo thông qua 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 giữa các trường tại thời điểm build. Mỗi mục là một khẳng định có tên: key là định danh quy tắc ổn định được hiển thị trong thông báo lỗi; value là một chuỗi Go template với ngữ nghĩa dừng {{ fail "message" }}. Nhiều khẳng định có tên trên mỗi thực thể được đánh giá theo từng instance theo thứ tự tác giả khai báo; khẳng định thất bại đầu tiên sẽ dừng quá trình build. Các khẳng định của Feature được đánh giá sau khi phân giải và phân tích tĩnh, trước khi render, và biểu đạt các bất biến kiến trúc của hợp đồng. Ngữ cảnh template: .values / .infra / .uses / .features / .metadata. Bộ đánh giá dùng missingkey=error: tham chiếu đến các 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 kịp 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 bảo vệ 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ự có mặt. Đọc khóa qua index cũng không cung cấp được: index dừng khi gặp một khóa map mà map không chứa, kèm theo tên khóa. |
Không cho phép thuộc tính bổ sung.
feature.spec.interoperability
Các điều khiển nâng cao về an toàn vận hành và khả năng tương tác.
| Thuộc tính | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
conflictsWith | string[] | không | Tên của các Features mà Feature này không thể cùng đến một component, mỗi tên được viết theo cách type của một lần gắn kết gọi tên một Feature. Quá trình build dừng trước khi render khi một component cuối cùng mang cả Feature này và một Feature được nêu ở đây — dù mỗi cái được gắn trên component, trên một subsystem hoặc boundary chứa nó, trên một mục component của Release, hay bằng việc mở rộng dựa trên annotation. Một khai báo là đủ: việc dừng không cần Feature kia liệt kê Feature này. Các tên được so sánh sau khi bỏ mọi phiên bản, vì vậy một mục khớp với mọi phiên bản của Feature mà nó gọi tên. Hai Features được gắn vào các boundary anh em không chung component nào sẽ không bao giờ gặp nhau và không gây dừng. |
Không cho phép thuộc tính bổ sung.