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.

Bề mặt kiểm tra hợp lệ

Aggrega kiểm tra hợp lệ nội dung được soạn thảo qua bốn lớp schema riêng biệt. Mỗi lớp bao quát một phạm vi khác nhau, chạy tại một thời điểm khác nhau trong pipeline biên dịch và tạo ra lỗi với hình dạng khác nhau. Khi gặp lỗi kiểm tra hợp lệ, người soạn thảo sẽ có lợi nếu biết lớp nào đã từ chối đầu vào — cùng một trường có thể chịu sự chi phối của nhiều hơn một lớp, và lớp đã kích hoạt quyết định cần sửa gì và sửa ở đâu.

Trang này mô tả bốn lớp, vị trí của chúng trong pipeline, quy ước về hình dạng lỗi mà mỗi lớp tuân theo, và cách các lớp tương tác khi nhiều hơn một lớp áp dụng cho cùng một trường.

Bốn lớp

Lớp 1 — Lớp vỏ JSON Schema

Phạm vi. Cấu trúc của mọi tệp YAML trong catalog: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, khối spec: cấp cao nhất, và các trường bắt buộc theo từng thực thể mà schema khai báo. Mỗi loại thực thể (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) có JSON Schema riêng, được mô tả trong tài liệu tham chiếu schema. Workload cũng có một schema ở đó, và đây là loại duy nhất trong tập đó mà tác giả viết bên trong một thực thể khác — khối workload: của một Recipe hoặc FeatureRecipe, hoặc một mục WorkloadLibrary — thay vì dưới dạng một tệp catalog riêng; cùng một phép kiểm tra lớp vỏ áp dụng cho nó ở bất cứ nơi nào nó được viết, và aggrega validate chấp nhận trực tiếp một tệp Workload làm đích đơn thực thể.

Thời điểm kiểm tra. Khi phân giải (resolver / load), theo từng tệp. Mỗi tài liệu được kiểm tra theo JSON Schema của loại của nó khi được nạp; một khóa nằm ngoài các trường mà schema khai báo sẽ bị từ chối ngay tại đó, trước khi bất kỳ bước kiểm tra nào khác chạy.

Dạng lỗi. Một sự không khớp schema được báo cáo là lỗi lớp vỏ tài liệu. Phần đầu của nó mang danh mục của tài liệu có lỗi — [CATALOG_ERROR E0215] cho một thực thể catalog, [DEVELOPER_ERROR E0215] cho một Aggregate, [OPS_ERROR E0215] cho một Release — và thông báo nêu loại, tệp, dòng và cột, đường dẫn trường và ràng buộc bị vi phạm:

[CATALOG_ERROR E0215] <path>
document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schema

Việc thiếu trường bắt buộc và không khớp kiểu cũng xuất hiện theo cùng dạng — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".

Lớp 2 — Schema của các trụ dữ liệu (schema: / featuresSchema / usesSchema)

Phạm vi. Các trụ dữ liệu mà một thực thể mang — values, infra, parameters, cùng với khối gắn features: có các slot do featuresSchema khai báo và khối uses: do usesSchema quản lý. Các thực thể Miền 2 (Component, Feature) nhúng các khai báo JSON Schema 2020-12 trong lớp vỏ YAML của chúng (spec.schema nội tuyến — dạng rút gọn hoặc đầy đủ — hoặc một $ref: tới một mục SchemaLibrary dùng chung); các thực thể Miền 3 (Recipe, FeatureRecipe) sử dụng các schema đã phân giải trong lượt kiểm tra của riêng chúng.

Thời điểm kiểm tra. Khi phân giải, sau khi lớp vỏ JSON Schema đạt. Trình biên dịch kết hợp schema: do thực thể khai báo với các schema cơ sở tự động sinh từ các khai báo usesSchema và featuresSchema; schema kết hợp kiểm tra các khối values: / infra: / features: / uses: do nhà phát triển cung cấp trên mọi thể hiện component trong Aggregate.

