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.

Đọc đầu ra trên các trang này

Hầu hết các trang trong phần này cho bạn thấy cả đầu ra lẫn đầu vào: một tệp mà bản build đã ghi trong dist/, văn bản mà bản build in ra terminal của bạn, hoặc những gì một công cụ như tofu in ra khi bạn chạy nó trên những gì bản build đã ghi.

Các khối đó được sao chép từ một lần chạy thật, không phải viết tay. Hãy tự build ví dụ và bạn có thể so sánh đầu ra của mình với trang từng dòng một.

Sự so sánh đó chính là lý do đầu ra có mặt ở đây. Một số trang này yêu cầu bạn thay đổi một dòng rồi build lại, hoặc xóa một tệp đã render rồi chạy lại công cụ, sau đó đọc sự khác biệt. Một chỉ dẫn như vậy chỉ đáng làm theo nếu khối bạn đang so sánh là chính xác — nếu không, bạn không có cách nào phân biệt một khác biệt mà trang muốn bạn tìm ra với một khác biệt mà trang đơn giản là chưa bao giờ nhắc đến.

Vì vậy, một khối hiển thị đầu ra luôn ở một trong hai trạng thái, và không bao giờ ở đâu đó giữa hai trạng thái ấy.

Đầy đủ

Khối hiển thị toàn bộ những gì trang đã nêu tên. Khi phần dẫn nhập nói service web, mọi dòng của service đó đều có mặt. Khi nó nêu tên một tệp, toàn bộ tệp đều có mặt.

Một đoạn trích, có đánh dấu chỗ lược bỏ

Đầu ra thật thường dài, và in ra toàn bộ sẽ vùi lấp dòng duy nhất mà một trang đang giảng giải. Ở chỗ các dòng bị lược bỏ, khối sẽ nói rõ điều đó, trên một dòng riêng, tại đúng vị trí chúng bị lược bỏ:

[… omitted: what was left out]

Đây là cách dùng điều đó. Đây là một plan cho ví dụ terraform-declared-sensitivity, nơi điểm đang được nêu là về một thuộc tính:

# module.store.terraform_data.reference will be created
+ resource "terraform_data" "reference" {
[… omitted: an id attribute, reported as known only after apply]
+ input = (sensitive value)
[… omitted: an output attribute, reported as known only after apply]
+ triggers_replace = [
+ "app-artifacts",
+ "AKIAEXAMPLE0001",
]
}

Plan của bạn sẽ chứa hai thuộc tính đó. Dấu đánh là cách bạn biết chúng thuộc về chỗ đó — rằng đó là các dòng mà trang chọn không in lại, chứ không phải điều gì đó bản build của bạn đã làm khác đi. Một dấu đánh nằm ở mỗi chỗ có dòng bị bỏ, nên vị trí của chúng cũng dễ đọc như việc chúng vắng mặt.

Dấu đánh luôn nói cái gì đã bị bỏ, không bao giờ chỉ nói rằng có thứ đã bị bỏ. “Một thuộc tính id, được báo là chỉ biết được sau khi apply” cho bạn đủ thông tin để nhận ra dòng đó khi gặp nó; một dấu ba chấm trơn thì không.

Các dấu ngoặc vuông là có chủ ý. Một dòng bắt đầu bằng [… không phải nội dung hợp lệ trong YAML, HCL, JSON hay bất kỳ định dạng nào khác mà các trang này in ra, và không công cụ nào được trình bày ở đây in ra một dòng như vậy. Vì thế một dòng như vậy luôn là lời của trang, không bao giờ là thứ bản build tạo ra — nó không thể bị nhầm là đầu ra, cũng không thể bị bỏ sót khi đọc lướt.

Những gì không phải là lược bỏ

Bốn điều thay đổi diện mạo của một khối mà không bỏ sót gì, và không điều nào trong số đó cần dấu đánh:

  • Nêu tên một phạm vi nhỏ hơn. Một trang nói “service web” rồi hiển thị service đó thì không bỏ sót gì trong những gì nó đã nêu tên. Phần còn lại của tệp nằm ngoài phạm vi chứ không phải bị thiếu trong đó.
  • Thụt lề. Một đoạn được lấy ra từ một cấu trúc lồng sâu thường được hiển thị từ lề trái để nó tự đọc được. Các dòng là các dòng đã được xuất ra; chỉ có khoảng trắng đầu dòng thay đổi.
  • Chú thích hoặc ghi chú. Một dòng # nêu tên tệp mà các dòng đến từ đó, hoặc một ghi chú ngắn bên cạnh một giá trị, rõ ràng là lời của trang chứ không phải của bản build.
  • Một # trên mỗi dòng của một thông báo được trích dẫn. Khi một trang hiển thị một lệnh và thông báo nó in ra trong cùng một khối, thông báo được chuyển thành chú thích để toàn bộ khối vẫn chạy được. Một dòng in ra dài có thể được ngắt qua nhiều dòng # để vẫn dễ đọc ở độ rộng này. Dù theo cách nào, các từ vẫn là các từ đã in ra, theo đúng thứ tự đã in.

Dấu đánh tồn tại cho trường hợp duy nhất mà bạn không thể phát hiện bằng cách khác: các dòng đơn giản là không có ở đó.

Một khối minh họa thay vì tái hiện

Một vài trang ở đây là các bài hướng dẫn được viết ra chứ không phải các workspace bạn có thể build, và một hai trang hiển thị hình dạng của một payload thay vì một lần chạy cụ thể của nó. Một khối như vậy không mang lời hứa nào để bạn có thể diff, nên nó nói rõ điều đó trong lời văn xung quanh — nó không bao giờ âm thầm thay thế cho thứ thật. Nếu một khối không nói điều đó, nó đã được sao chép từ một lần chạy và hai trạng thái ở trên áp dụng cho nó.

Nếu bạn điều chỉnh một trong các trang này

Hãy giữ nguyên hai trạng thái đó. Khi đầu ra thay đổi — vì bạn đã thay đổi ví dụ, hoặc vì một bản phát hành mới hơn render nó khác đi — hãy thay khối bằng đầu ra từ một lần chạy thật thay vì chỉnh sửa bằng tay, và đánh dấu mọi dòng bạn lược bỏ. Một khối được chỉnh sửa để trông có vẻ đúng chính là điều mà quy ước này nhằm ngăn chặn, vì nó đọc y hệt một khối đã được kiểm tra.