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.

Khế ước xã hội

Theo thiết kế, Aggrega là một trình biên dịch không có quan điểm riêng. Theo các bất biến nền tảng được mô tả tại architecture/05-invariants.md, trình biên dịch phân tích YAML, duyệt đồ thị, đánh giá giao của các nhãn và truyền chuỗi giữa các component — nhưng nó không kiểm soát những gì nhà phát triển đặt vào values, parameters, infra, provides hay locals; nó không áp đặt các quy ước đặt tên, quy ước cổng hay các nhãn ngữ nghĩa mà một Architect tự đặt ra; nó không đoán mục đích của component từ tên. Nhiều nguyên tắc nghe có vẻ là quy tắc của trình biên dịch thực ra là khế ước xã hội: các thực hành tốt nhất được duy trì bằng quy ước khi soạn thảo chứ không phải bằng schema hay cơ chế thực thi lúc chạy.

Sự trung lập đó dừng lại ở đâu là điều đáng nói rõ, vì đó chỉ là một ranh giới và rất dễ bị hiểu quá mức. Một vài khóa là của riêng Aggrega — được dành riêng, với các giá trị mà nó chấp nhận được ghi vào schema đã công bố — và những khóa đó thì schema có kiểm tra, theo cách nó kiểm tra bất kỳ trường nào khác đã được khai báo. Việc khai báo tập giá trị của một khóa do chính nền tảng định nghĩa không phải là trình biên dịch gán ý nghĩa vào những gì bạn viết; đó là nền tảng nói rõ khóa của chính nó có nghĩa là gì. Mọi thứ bạn soạn dưới một khóa của riêng bạn vẫn hoàn toàn không bị kiểm soát như trang này mô tả.

Trang này là danh mục chính thức về các khế ước xã hội của ngôn ngữ. Người soạn thảo nắm được các khế ước từ trang này có thể hiểu vì sao trình biên dịch chấp nhận một bản build sai theo quy ước (nó chấp nhận — trình biên dịch không diễn giải quy ước) và trách nhiệm phát hiện vi phạm nằm ở đâu (kỷ luật khi soạn thảo, sự chú ý của người review, hoặc một plugin linter do aggrega lint chạy).

Ba lớp kỷ luật

Các kỷ luật của Aggrega chia thành ba lớp theo cách kỷ luật được thực thi. Việc phân loại này quan trọng vì mỗi lớp có một kiểu thất bại khác nhau khi kỷ luật bị vi phạm.

Do schema thực thi

Kỷ luật được thực thi bằng việc xác thực JSON Schema 2020-12 lúc nạp (JSON Schema của phong bì thực thể, cùng với các khai báo schema: ở cấp trụ cột trên các thực thể Component và Feature). Một vi phạm gây ra một lỗi dừng nghiêm trọng trước khi bản build tiếp tục; trình biên dịch từ chối tiếp tục. Tác giả nào cố vi phạm một kỷ luật do schema thực thi sẽ thấy một lỗi xác thực rõ ràng chỉ vào trường và ràng buộc.

Ví dụ: các trường bắt buộc của phong bì thực thể (apiVersion / kind / metadata.name / metadata.version); biểu thức chính quy SemVer trên metadata.version; tập giá trị đóng trên nhãn dành riêng component.aggrega.ai/type; lệnh cấm cơ học của schema Release đối với các khối values: (theo Bất biến 5); việc từ chối extends cùng với aggregate trên Release (bất biến Nguồn sự thật duy nhất); các quy tắc hình dạng Recipe thực thi hợp đồng kết hợp loại đầu vào.

Các kỷ luật do schema thực thi là những đảm bảo mạnh nhất mà ngôn ngữ mang lại. Trình biên dịch từ chối kết xuất bất cứ thứ gì vi phạm chúng.

Do một plugin chính sách thực thi

Kỷ luật được thực thi bởi một plugin Wasm chạy tại một trong các điểm socket đã được ghi lại (vai trò quản trị label-transform lúc xây dựng topo; vai trò quản trị ir-verdict lúc phân tích tĩnh; socket linter ngoài băng). Một vi phạm gây ra hoặc một lỗi chính sách làm dừng bản build (socket trong băng) hoặc một cảnh báo tư vấn (socket ngoài băng), tùy theo ngữ nghĩa chặn của socket.