Dạng lỗi. Các vi phạm ràng buộc xuất hiện dưới dạng thông báo nêu tên thực thể, đường dẫn bên trong trụ dữ liệu, và quy tắc đã từ chối giá trị — ví dụ một nhà phát triển đặt cổng là 80 trong khi quy tắc schema yêu cầu >=1024.

Một mục usesSchema hoặc featuresSchema được khai báo lại không gây lỗi kết hợp. Hai bề mặt này chồng lên nhau theo tên: mục của con thay thế hoàn toàn mục của cơ sở, cả schema lẫn selector, nên không có xung đột nào giữa mục cơ sở và mục con để báo cáo.

Lớp 3 — Khả năng chế độ tổng hợp của Provider

Phạm vi. Được quản lý bởi cổng khả năng chế độ tổng hợp của provider được gắn:

  • Việc hỗ trợ chế độ tổng hợp (workload:) phụ thuộc vào khả năng của provider được gắn, không phụ thuộc vào sự có mặt của workloadSchema: một Recipe workload: gắn với provider không thể tổng hợp sẽ bị từ chối tại đây. Catalog thư viện chuẩn khai báo workloadSchema trên các provider có khả năng tổng hợp theo quy ước — trên spec.provider.workloadSchema của Plugin hiển thị provider — như hợp đồng chuyển đổi được ghi trong tài liệu. Bản thân phần thân workloadSchema đó được biên dịch sang JSON Schema 2020-12 khi Plugin được nạp, một cổng chấp nhận về cấu trúc từ chối schema sai định dạng ngay khi nạp thay vì khi hiển thị.

Thời điểm kiểm tra. Khi hiển thị cơ sở, sau khi valuesMapping của chính Recipe đã được phân giải. Lớp 3 kiểm soát việc điều phối chế độ tổng hợp dựa trên khả năng của provider.

Dạng lỗi. Một lần từ chối do khả năng được quy về miền tạo catalog, nên báo cáo của nó mở đầu bằng phần đầu trong ngoặc vuông mang danh mục đó và instance gây ra lỗi. Thông báo mở đầu bằng câu cố định nêu điều kiện, sau đó nêu tên nút, provider, và các loại mà provider đó có hỗ trợ:

[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesized

Phần đầu [CATALOG_ERROR] cho biết lỗi thuộc về thực thể catalog, không phải Aggregate của nhà phát triển. Trên terminal, phần đầu còn mang mã ngắn của điều kiện — E0265 cho trường hợp này, được tra trong bảng mọi điều kiện — và thông báo chuyển sang dòng thụt lề riêng; dạng một dòng ở trên là dạng được ghi vào log. Câu mở đầu cố định theo từng điều kiện, nên đó là phần để so khớp khi bạn làm việc với văn bản; mọi thứ sau nó thay đổi theo nút gây lỗi.

Một cơ chế bảo vệ liên quan bảo vệ chính việc điều phối provider: khi có nhiều hơn một Plugin hiển thị provider phục vụ cùng một đích, workspace giải quyết sự mơ hồ bằng một liên kết provider trong .aggrega-config.yaml, được chọn khi chạy aggrega pull và ghi vào lockfile. Khi không có liên kết và chỉ có đúng một Plugin ứng viên, ứng viên đó được dùng; khi không có liên kết và có nhiều hơn một ứng viên, bản build dừng lại rõ ràng và nêu tên các plugin ứng viên. Sự mơ hồ được giải quyết theo từng workspace tại nơi sử dụng, không bằng một quy tắc duy nhất trên toàn catalog.

Kiểm tra nội dung Workload theo từng provider. spec.provider.workloadSchema của một Plugin render provider mô tả cách provider chuyển đổi một Workload và đánh dấu provider là có khả năng tổng hợp Workload; nó không kiểm tra gì cả. Mọi thân Workload đều được kiểm tra theo schema Workload của nền tảng, bất kể provider nào.

Lớp 4 — Kiểm tra giá trị liên kết annotation

Phạm vi. Các giá trị annotation được khai báo trên các ranh giới Release / component ranh giới hoặc các hệ thống con / thể hiện component của Aggregate, khi một liên kết Manifest dưới mappings.features.annotations.<key> khai báo định tuyến qua các danh sách đường dẫn dạng dấu chấm maps.infra và/hoặc maps.values. Mỗi đường dẫn được khai báo đi qua spec.schema.<pillar> của Feature đích tới một thuộc tính lá; phần đóng góp của giá trị annotation tại lá đó được kiểm tra theo kiểu đã khai báo của schema Feature. Việc kiểm tra đi qua khai báo JSON Schema 2020-12 của chính Feature — các liên kết chỉ khai báo định tuyến, không khai báo các phân đoạn kiểm tra.

Thời điểm kiểm tra. Pha con mở rộng annotation của bước phân giải, sau bước kiểm tra đích liên kết Manifest (phép kiểm tra khi nạp catalog xác nhận mỗi đường dẫn được khai báo tồn tại trong schema Feature được tham chiếu) và song song với kiểm tra schema Lớp 2 trên các phần gắn tường minh. Với mỗi annotation hiệu lực theo từng component: phân tích giá trị thành một giá trị vô hướng, một map có cấu trúc hoặc một null tường minh; định tuyến theo từng khóa con qua khai báo maps được nhóm theo trụ của liên kết, với việc áp dụng phía-so-với-trụ (phía Aggregate kích hoạt maps.values; phía Release kích hoạt maps.infra); kiểm tra giá trị runtime theo từng lá với kiểu đã khai báo của schema Feature tại trụ được định tuyến. Nhiều lỗi khóa con được thu thập và phát ra tất cả trước khi dừng.

Dạng lỗi. Các lỗi kiểm tra schema ở lớp này theo dạng của Lớp 2 — thực thể, đường dẫn (khóa annotation cùng tuyến khóa con), chi tiết ràng buộc. Các vi phạm phân vùng phía-so-với-trụ và lỗi định tuyến mơ hồ được quy về tài liệu mà giá trị annotation được khai báo trong đó, nên lỗi nằm trong một Aggregate mở đầu bằng phần đầu [DEVELOPER_ERROR] và lỗi nằm trong một Release mở đầu bằng phần đầu [OPS_ERROR], và cả hai đều nêu khóa annotation, trụ được định tuyến, phía khai báo, và vị trí nguồn.

Một quy ước định dạng lỗi chung cho các lớp

Bốn lớp có chung một quy ước có thể quan sát được: mọi lỗi xác thực quy được cho Aggrega đều mang dạng đường dẫn kèm lý do, nêu tên trường vi phạm và ràng buộc đã từ chối trường đó.

  • Lỗi Lớp 1 (lớp vỏ) và Lớp 2 (schema trụ) mở đầu bằng cùng một phần đầu trong ngoặc vuông — danh mục của tài liệu có lỗi và mã ngắn của điều kiện, chẳng hạn [CATALOG_ERROR E0215] cho một sự không khớp lớp vỏ trong một thực thể catalog và [DEVELOPER_ERROR E0168] cho một giá trị Aggregate mà schema trụ từ chối — tiếp theo là đường dẫn trường và quy tắc schema bị vi phạm.
  • Lỗi của Lớp 3 (nguồn Provider / Workload) theo định nghĩa là quy được cho thực thể catalog — cặp Recipe + Provider đã viết schema từ chối đầu vào của nhà phát triển. Các lỗi này được quy cho miền soạn catalog, và sự quy trách nhiệm đến với bạn qua phần đầu trong ngoặc vuông của chẩn đoán chứ không phải qua một từ được gõ vào thông báo: một báo cáo dừng bắt đầu bằng [CATALOG_ERROR E0nnn], trong đó danh mục nêu tên miền và mã ngắn nêu tên điều kiện. Hãy đối chiếu theo mã ngắn, vốn cố định một khi đã được cấp.
  • Lỗi của Lớp 4 (xác thực giá trị liên kết chú thích) theo dạng của Lớp 2 — schema Feature dùng để xác thực nằm trong spec.schema của Feature được tham chiếu, và các giá trị thời gian chạy đi qua định tuyến maps của liên kết Manifest vào schema đó để kiểm tra kiểu theo từng lá.

Để xem toàn bộ danh sách các sentinel có tiền tố Aggrega và các bề mặt tạo ra chúng, hãy xem errors/error-translation.md. Để xem catalog theo từng lỗi (các quy tắc hình dạng Recipe [CATALOG_ERROR], theo từng điều kiện), hãy xem errors/fatal-halts.md.

Tương tác giữa các lớp khi các trường chồng lấn

Cùng một trường được viết có thể chịu sự chi phối của nhiều hơn một lớp. containers.<name>.ports.<port> của một Workload được Lớp 1 kiểm tra như một phần của cấu trúc schema Workload; Lớp 2 không chạm tới nó, vì nội dung Workload là một cấu trúc nội bộ của Recipe chứ không phải một trụ của Component; và workloadSchema của provider không kiểm tra gì — vì vậy một ràng buộc như từ chối cổng dưới 1024 nên đặt trong schema của Component hoặc trong một assertion, nơi lớp được kích hoạt sẽ nêu tên nó.

Tóm tắt vị trí trong pipeline

LớpPhạm viChạy tạiTiền tố lỗi
1 — Lớp bao JSON SchemaHình dạng cấu trúc (apiVersion, kind, metadata, spec cấp cao nhất)Phân giải (tải)danh mục của tài liệu với E0215 — [CATALOG_ERROR E0215] cho một thực thể catalog
2 — Schema trụ cột (schema: / featuresSchema / usesSchema)Xác thực dữ liệu theo từng trụ cột (values, infra, secrets, uses)Phân giải (sau envelope)danh mục của tài liệu nguồn với mã ngắn của điều kiện — [DEVELOPER_ERROR E0168] cho một giá trị Aggregate
3 — Cổng kiểm tra khả năng ProviderHỗ trợ chế độ tổng hợp (năng lực của provider)Kết xuất cơ sở[CATALOG_ERROR]
4 — Xác thực giá trị của liên kết annotationCác đóng góp giá trị annotation được định tuyến vào spec.schema của Feature đích thông qua các đường dẫn maps của liên kết trong ManifestGiai đoạn con mở rộng annotation của quá trình phân giải, song song với Layer 2lỗi xác thực schema; các bề mặt side-so-với-trụ-cột / định tuyến mơ hồ mở đầu bằng miền của chính tài liệu tạo ra chúng — [DEVELOPER_ERROR] từ một Aggregate, [OPS_ERROR] từ một Release

Tham chiếu chéo

  • errors/error-translation.md — danh mục các sentinel có tiền tố Aggrega và các bề mặt tạo ra chúng.
  • errors/fatal-halts.md — danh mục theo từng lỗi của mọi điểm dừng nghiêm trọng mà trình biên dịch phát ra.
  • vocabulary/data-pillars.md — các trụ cột dữ liệu (values, infra, parameters, locals, features:, uses: và provides) mà Lớp 2 kiểm tra hợp lệ.
  • entities/component.md — bề mặt soạn thảo Component cho schema: / featuresSchema / usesSchema.
  • entities/plugin.md — bề mặt soạn thảo Plugin kết xuất provider cho spec.provider.workloadSchema.
  • entities/manifest.md — bề mặt ràng buộc features.annotations của Manifest (Lớp 4).
  • providers/well-known-annotations.md — việc phân tích giá trị annotation, định tuyến khóa con của giá trị có cấu trúc, cơ chế null để từ chối theo từng khóa con, và việc kết hợp giữa các phía mà Lớp 4 kiểm tra hợp lệ.