Một kỷ luật chỉ được thực thi theo cách này ở nơi có một plugin kiểm tra nó đang chạy: runtime Wasm gọi các plugin tại các điểm socket đã được ghi lại, và một kỷ luật không có plugin nào kiểm tra thì vẫn là một quy ước. Linter xuất bản, do aggrega lint chạy, kiểm tra một phần của một quy ước trên trang này — xem Các quy ước mà một quy tắc linter kiểm tra. Không quy tắc nào của linter xuất bản kiểm tra tính kín (FuncMap của Sprig cung cấp các hàm trợ giúp phá vỡ tính tất định của đầu ra theo lưu ý về tính tất định tại templates/sprig-functions.md) hay việc đặt tên tài nguyên đám mây (các Recipes có đầu ra valuesMapping: tham chiếu các trường tên tài nguyên đám mây mà không nội suy release_name / instance_id, theo entities/recipe.md “Cloud-resource naming discipline”); một plugin linter của riêng bạn có thể kiểm tra cả hai.

Về bề mặt hợp đồng plugin Wasm và tiêu chí bố trí (socket linter so với các vai trò phán quyết quản trị), xem plugins/plugin-contract.md.

Được duy trì bằng quy ước

Kỷ luật chỉ được duy trì bởi kỷ luật khi soạn thảo cùng với sự chú ý của người review. Trình biên dịch không thực thi; không schema nào từ chối vi phạm; không plugin Wasm nào đánh dấu nó. Tác giả học kỷ luật từ tài liệu, tuân theo nó vì hình dạng kiến trúc phụ thuộc vào nó, và dựa vào việc review PR để phát hiện sai sót. Một vi phạm không tạo ra tín hiệu nào lúc biên dịch — bản build thành công, đầu ra được kết xuất hoạt động theo những gì trình biên dịch biết, và vi phạm kỷ luật chỉ lộ ra khi công cụ hạ nguồn hoặc hành vi runtime phụ thuộc vào quy ước.

Các kỷ luật được duy trì bằng quy ước là danh sách trọng yếu mà tác giả phải học từ tài liệu. Trình biên dịch không diễn giải chúng; làm sai không làm hỏng bản build, nhưng làm hỏng hình dạng kiến trúc mà Aggrega phụ thuộc vào. Phần lớn trang này ghi lại chúng.

Các quy ước

Các khế ước xã hội sau đây được duy trì bằng quy ước. Mỗi mục nêu tên kỷ luật, nơi quy ước được ghi lại trong tài liệu, và chế độ lỗi nếu bị vi phạm. Mỗi mục giữ nguyên số thứ tự của nó dù nằm ở đâu: khế ước 3, kỷ luật tiền tố dành riêng, được một quy tắc linter kiểm tra đối với các khóa annotation và được mô tả trong Các quy ước mà một quy tắc linter kiểm tra.

1. Chọn loại vận hành phù hợp với thành phần

Nhãn dành riêng component.aggrega.ai/type cho biết một thành phần là loại gì, lấy từ một tập đóng gồm các nguyên thủy đám mây phổ quát: server, worker, task, function, stateful-server, resource. Việc thuộc tập đó do schema thực thi, chứ không được duy trì bằng quy ước. Aggrega định nghĩa khóa này và các giá trị mà nó chấp nhận, schema của Component liệt kê chúng, và một tài liệu mang bất kỳ giá trị nào khác sẽ bị từ chối khi tải — E0215, điều kiện entity-envelope-invalid, nêu tên nhãn và liệt kê các giá trị mà nó chấp nhận. Sự từ chối đó là điều mà mục này không đề cập.

Điều vẫn là quy ước là giá trị nào phù hợp với thành phần trước mặt bạn. Không có gì kiểm tra rằng một cơ sở dữ liệu quan hệ được gắn nhãn stateful-server thay vì server, hay một consumer hàng đợi là worker thay vì task; bộ chọn đánh giá bất kỳ giá trị nào nó tìm thấy mà không gán ý nghĩa cho nó. Architect khi viết một Component sẽ chọn giá trị mô tả cách hạ tầng phải xử lý nó, và các bộ chọn, plugin chính sách và plugin kết xuất Wasm ở hạ nguồn đều dựa vào việc lựa chọn đó là trung thực.

Phân loại theo trục của riêng bạn. Tập đóng chỉ chi phối một khóa dành riêng này và không gì khác. Một catalog cần một cách phân loại mà Aggrega không định nghĩa — một tier, một vùng dữ liệu, một lớp dịch vụ, hoặc một cách chia nhỏ hơn các nguyên thủy vận hành — sẽ thêm khóa nhãn của riêng nó bên cạnh khóa dành riêng. Schema của Component chấp nhận mọi khóa nhãn khác có giá trị chuỗi, và cùng cơ chế bộ chọn sẽ đọc nó, nên acme.aggrega.ai/storage-tier: oltp nằm cạnh component.aggrega.ai/type: stateful-server và appliesTo của một Feature hay selector của một socket đều có thể nhắm tới một trong hai. Việc mở rộng diễn ra trên một khóa của riêng bạn, không bao giờ trên một giá trị bên trong khóa của Aggrega.

Được ghi lại tại: architecture/02-ecosystem-philosophy.md (bản thể luận vận hành) + labels-and-annotations.md (kỷ luật tiền tố) + errors/sentinels.md (E0215).

Chế độ lỗi: Một giá trị thuộc tập nhưng không phù hợp với thành phần sẽ đánh lừa mọi thứ đọc nhãn đó. Một kho dữ liệu được gắn nhãn server bị từ chối bởi một Feature hoặc một socket chọn stateful-server — lần dừng này nêu tên selector chứ không phải nhãn sai — và một plugin chính sách hay plugin kết xuất đọc nhãn sẽ xử lý nó như tài nguyên tính toán không trạng thái. Ở nơi chỉ những bên đọc như vậy thấy nó, build thành công; sai sót chỉ lộ ra khi các artifact đã kết xuất đến cluster.

2. Tách biệt .context.annotations.* thành ba nhóm

Các annotation được truyền xuống nằm trong ba nhóm có tên — .context.annotations.release, .context.annotations.catalog, .context.annotations.aggregate — mỗi nhóm mang một ý định khác nhau. Mục tiêu của kỷ luật: release là “thành phần này chạy ở đâu, do Ops quản lý”; catalog là “thành phần này là gì, do Architect viết”; aggregate là “thành phần này làm gì, do Developer viết”.

Trình biên dịch không thực thi ranh giới giữa các nhóm. Ba nhóm có chung một hình dạng phẳng string → string; template của một Recipe có thể đọc cả ba, và không có gì ngăn một annotation ranh giới Release bị diễn giải như siêu dữ liệu nhận thức hay một annotation catalog bị định tuyến vào infra:. Sự tách biệt được duy trì bởi các tác giả ghi annotation vào đúng nhóm và bởi người review phát hiện các rò rỉ giữa các nhóm.

Được ghi lại tại: labels-and-annotations.md (Tách biệt ba nhóm là một Social Contract).

Chế độ lỗi: Logic định tuyến phụ thuộc vào sự phân biệt ý định giữa các nhóm (ví dụ, một Recipe định tuyến .context.annotations.release.aggrega.ai/region vào trường region của Terraform) âm thầm tiêu thụ bất kỳ annotation nào xuất hiện trong nhóm bất kể ý định của tác giả. Build thành công; đầu ra đã kết xuất có thể mang các giá trị sai về ngữ nghĩa.

4. Tính tự chứa của provides: trong Recipe

Các template provides: của Recipe chỉ bao đóng trên dữ liệu của chính nút — .values, .infra, .context.instance_id, .context.rendered_name khi provider của nút báo cáo giá trị này, .locals đã phân giải của nút, cùng các chuỗi tĩnh. Các tham chiếu đến .context.inject và .context.uses bị cấm vì việc đánh giá provides chạy các template đó theo thứ tự bất kỳ; đọc dữ liệu liên nút sẽ gắn nó với thứ tự duyệt topo, điều mà thiết kế cố ý tránh. .locals nằm trong phạm vi chứ không nằm ngoài: các locals của nút được phân giải trong phần mở đầu của cùng giai đoạn, trước provides của nó, và chúng chỉ cục bộ trong nút, nên việc đọc chúng không ảnh hưởng gì đến thứ tự. Gọi tên một khóa mà khối locals không khai báo sẽ dừng build.

Đây là một quy tắc gồm hai nửa, mỗi nửa nêu rõ nơi nó được kiểm tra. Trình biên dịch kiểm tra nửa đầu: việc đánh giá provides kiểm tra từng template với một danh sách cho phép gồm các gốc mà ngữ cảnh của nó định nghĩa trước khi template thực thi, nên một lần đọc .context.inject / .context.uses sẽ dừng với lỗi rõ ràng thay vì kết xuất rỗng; quy tắc cũng được ghi lại tại templates/expansion-matrix.md hàng 6. Quy ước duy trì nửa sau: mẫu rộng hơn (provides là công khai; locals là riêng tư) được neo vào quy ước.

Được ghi lại tại: templates/expansion-matrix.md hàng 6 + vocabulary/data-pillars.md “provides: và locals: — mặt công khai và mặt riêng tư”.

Chế độ lỗi: trình biên dịch phát hiện và dừng build lúc đánh giá template khi các tham chiếu bị cấm xuất hiện trực tiếp trong provides:. Kỷ luật công khai-riêng tư rộng hơn (không phơi bày trạng thái nội bộ qua các khóa provides:) chỉ là quy ước — các tác giả coi provides: như một không gian tên nội bộ của Recipe sẽ tạo ra các hợp đồng mà bên gọi phụ thuộc vào; việc refactor trở thành một thay đổi phá vỡ.

5. Tính tất định — các helper không kín (non-hermetic) trong template trên đường render

Bất biến Đầu ra Tất định của Aggrega (Bất biến 8 tại architecture/05-invariants.md) yêu cầu đầu ra giống hệt từng byte cho đầu vào giống hệt từng byte. FuncMap đầy đủ của Sprig cung cấp các helper đọc trạng thái môi trường xung quanh (bộ đọc đồng hồ thực now / date; bộ sinh ngẫu nhiên randAlpha / uuidv4; bộ đọc biến môi trường env / expandenv; bộ phân giải mạng getHostByName). Tác giả gọi các helper này từ một template đóng góp vào đầu ra đã render sẽ phá vỡ hợp đồng tất định.

Trình biên dịch không phát hiện hay chặn việc dùng các helper không kín. FuncMap của Sprig cung cấp chúng theo templates/sprig-functions.md “Determinism caveat”; kỷ luật này được duy trì bởi các tác giả tránh dùng các helper đó trong template trên đường render và bởi người review phát hiện việc sử dụng chúng khi review PR.

Được ghi tài liệu tại: templates/sprig-functions.md “Determinism caveat”.

Hậu quả khi vi phạm: Đầu ra build khác nhau giữa các lần chạy với cùng đầu vào. Sự sai lệch lộ ra khi diff GitOps, khi công cụ phía sau (ArgoCD, Flux) thấy độ lệch bất ngờ giữa manifest đã commit và trạng thái cluster, hoặc khi kiểm toán, lúc hai lần biên dịch cùng một đầu vào tạo ra các artifact khác nhau.

Không quy tắc nào của linter xuất bản kiểm tra các lời gọi hàm trợ giúp không kín trong template. Tên của hàm trợ giúp được viết trong template, nên một plugin linter của riêng bạn có thể tìm ra nó (xem Các quy ước mà một quy tắc linter kiểm tra).

6. Ranh giới trụ cột (biển chỉ dẫn, không phải bức tường)

Ranh giới trụ cột là kỷ luật biên soạn, không phải sự cưỡng chế của ngôn ngữ. Template engine cho phép đọc chéo trụ cột ở mọi vị trí trừ khi bị cấm rõ ràng bởi các quy tắc tự chứa (ví dụ: Recipe provides: và source: đọc .context.inject / .context.uses). Tác giả nên:

  • Đọc .values cho payload nhận thức (ý định do developer biên soạn).
  • Đọc .infra cho kích thước vật lý (sizing do Ops biên soạn).
  • Đọc .context.uses.<alias>.provides.<key> cho các chuỗi con trỏ liên component.
  • Đọc .context.inject cho đường ống phân phối sau hydration.

Template engine không chặn việc đọc. Một template Recipe đọc .infra.replicas để điều khiển một trường values: vẫn hoạt động; không gì ngăn tuyến đọc chéo trụ cột. Mục tiêu của kỷ luật là biển chỉ dẫn — các ranh giới mô tả ý định biên soạn (ai sở hữu dữ liệu) chứ không phải hạn chế lúc chạy.

Được ghi tài liệu tại: vocabulary/data-pillars.md “Pillar boundaries and authoring discipline”.

Hậu quả khi vi phạm: Rò rỉ chéo trụ cột — payload nhận thức của developer chứa chi tiết kích thước vật lý, hoặc sizing do Ops biên soạn chứa metadata nhận thức. Build thành công; sự phân chia biên soạn bốn miền dần mờ đi khi tác giả đi tắt qua các trụ cột; việc bảo trì về sau khó hơn khi sự tương ứng giữa trụ cột và luồng dữ liệu suy yếu.

7. Ngữ nghĩa hai nguồn của Workload containers.<name>.variables

Map variables: kết hợp hai nguồn dữ liệu riêng biệt qua biểu thức Go template: literal thuộc trụ cột developer (các mục đọc .values / .infra / .locals) và dữ liệu đường ống liên component (các mục đọc .context.inject.env.<KEY>). Tác giả chọn một nguồn cho mỗi mục tùy theo giá trị là cục bộ của component hay được suy ra từ component khác.

Trình biên dịch không phân biệt hai nguồn; cả hai đều chảy vào cùng danh sách Kubernetes env: trên Deployment đã render. Ngữ nghĩa hai nguồn chỉ tồn tại lúc biên soạn — kỷ luật là thể hiện ý định (mục này là cục bộ của component; mục kia được suy ra từ component khác) để người bảo trì sau này đọc được mục nào phụ thuộc vào đầu ra inject-hydration nào.

Được ghi tài liệu tại: entities/workload.md “Field-semantics essentials” (variables).

Hậu quả khi vi phạm: Tác giả không phân biệt hai nguồn sẽ mất dấu vết “mục nào gắn với provides: của target nào”. Việc refactor các khóa provides: của một target âm thầm làm hỏng mọi mục variables: phía gọi đã đọc qua đường ống inject.

8. Kỷ luật đặt tên tài nguyên đám mây

Các Recipes phát ra tên tài nguyên đám mây (tên bucket S3, định danh cơ sở dữ liệu RDS, tên role IAM, tên stack CloudFormation — bất kỳ trường nào có giá trị nằm trong một không gian tên toàn cục tại nhà cung cấp đám mây) phải ghép {{ .metadata.release_name }} và/hoặc {{ .context.instance_id }} vào tên được render để tránh xung đột khi cùng một Recipe chạy trên nhiều Releases hoặc nhiều instance component.

Trình biên dịch không kiểm tra đầu ra valuesMapping: để tìm các trường tên tài nguyên đám mây thiếu các phép nội suy này. Kỷ luật này được duy trì bởi tác giả Recipe (người biết trường nào đặt tên cho tài nguyên duy nhất toàn cục với provider đích) và người review (người phát hiện các mẫu tài nguyên không được đặt tên khi review PR).

Được ghi tài liệu tại: entities/recipe.md “Cloud-resource naming discipline”.

Hậu quả khi vi phạm: Hai Releases của cùng một Aggregate (prod-billing và staging-billing) cùng cố triển khai một tài nguyên có cùng tên toàn cục; lần triển khai thứ hai thất bại lúc chạy do bị phía đám mây từ chối. Build Aggrega thành công; lỗi triển khai chỉ lộ ra khi Release thứ hai được áp dụng.

Không quy tắc nào của linter xuất bản kiểm tra các trường tên tài nguyên đám mây có các phép nội suy bắt buộc hay không; một plugin linter của riêng bạn có thể làm điều đó (xem Các quy ước mà một quy tắc linter kiểm tra).

9. Độ chi tiết của Component — một dịch vụ thống nhất cho mỗi Component

Một Component mô hình hóa một dịch vụ thống nhất — một dịch vụ được công khai duy nhất, hoặc (các) workload của một dịch vụ cùng với các workload hỗ trợ chỉ dùng nội bộ của nó. Khi một chart gói kèm các dịch vụ mà một component khác có thể use riêng một cách có ý nghĩa — đặc biệt là hạ tầng bên ngoài như cơ sở dữ liệu, cache hay message broker mà Aggrega đã mô hình hóa thành Component riêng — thư viện chuẩn kết hợp các Components theo từng dịch vụ thành một Module sub-aggregate (spec.aggregates + exportedComponents) thay vì bọc toàn bộ sản phẩm thành một Component mờ đục. Kỷ luật: nhiều workload trong một Component là ổn; khả năng sử dụng độc lập là ranh giới tách một Component thành một stack.

Trình biên dịch không phụ thuộc vào độ chi tiết này. Nó render bất cứ thứ gì vượt qua kiểm tra schema — nó không kiểm tra Recipe của một Component gói bao nhiêu dịch vụ, cũng không kiểm tra liệu một trong số đó có dùng độc lập được hay không. Tác giả bọc một sản phẩm năm dịch vụ thành một Component duy nhất sẽ tạo ra một Component mà trình biên dịch chấp nhận và render mà không phàn nàn; quy ước này được duy trì bởi kỷ luật biên soạn và sự chú ý của người review.

Được ghi tài liệu tại: ../../architecture/06-data-taxonomy-and-composition.md (Một dịch vụ thống nhất cho mỗi Component — ranh giới single-workload).

Hậu quả khi vi phạm: Một gói nhiều dịch vụ nguyên khối build thành công, nhưng các dịch vụ được gói kèm trở nên vô hình với topology, selector và policy — chúng không thể được scale, thay thế hay làm phụ thuộc một cách độc lập. Việc refactor khối nguyên khối thành các Components theo từng dịch vụ về sau là một thay đổi phá vỡ đối với mọi consumer đã tham chiếu đến node được bọc duy nhất đó.

Vì sao các quy ước tồn tại

Mỗi quy ước này theo thiết kế là kỷ luật soạn thảo, dù một schema hoặc một chính sách Wasm có thể thực thi bất kỳ quy ước nào trong số đó. Lý do theo từng loại khế ước:

Khả năng mở rộng. Kỷ luật tiền tố dành riêng (khế ước 3) mô tả bộ từ vựng của thư viện chuẩn, không phải toàn bộ từ vựng hợp lệ. Các catalog doanh nghiệp tự soạn tiền tố và khóa nhãn của riêng mình để mở rộng thư viện chuẩn; cưỡng chế quy ước tiền tố bằng schema sẽ biến “kỷ luật của thư viện chuẩn” thành “hình dạng duy nhất được ngôn ngữ cho phép” — đó chính là bức tường mà kiến trúc cố ý tránh. Trục loại vận hành (khế ước 1) giữ cùng khả năng mở rộng đó trên một bề mặt khác: khóa dành riêng mà Aggrega định nghĩa mang một tập giá trị đóng, được cưỡng chế bằng schema, và một catalog mở rộng bằng cách thêm một khóa nhãn của riêng mình bên cạnh nó thay vì một giá trị bên trong khóa của Aggrega. Điều schema kiểm tra là tập giá trị của một khóa mà nó sở hữu; điều vẫn để mở là mọi khóa khác, nơi bộ từ vựng riêng của một catalog tồn tại.

Tính thuần khiết AOT. Kỷ luật đặt tên tài nguyên đám mây (khế ước 8) và kỷ luật tính tất định (khế ước 5) đòi hỏi phải xem xét nội dung template để xác định một trường có phải là tên tài nguyên đám mây hay là một lời gọi helper không kín. Tính thuần khiết AOT (Invariant 2) giữ cho trình biên dịch không phụ thuộc vào trạng thái thời gian chạy; việc xem xét template tĩnh là khả thi (một plugin linter đọc các template của thực thể đúng như chúng được viết) nhưng thực hiện nó bên trong trình biên dịch lõi sẽ gắn logic nội bộ của trình biên dịch với các mối quan tâm soạn thảo theo từng miền. Kiến trúc chuyển các kiểm tra này ra khỏi trình biên dịch và vào các plugin Wasm theo Invariant 6 (Ranh giới Wasm ABI).

Tính linh hoạt khi soạn thảo. Kỷ luật ranh giới trụ cột (khế ước 6) và ngữ nghĩa hai nguồn của variables (khế ước 7) mô tả các mẫu soạn thảo chứ không phải ràng buộc thời gian chạy. Cùng một cú pháp template có thể biểu đạt một mẫu tuân thủ kỷ luật hoặc một mẫu vi phạm kỷ luật; biến kỷ luật thành một kiểm tra thời gian chạy sẽ đòi hỏi trình biên dịch diễn giải ý định soạn thảo mà nó không thể truy cập. Kiến trúc coi quy ước là tài liệu để tác giả học theo chứ không phải một bất biến thời gian chạy. Độ chi tiết của Component (khế ước 9) cũng thuộc nhóm này: doanh nghiệp có thể đóng gói một sản phẩm ở bất kỳ độ chi tiết nào mà catalog của họ ưa chuộng, và trình biên dịch — trung lập về nội dung và không có quan điểm riêng theo Invariant 1 — không có cách nào biết một workload được gộp có thể dùng độc lập hay không, nên ranh giới một-dịch-vụ-mạch-lạc vẫn là kỷ luật soạn thảo chứ không phải một bức tường schema. Lựa chọn loại vận hành (khế ước 1) có cùng hình dạng: schema xác định những giá trị nào tồn tại, nhưng giá trị nào mô tả một component cụ thể là một phán đoán mô hình hóa về cách hạ tầng phải đối xử với nó, và không có gì trong một Recipe hay một khối values cho trình biên dịch biết phán đoán đó có đúng hay không.

Thực thi theo hai nửa. Tính tự chứa của provides: trong Recipe (khế ước 4) được trình biên dịch cưỡng chế một phần — đường render phát hiện các lần đọc .context.inject / .context.uses trong các template provides: và dừng lại. Kỷ luật công khai-so-với-riêng tư rộng hơn (không phơi bày trạng thái nội bộ) được neo vào quy ước vì trình biên dịch không thể xác định chuỗi nào nên giữ nội bộ trong Recipe nếu không có ý định soạn thảo.

Ba con đường này quan trọng vì mỗi con đường cho biết trách nhiệm phát hiện vi phạm nằm ở đâu. Do schema thực thi: trình biên dịch. Do một plugin chính sách thực thi: plugin kiểm tra nó, ở nơi có plugin chạy. Được duy trì bằng quy ước: tác giả và người review. Tác giả nắm vững các con đường này sẽ hiểu lỗi nào trình biên dịch sẽ bắt và lỗi nào sẽ âm thầm lọt qua tới công cụ phía sau hoặc thời gian chạy.

Các quy ước mà một quy tắc linter kiểm tra

Linter xuất bản, do aggrega lint chạy, kiểm tra một phần một quy ước trên trang này: các khóa annotation của khế ước 3, ở bên dưới. Phát hiện của nó mang tính khuyến nghị, và phần quy ước mà nó không chạm tới được duy trì bằng quy ước, giống như các mục ở trên.

Không quy tắc nào của linter xuất bản kiểm tra bất kỳ quy ước nào khác trên trang này. Hai trong số đó có thể được một quy tắc linter kiểm tra, vì vi phạm được viết ngay trong thực thể: tính tất định (khế ước 5) — một template gọi một hàm trợ giúp không kín — và việc đặt tên tài nguyên đám mây (khế ước 8) — một đầu ra valuesMapping: đặt tên một tài nguyên đám mây mà không nội suy release_name / instance_id. Các khóa nhãn dưới các tiền tố dành riêng (khế ước 3) cũng vậy. Một workspace có thể gắn các plugin linter của riêng nó dưới plugins.linter, bên cạnh linter xuất bản, để kiểm tra bất kỳ quy ước nào trong số đó; The discipline rules liệt kê các quy tắc mà linter xuất bản mang theo.

Các quy ước còn lại (1, 2, 4, 6, 7, 9) phụ thuộc vào điều tác giả muốn nói, điều mà không quy tắc nào đọc được từ những gì đã viết. Việc tách nhóm được dẫn dắt bởi khả năng mở rộng (các catalog doanh nghiệp ghi đè) — thực thi bằng schema sẽ xung đột với sự linh hoạt đó. Phần còn lại của trục operational type sau khi schema đã cố định tập giá trị — việc chọn primitive phù hợp với component — được dẫn dắt bởi ý định soạn thảo: trình biên dịch không thể phân biệt một operational type được chọn tốt với một operational type được chọn kém, vì cả hai đều là các giá trị mà nó chấp nhận. Kỷ luật ranh giới pillar và ngữ nghĩa variables hai nguồn được dẫn dắt bởi ý định soạn thảo — trình biên dịch không thể xác định ý định chỉ từ cú pháp template. Tính tự chứa của provides: trong Recipe được thực thi một phần; kỷ luật công khai và riêng tư rộng hơn phụ thuộc vào việc tác giả định giữ những khóa nào ở dạng nội bộ, điều mà không gì trong Recipe nêu ra. Độ chi tiết của Component cũng được dẫn dắt bởi ý định soạn thảo — việc một workload được đóng gói có thể dùng độc lập hay không là một phán đoán mô hình hóa mà trình biên dịch không thể đọc được từ nội dung Recipe.

3. Kỷ luật tiền tố dành riêng

Các khóa annotation và nhãn tuân theo hình dạng <namespace>/<name>. Năm tiền tố dành riêng mang các quy tắc viết cụ thể: aggrega.ai/ (chỉ dành cho nền tảng), feature.aggrega.ai/ (các lối tắt Feature chính thức), component.aggrega.ai/ (các đặc tính nội tại của Component), aggregate.aggrega.ai/ (định danh module Aggregate), và <any-other-domain>/ (doanh nghiệp / cộng đồng).

Trình biên dịch không từ chối một annotation được viết dưới một tiền tố dành riêng trên một thực thể catalog hoặc một Release; chỉ một binding annotation của Manifest hoặc một nhãn đầu ra của Recipe chiếm một khóa dưới aggrega.ai/ mới làm dừng bản build. Một doanh nghiệp khai báo aggrega.ai/internal-billing-tag: "..." ngoài bộ từ vựng của nền tảng sẽ tạo ra một annotation mà trình biên dịch chấp nhận và truyền xuống qua hệ thống nhóm; các bản cập nhật nền tảng về sau giới thiệu một aggrega.ai/internal-billing-tag thực sự sẽ xung đột một cách âm thầm.

Được ghi lại tại: labels-and-annotations.md (Kỷ luật tiền tố) + providers/well-known-annotations.md.

Chế độ lỗi: Các annotation tùy chỉnh dưới tiền tố dành riêng xung đột với các annotation nền tảng trong tương lai có cùng tên; hành vi mong đợi của nền tảng âm thầm ghi đè hoặc cùng tồn tại với giá trị do doanh nghiệp viết, tùy theo thứ tự.

Linter xuất bản, do aggrega lint chạy, gắn cờ là một phát hiện mang tính khuyến nghị (E0277) một khóa annotation của thực thể catalog nằm dưới aggrega.ai/ mà không phải là một trong các annotation phổ biến của nền tảng, và một khóa dưới feature.aggrega.ai/ trên một thực thể không phải Feature. Các khóa nhãn, các tiền tố dành riêng khác và các annotation nằm ngoài metadata.annotations của thực thể — chẳng hạn những annotation mà một Release ghi — không được kiểm tra, nên đối với chúng kỷ luật vẫn là một quy ước.

Tham chiếu chéo