Python cắt ngắn về 0
GHI CHÚ. Trang web này không được dùng nữa. Trang web sẽ ngừng hoạt động sau ngày 31 tháng 1 năm 2023 và lưu lượng truy cập sẽ chuyển hướng đến trang web mới tại https. // protobuf. nhà phát triển. Trong thời gian chờ đợi, các bản cập nhật sẽ chỉ được thực hiện cho protobuf. nhà phát triển Show
Hướng dẫn này mô tả cách sử dụng ngôn ngữ bộ đệm giao thức để cấu trúc dữ liệu bộ đệm giao thức của bạn, bao gồm cú pháp tệp 3 và cách tạo các lớp truy cập dữ liệu từ tệp 3 của bạn. Nó bao gồm phiên bản proto3 của ngôn ngữ bộ đệm giao thức. để biết thông tin về cú pháp proto2, xem Hướng dẫn ngôn ngữ Proto2Đây là hướng dẫn tham khảo – để biết ví dụ từng bước sử dụng nhiều tính năng được mô tả trong tài liệu này, hãy xem hướng dẫn cho ngôn ngữ bạn chọn (hiện chỉ có proto2; sắp có thêm tài liệu proto3) Xác định loại tin nhắnTrước tiên hãy xem một ví dụ rất đơn giản. Giả sử bạn muốn xác định định dạng thông báo yêu cầu tìm kiếm, trong đó mỗi yêu cầu tìm kiếm có một chuỗi truy vấn, trang kết quả cụ thể mà bạn quan tâm và một số kết quả trên mỗi trang. Đây là tệp 3 bạn sử dụng để xác định loại thư
Chỉ định loại trườngTrong ví dụ trên, tất cả các trường được. hai số nguyên ( 8 và 9) và một chuỗi ( 0). Tuy nhiên, bạn cũng có thể chỉ định các loại kết hợp cho các trường của mình, bao gồm và các loại thông báo khácGán số trườngNhư bạn có thể thấy, mỗi trường trong định nghĩa thông báo có một số duy nhất. Các số trường này được sử dụng để xác định các trường của bạn ở định dạng nhị phân thông báo và không được thay đổi sau khi loại thông báo của bạn được sử dụng. Lưu ý rằng số trường trong phạm vi từ 1 đến 15 mất một byte để mã hóa, bao gồm số trường và loại trường (bạn có thể tìm hiểu thêm về điều này trong). Số trường trong phạm vi 16 đến 2047 chiếm hai byte. Vì vậy, bạn nên dành các số từ 1 đến 15 cho các phần tử thông báo xuất hiện rất thường xuyên. Hãy nhớ để lại một số chỗ cho các yếu tố thường xuyên xuất hiện có thể được thêm vào trong tương lai Số trường nhỏ nhất bạn có thể chỉ định là 1 và số lớn nhất là 229 - 1 hoặc 536.870.911. Bạn cũng không thể sử dụng các số từ 19000 đến 19999 ( 1 đến 2), vì chúng được dành riêng cho việc triển khai Bộ đệm giao thức—trình biên dịch bộ đệm giao thức sẽ phàn nàn nếu bạn sử dụng một trong những số dành riêng này trong 3 của mình. Tương tự, bạn không thể sử dụng bất kỳ số trường nào trước đâyChỉ định quy tắc trườngCác trường tin nhắn có thể là một trong những trường sau
Trong proto3, các trường 8 của kiểu số vô hướng sử dụng mã hóa 1 theo mặc định. Bạn có thể tìm hiểu thêm về mã hóa 1 trongThêm các loại tin nhắn khácNhiều loại thông báo có thể được xác định trong một tệp 3. Điều này hữu ích nếu bạn đang xác định nhiều thư có liên quan – vì vậy, ví dụ: nếu bạn muốn xác định định dạng thư trả lời tương ứng với loại thư 4 của mình, bạn có thể thêm nó vào cùng một thư 3
Thêm Nhận xétĐể thêm nhận xét vào tệp 3 của bạn, hãy sử dụng cú pháp kiểu C/C++ 7 và 8
Trường dành riêngNếu bạn loại thông báo bằng cách xóa hoàn toàn một trường hoặc nhận xét nó, thì người dùng trong tương lai có thể sử dụng lại số trường khi thực hiện cập nhật của riêng họ cho loại. Điều này có thể gây ra sự cố nghiêm trọng nếu sau đó họ tải các phiên bản cũ của cùng một 3, bao gồm hỏng dữ liệu, lỗi bảo mật, v.v. Một cách để đảm bảo điều này không xảy ra là chỉ định rằng số trường (và/hoặc tên, cũng có thể gây ra sự cố cho việc tuần tự hóa JSON) của các trường đã xóa của bạn là 0. Trình biên dịch bộ đệm giao thức sẽ khiếu nại nếu bất kỳ người dùng nào trong tương lai cố gắng sử dụng các mã định danh trường này
Lưu ý rằng bạn không thể trộn lẫn tên trường và số trường trong cùng một câu lệnh 0Điều gì được tạo ra từ message Foo { reserved 2, 15, 9 to 11; reserved "foo", "bar"; } 3 của bạn?Khi bạn chạy trên 3, trình biên dịch sẽ tạo mã bằng ngôn ngữ bạn chọn, bạn sẽ cần làm việc với các loại thông báo bạn đã mô tả trong tệp, bao gồm nhận và đặt giá trị trường, tuần tự hóa thông báo của bạn thành luồng đầu ra,
Bạn có thể tìm hiểu thêm về cách sử dụng API cho từng ngôn ngữ bằng cách làm theo hướng dẫn cho ngôn ngữ bạn chọn (sắp có phiên bản proto3). Để biết thêm chi tiết về API, hãy xem tài liệu tham khảo API có liên quan (sắp có phiên bản proto3) Các loại giá trị vô hướngTrường thông báo vô hướng có thể có một trong các loại sau – bảng hiển thị loại được chỉ định trong tệp 3 và loại tương ứng trong lớp được tạo tự độngproto TypeNotesC++ TypeJava/Kotlin Type[1]Python Type[3]Go TypeRuby TypeC# TypePHP TypeDart Typedoubledoubledoublefloatfloat64Floatdoublefloatdoublefloatfloatfloatfloatfloat32Floatfloatfloatdoubleint32Sử dụng mã hóa có độ dài thay đổi. Không hiệu quả để mã hóa số âm – nếu trường của bạn có thể có giá trị âm, hãy sử dụng sint32 để thay thế. int32intintint32Fixnum hoặc Bignum (theo yêu cầu)intintegerintint64Sử dụng mã hóa có độ dài thay đổi. Mã hóa số âm không hiệu quả – nếu trường của bạn có thể có giá trị âm, hãy sử dụng sint64 để thay thế. int64longint/long[4]int64Bignumlonginteger/string[6]Int64uint32Sử dụng mã hóa có độ dài thay đổi. uint32int[2]int/long[4]uint32Fixnum hoặc Bignum (theo yêu cầu)uintintegerintuint64Sử dụng mã hóa có độ dài thay đổi. uint64long[2]int/long[4]uint64Bignumulonginteger/string[6]Int64sint32Sử dụng mã hóa có độ dài thay đổi. Giá trị int đã ký. Những số âm này mã hóa hiệu quả hơn so với int32 thông thường. int32intintint32Fixnum hoặc Bignum (theo yêu cầu)intintegerintsint64Sử dụng mã hóa có độ dài thay đổi. Giá trị int đã ký. Những số âm này mã hóa hiệu quả hơn so với int64 thông thường. int64longint/long[4]int64Bignumlonginteger/string[6]Int64fixed32Luôn luôn bốn byte. Hiệu quả hơn uint32 nếu giá trị thường lớn hơn 228. uint32int[2]int/long[4]uint32Fixnum hoặc Bignum (theo yêu cầu)uintintegerintfixed64Luôn tám byte. Hiệu quả hơn uint64 nếu giá trị thường lớn hơn 256. uint64long[2]int/long[4]uint64Bignumulonginteger/string[6]Int64sfixed32Luôn luôn bốn byte. int32intintint32Fixnum hoặc Bignum (theo yêu cầu)intintegerintsfixed64Luôn tám byte. int64longint/long[4]int64Bignumlonginteger/string[6]Int64boolboolbooleanboolboolTrueClass/FalseClassboolbooleanboolstringMột chuỗi phải luôn chứa văn bản ASCII 7 bit hoặc mã hóa UTF-8 và không được dài hơn 232. stringStringstr/unicode[5]stringString (UTF-8)stringstringStringbytesCó thể chứa bất kỳ chuỗi byte tùy ý nào không dài hơn 232. stringByteStringstr (Python 2) Bạn có thể tìm hiểu thêm về cách các loại này được mã hóa khi bạn đánh số thứ tự thư của mình trong Mã hóa bộ đệm giao thức [1] Kotlin sử dụng các loại tương ứng từ Java, ngay cả đối với các loại không dấu, để đảm bảo khả năng tương thích trong các cơ sở mã Java/Kotlin hỗn hợp [2] Trong Java, các số nguyên 32 bit và 64 bit không dấu được biểu diễn bằng cách sử dụng các số nguyên có dấu của chúng, với bit trên cùng chỉ đơn giản là được lưu trữ trong bit dấu [3] Trong mọi trường hợp, việc đặt giá trị cho một trường sẽ thực hiện kiểm tra loại để đảm bảo trường đó hợp lệ [4] Các số nguyên 32 bit 64 bit hoặc không dấu luôn được biểu thị bằng long khi được giải mã, nhưng có thể là một số nguyên nếu một số int được cung cấp khi đặt trường. Trong mọi trường hợp, giá trị phải phù hợp với loại được biểu thị khi đặt. Xem [2] [5] Các chuỗi Python được biểu diễn dưới dạng unicode khi giải mã nhưng có thể là str nếu một chuỗi ASCII được cung cấp (điều này có thể thay đổi) [6] Số nguyên được sử dụng trên máy 64 bit và chuỗi được sử dụng trên máy 32 bit Giá trị mặc địnhKhi một thông báo được phân tích cú pháp, nếu thông báo được mã hóa không chứa một phần tử số ít cụ thể, thì trường tương ứng trong đối tượng được phân tích cú pháp được đặt thành giá trị mặc định cho trường đó. Các giá trị mặc định này là loại cụ thể
Giá trị mặc định cho các trường lặp lại là trống (thường là danh sách trống bằng ngôn ngữ thích hợp) Lưu ý rằng đối với các trường thông báo vô hướng, sau khi một thông báo được phân tích cú pháp, không có cách nào để biết liệu một trường có được đặt rõ ràng thành giá trị mặc định hay không (ví dụ: liệu một boolean đã được đặt thành 0) hay hoàn toàn không được đặt. bạn nên ghi nhớ điều này khi xác định loại tin nhắn của mình. Ví dụ: không có boolean bật một số hành vi khi được đặt thành 0 nếu bạn không muốn hành vi đó cũng xảy ra theo mặc định. Cũng lưu ý rằng nếu trường thông báo vô hướng được đặt thành mặc định, giá trị sẽ không được đánh số thứ tự trên dâyXem hướng dẫn mã được tạo cho ngôn ngữ bạn đã chọn để biết thêm chi tiết về cách hoạt động mặc định trong mã được tạo phép liệt kêKhi bạn đang xác định loại thông báo, bạn có thể muốn một trong các trường của nó chỉ có một trong danh sách giá trị được xác định trước. Ví dụ: giả sử bạn muốn thêm trường 2 cho mỗi 7, trong đó kho văn bản có thể là 4, 5, 6, 7, 8, 9 hoặc 0. Bạn có thể làm điều này rất đơn giản bằng cách thêm một 1 vào định nghĩa thư của bạn với một hằng số cho mỗi giá trị có thểTrong ví dụ sau, chúng tôi đã thêm một 1 được gọi là 3 với tất cả các giá trị có thể và một trường loại 3________số 8_______Như bạn có thể thấy, hằng số đầu tiên của 3 enum ánh xạ tới 0. mọi định nghĩa enum phải chứa một hằng số ánh xạ tới 0 làm phần tử đầu tiên của nó. Điều này là do
Bạn có thể xác định bí danh bằng cách gán cùng một giá trị cho các hằng số enum khác nhau. Để làm điều này, bạn cần đặt tùy chọn 6 thành 7, nếu không, trình biên dịch giao thức sẽ tạo thông báo lỗi khi tìm thấy bí danh. Mặc dù tất cả các giá trị bí danh đều hợp lệ trong quá trình giải tuần tự hóa, nhưng giá trị đầu tiên luôn được sử dụng khi tuần tự hóa
Hằng số liệt kê phải nằm trong phạm vi số nguyên 32 bit. Vì các giá trị 1 sử dụng mã hóa varint trên dây nên các giá trị âm không hiệu quả và do đó không được khuyến nghị. Bạn có thể xác định các ____61_______1 bên trong định nghĩa thông báo, như trong ví dụ trên hoặc bên ngoài – các ____61_______1 này có thể được sử dụng lại trong bất kỳ định nghĩa thông báo nào trong tệp 3 của bạn. Bạn cũng có thể sử dụng loại 1 được khai báo trong một tin nhắn làm loại trường trong một tin nhắn khác, sử dụng cú pháp 03Khi bạn chạy trình biên dịch bộ đệm giao thức trên một 3 sử dụng một 1, mã được tạo ra sẽ có một ____61_______1 tương ứng cho Java, Kotlin hoặc C++ hoặc một lớp đặc biệt 07 cho Python được sử dụng để tạo một tập hợp các hằng ký hiệu với các giá trị nguyên ** Thận trọng. ** mã được tạo có thể bị giới hạn theo ngôn ngữ cụ thể về số lượng điều tra viên (nghìn thấp cho một ngôn ngữ). Vui lòng xem lại các giới hạn đối với ngôn ngữ bạn định sử dụngTrong quá trình khử lưu huỳnh, các giá trị enum không được nhận dạng sẽ được giữ nguyên trong thông báo, mặc dù cách thức này được biểu thị khi thông báo được giải tuần tự hóa phụ thuộc vào ngôn ngữ. Trong các ngôn ngữ hỗ trợ các kiểu enum mở với các giá trị nằm ngoài phạm vi của các ký hiệu đã chỉ định, chẳng hạn như C++ và Go, giá trị enum không xác định được lưu trữ đơn giản dưới dạng biểu diễn số nguyên cơ bản của nó. Trong các ngôn ngữ có kiểu enum đóng, chẳng hạn như Java, một trường hợp trong enum được sử dụng để biểu thị một giá trị không được nhận dạng và số nguyên bên dưới có thể được truy cập bằng các bộ truy cập đặc biệt. Trong cả hai trường hợp, nếu thông báo được đánh số thứ tự thì giá trị không được nhận dạng sẽ vẫn được đánh số thứ tự cùng với thông báo Để biết thêm thông tin về cách làm việc với thông báo 1 trong ứng dụng của bạn, hãy xem hướng dẫn mã được tạo cho ngôn ngữ bạn chọnGiá trị dành riêngNếu bạn là một loại enum bằng cách xóa hoàn toàn một mục nhập enum hoặc nhận xét nó, những người dùng trong tương lai có thể sử dụng lại giá trị số khi thực hiện cập nhật của riêng họ cho loại. Điều này có thể gây ra sự cố nghiêm trọng nếu sau đó họ tải các phiên bản cũ của cùng một 3, bao gồm hỏng dữ liệu, lỗi bảo mật, v.v. Một cách để đảm bảo điều này không xảy ra là chỉ định rằng các giá trị số (và/hoặc tên, cũng có thể gây ra sự cố cho quá trình tuần tự hóa JSON) của các mục nhập đã xóa của bạn là 0. Trình biên dịch bộ đệm giao thức sẽ khiếu nại nếu bất kỳ người dùng nào trong tương lai cố gắng sử dụng các mã định danh này. Bạn có thể chỉ định rằng phạm vi giá trị số dành riêng của bạn tăng lên giá trị tối đa có thể bằng cách sử dụng từ khóa 11
Lưu ý rằng bạn không thể kết hợp tên trường và giá trị số trong cùng một câu lệnh 0Sử dụng các loại tin nhắn khácBạn có thể sử dụng các loại thông báo khác làm loại trường. Ví dụ: giả sử bạn muốn bao gồm các thư 13 trong mỗi thư 4 – để làm điều này, bạn có thể xác định một loại thư 13 trong cùng một thư 3 và sau đó chỉ định một trường loại 13 trong 4
Nhập định nghĩaTrong ví dụ trên, loại thông báo 13 được xác định trong cùng một tệp như 4 – nếu loại thông báo bạn muốn sử dụng làm loại trường đã được xác định trong một tệp 3 khác thì sao?Bạn có thể sử dụng định nghĩa từ các tệp 3 khác bằng cách nhập chúng. Để nhập định nghĩa của 3 khác, bạn thêm câu lệnh nhập vào đầu tệp của mình
Theo mặc định, bạn chỉ có thể sử dụng các định nghĩa từ tệp 3 được nhập trực tiếp. Tuy nhiên, đôi khi bạn có thể cần di chuyển tệp 3 đến một vị trí mới. Thay vì di chuyển trực tiếp tệp 3 và cập nhật tất cả các vị trí cuộc gọi trong một lần thay đổi, bạn có thể đặt tệp giữ chỗ 3 ở vị trí cũ để chuyển tiếp tất cả các lần nhập sang vị trí mới bằng cách sử dụng khái niệm 28Lưu ý rằng chức năng nhập công khai không khả dụng trong Java Các phụ thuộc của 28 có thể được dựa vào quá độ bởi bất kỳ mã nào nhập nguyên mẫu có chứa câu lệnh 28. Ví dụ
0 1Trình biên dịch giao thức tìm kiếm các tệp đã nhập trong một tập hợp các thư mục được chỉ định trên dòng lệnh của trình biên dịch giao thức bằng cách sử dụng cờ 31/ 32. Nếu không có cờ nào được đưa ra, nó sẽ tìm trong thư mục mà trình biên dịch được gọi. Nói chung, bạn nên đặt cờ 32 cho thư mục gốc của dự án và sử dụng các tên đủ điều kiện cho tất cả các mục nhậpSử dụng các loại tin nhắn proto2Có thể nhập các loại tin nhắn proto2 và sử dụng chúng trong tin nhắn proto3 của bạn và ngược lại. Tuy nhiên, không thể sử dụng trực tiếp enums proto2 trong cú pháp proto3 (không sao nếu thông báo proto2 đã nhập sử dụng chúng) Các loại lồng nhauBạn có thể xác định và sử dụng các loại thông báo bên trong các loại thông báo khác, như trong ví dụ sau – ở đây thông báo 13 được xác định bên trong thông báo 4 2Nếu bạn muốn sử dụng lại loại tin nhắn này bên ngoài loại tin nhắn gốc của nó, bạn gọi nó là 36 3Bạn có thể lồng các tin nhắn sâu như bạn muốn 4Cập nhật loại tin nhắnNếu một loại thông báo hiện có không còn đáp ứng tất cả các nhu cầu của bạn – ví dụ: bạn muốn định dạng thông báo có thêm một trường – nhưng bạn vẫn muốn sử dụng mã được tạo bằng định dạng cũ, đừng lo lắng. Rất đơn giản để cập nhật các loại thông báo mà không vi phạm bất kỳ mã hiện có nào của bạn. Chỉ cần nhớ các quy tắc sau
Trường không xác địnhCác trường không xác định là dữ liệu được tuần tự hóa trong bộ đệm giao thức được định dạng tốt biểu thị các trường mà trình phân tích cú pháp không nhận ra. Ví dụ: khi một nhị phân cũ phân tích dữ liệu được gửi bởi một nhị phân mới với các trường mới, những trường mới đó trở thành các trường không xác định trong nhị phân cũ Ban đầu, các thông báo proto3 luôn loại bỏ các trường không xác định trong quá trình phân tích cú pháp, nhưng trong phiên bản 3. 5, chúng tôi đã giới thiệu lại việc bảo tồn các trường không xác định để phù hợp với hành vi proto2. Trong phiên bản 3. 5 trở lên, các trường không xác định được giữ lại trong quá trình phân tích cú pháp và được đưa vào đầu ra được tuần tự hóa Không tí nàoLoại thông báo 67 cho phép bạn sử dụng thông báo dưới dạng các loại được nhúng mà không cần. độ nét nguyên thủy. Một 67 chứa một thông báo được đánh số thứ tự tùy ý là 46, cùng với một URL hoạt động như một mã định danh duy nhất trên toàn cầu và phân giải thành loại của thông báo đó. Để sử dụng loại 67, bạn cần phải 71 5URL loại mặc định cho một loại thông báo nhất định là 72Các triển khai ngôn ngữ khác nhau sẽ hỗ trợ người trợ giúp thư viện thời gian chạy để đóng gói và giải nén các giá trị 67 theo cách an toàn về kiểu – ví dụ: trong Java, kiểu 67 sẽ có các trình truy cập đặc biệt 75 và 76, trong khi ở C++ có các phương thức 77 và 78 6Hiện tại các thư viện thời gian chạy để làm việc với các loại 67 đang được phát triểnNếu bạn đã quen thuộc với cú pháp proto2, thì 67 có thể chứa các tin nhắn proto3 tùy ý, tương tự như các tin nhắn proto2 có thể cho phépMột trongNếu bạn có một thư có nhiều trường và nơi tối đa một trường sẽ được đặt cùng lúc, bạn có thể thực thi hành vi này và tiết kiệm bộ nhớ bằng cách sử dụng tính năng một trong những Một trong các trường giống như các trường thông thường ngoại trừ tất cả các trường trong một bộ nhớ dùng chung và nhiều nhất một trường có thể được đặt cùng một lúc. Đặt bất kỳ thành viên nào của oneof sẽ tự động xóa tất cả các thành viên khác. Bạn có thể kiểm tra xem giá trị nào trong một trong số được đặt (nếu có) bằng cách sử dụng phương pháp 81 hoặc 82 đặc biệt, tùy thuộc vào ngôn ngữ bạn đã chọnLưu ý rằng nếu nhiều giá trị được đặt, giá trị được đặt cuối cùng được xác định theo thứ tự trong proto sẽ ghi đè lên tất cả các giá trị trước đó Sử dụng OneofĐể xác định một trong số trong 3 của bạn, bạn sử dụng từ khóa 62 theo sau là tên của một trong số bạn, trong trường hợp này là 85 7Sau đó, bạn thêm các trường oneof của mình vào định nghĩa oneof. Bạn có thể thêm các trường thuộc bất kỳ loại nào, ngoại trừ trường 9 và trường 8Trong mã được tạo của bạn, một trong các trường có cùng getters và setters như các trường thông thường. Bạn cũng có một phương pháp đặc biệt để kiểm tra xem giá trị nào (nếu có) trong oneof được đặt. Bạn có thể tìm hiểu thêm về API oneof cho ngôn ngữ bạn đã chọn trong tài liệu tham khảo API có liên quan Một trong những tính năng
Vấn đề tương thích ngượcHãy cẩn thận khi thêm hoặc xóa một trong các trường. Nếu kiểm tra giá trị của một trong số trả về 96/ 97, điều đó có thể có nghĩa là một trong số đó chưa được đặt hoặc nó đã được đặt thành một trường trong một phiên bản khác của một trong số đó. Không có cách nào để phân biệt sự khác biệt, vì không có cách nào để biết liệu một trường chưa biết trên dây có phải là thành viên của một trường khôngVấn đề sử dụng lại thẻ
bản đồNếu bạn muốn tạo bản đồ kết hợp như một phần của định nghĩa dữ liệu của mình, bộ đệm giao thức cung cấp cú pháp phím tắt tiện dụng 1trong đó 98 có thể là bất kỳ loại tích phân hoặc chuỗi nào (vì vậy, bất kỳ loại nào ngoại trừ các loại dấu phẩy động và 46). Lưu ý rằng enum không phải là một 98 hợp lệ. 01 có thể là bất kỳ loại nào ngoại trừ bản đồ khácVì vậy, ví dụ: nếu bạn muốn tạo bản đồ các dự án trong đó mỗi thông báo 02 được liên kết với một khóa chuỗi, bạn có thể xác định nó như sau 2
API bản đồ được tạo hiện có sẵn cho tất cả các ngôn ngữ được hỗ trợ proto3. Bạn có thể tìm hiểu thêm về API bản đồ cho ngôn ngữ bạn đã chọn trong tài liệu tham khảo API có liên quan Tương thích ngượcCú pháp bản đồ tương đương với cú pháp sau trên dây, vì vậy việc triển khai bộ đệm giao thức không hỗ trợ bản đồ vẫn có thể xử lý dữ liệu của bạn 3Mọi triển khai bộ đệm giao thức hỗ trợ bản đồ đều phải tạo và chấp nhận dữ liệu có thể được chấp nhận theo định nghĩa trên góiBạn có thể thêm một mã xác định 05 tùy chọn vào tệp 3 để tránh xung đột tên giữa các loại thông báo giao thức 4Sau đó, bạn có thể sử dụng trình xác định gói khi xác định các trường thuộc loại thông báo của mình 5Cách trình xác định gói ảnh hưởng đến mã được tạo tùy thuộc vào ngôn ngữ bạn đã chọn
Độ phân giải gói và tênNhập độ phân giải tên trong ngôn ngữ bộ đệm giao thức hoạt động như C++. đầu tiên, phạm vi trong cùng được tìm kiếm, sau đó là phạm vi trong cùng tiếp theo, v.v., với mỗi gói được coi là "bên trong" đối với gói mẹ của nó. Một sự dẫn đầu '. ' (ví dụ: 20) có nghĩa là bắt đầu từ phạm vi ngoài cùng thay vìTrình biên dịch bộ đệm giao thức giải quyết tất cả các tên loại bằng cách phân tích cú pháp các tệp 3 đã nhập. Trình tạo mã cho mỗi ngôn ngữ biết cách đề cập đến từng loại trong ngôn ngữ đó, ngay cả khi ngôn ngữ đó có các quy tắc phạm vi khác nhauXác định dịch vụNếu bạn muốn sử dụng các loại thông báo của mình với hệ thống RPC (Gọi thủ tục từ xa), bạn có thể xác định giao diện dịch vụ RPC trong tệp 3 và trình biên dịch bộ đệm giao thức sẽ tạo mã giao diện dịch vụ và sơ khai bằng ngôn ngữ bạn đã chọn. Vì vậy, ví dụ: nếu bạn muốn xác định một dịch vụ RPC bằng một phương thức lấy 7 của bạn và trả về một 4, bạn có thể xác định dịch vụ đó trong tệp 3 của mình như sau 6Hệ thống RPC đơn giản nhất để sử dụng với bộ đệm giao thức là gRPC. một hệ thống RPC nguồn mở trung lập về ngôn ngữ và nền tảng được phát triển tại Google. gRPC hoạt động đặc biệt hiệu quả với bộ đệm giao thức và cho phép bạn tạo mã RPC có liên quan trực tiếp từ tệp 3 của mình bằng plugin trình biên dịch bộ đệm giao thức đặc biệtNếu bạn không muốn sử dụng gRPC, bạn cũng có thể sử dụng bộ đệm giao thức với triển khai RPC của riêng mình. Bạn có thể tìm hiểu thêm về điều này trong Ngoài ra còn có một số dự án của bên thứ ba đang diễn ra để phát triển triển khai RPC cho Bộ đệm giao thức. Để biết danh sách các liên kết đến các dự án mà chúng tôi biết, hãy xem trang wiki tiện ích bổ sung của bên thứ ba Ánh xạ JSONProto3 hỗ trợ mã hóa chuẩn trong JSON, giúp chia sẻ dữ liệu giữa các hệ thống dễ dàng hơn. Mã hóa được mô tả trên cơ sở từng loại trong bảng bên dưới Khi phân tích cú pháp dữ liệu được mã hóa JSON vào bộ đệm giao thức, nếu một giá trị bị thiếu hoặc nếu giá trị của nó là 27, thì nó sẽ được hiểu là giá trị tương ứngKhi tạo đầu ra được mã hóa JSON từ bộ đệm giao thức, nếu trường protobuf có giá trị mặc định và nếu trường không hỗ trợ sự hiện diện của trường, thì nó sẽ bị bỏ qua khỏi đầu ra theo mặc định. Việc triển khai có thể cung cấp các tùy chọn để bao gồm các trường có giá trị mặc định trong đầu ra Trường proto3 được xác định bằng từ khóa 5 hỗ trợ sự hiện diện của trường. Các trường có một bộ giá trị và sự hiện diện của trường hỗ trợ đó luôn bao gồm giá trị trường trong đầu ra được mã hóa JSON, ngay cả khi đó là giá trị mặc địnhproto3JSONJSON exampleNotesmessageobject 29Generates JSON objects. Message field names are mapped to lowerCamelCase and become JSON object keys. If the 30 field option is specified, the specified value will be used as the key instead. Parsers accept both the lowerCamelCase name (or the one specified by the 30 option) and the original proto field name. 27 is an accepted value for all field types and treated as the default value of the corresponding field type.enumstring 33The name of the enum value as specified in proto is used. Parsers accept both enum names and integer values.map 34All keys are converted to strings.repeated Varray 35 27 is accepted as the empty list 37.booltrue, false 38stringstring 39bytesbase64 string 40JSON value will be the data encoded as a string using standard base64 encoding with paddings. Either standard or URL-safe base64 encoding with/without paddings are accepted.int32, fixed32, uint32number 41JSON value will be a decimal number. Either numbers or strings are accepted.int64, fixed64, uint64string 42JSON value will be a decimal string. Either numbers or strings are accepted.float, doublenumber 43JSON value will be a number or one of the special string values "NaN", "Infinity", and "-Infinity". Either numbers or strings are accepted. Exponent notation is also accepted. -0 is considered equivalent to 0.Any 44 45If the 67 contains a value that has a special JSON mapping, it will be converted as follows: 47. Otherwise, the value will be converted into a JSON object, and the 48 field will be inserted to indicate the actual data type.Timestampstring 49Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted.Durationstring 50Generated output always contains 0, 3, 6, or 9 fractional digits, depending on required precision, followed by the suffix "s". Accepted are any fractional digits (also none) as long as they fit into nano-seconds precision and the suffix "s" is required.Struct 44 52Any JSON object. See 53.Wrapper typesvarious types 54Wrappers use the same representation in JSON as the wrapped primitive type, except that 27 is allowed and preserved during data conversion and transfer.FieldMaskstring 56See 57.ListValuearray 58ValuevalueAny JSON value. Check for details.NullValuenullJSON nullEmptyobject 59An empty JSON objecttùy chọn JSONViệc triển khai JSON proto3 có thể cung cấp các tùy chọn sau
Tùy chọnCác khai báo riêng lẻ trong tệp 3 có thể được chú thích bằng một số tùy chọn. Các tùy chọn không thay đổi ý nghĩa tổng thể của một tuyên bố, nhưng có thể ảnh hưởng đến cách nó được xử lý trong một ngữ cảnh cụ thể. Danh sách đầy đủ các tùy chọn có sẵn được xác định trong 61Một số tùy chọn là tùy chọn cấp tệp, nghĩa là chúng phải được viết ở phạm vi cấp cao nhất, không nằm trong bất kỳ thông báo, enum hoặc định nghĩa dịch vụ nào. Một số tùy chọn là tùy chọn cấp thông báo, nghĩa là chúng phải được viết bên trong định nghĩa thông báo. Một số tùy chọn là tùy chọn cấp trường, nghĩa là chúng phải được viết bên trong định nghĩa trường. Các tùy chọn cũng có thể được viết trên các loại enum, giá trị enum, một trong các trường, loại dịch vụ và phương thức dịch vụ; Dưới đây là một số tùy chọn được sử dụng phổ biến nhất
Tùy chọn tùy chỉnhBộ đệm giao thức cũng cho phép bạn xác định và sử dụng các tùy chọn của riêng mình. Đây là một tính năng nâng cao mà hầu hết mọi người không cần. Nếu bạn nghĩ rằng bạn cần tạo các tùy chọn của riêng mình, hãy xem phần để biết chi tiết. Lưu ý rằng việc tạo các tùy chọn tùy chỉnh sử dụng , chỉ được phép cho các tùy chọn tùy chỉnh trong proto3 Tạo các lớp học của bạnĐể tạo mã Java, Kotlin, Python, C++, Go, Ruby, Objective-C hoặc C#, bạn cần làm việc với các loại thông báo được xác định trong tệp 3, bạn cần chạy trình biên dịch bộ đệm giao thức ________0____02 trên 3. Nếu bạn chưa cài đặt trình biên dịch, hãy tải xuống gói và làm theo hướng dẫn trong README. Đối với Go, bạn cũng cần cài đặt plugin tạo mã đặc biệt cho trình biên dịch. bạn có thể tìm hướng dẫn này và hướng dẫn cài đặt trong kho lưu trữ golang/protobuf trên GitHubTrình biên dịch giao thức được gọi như sau 2
Vị trí tập tinKhông muốn đặt các tệp 3 trong cùng thư mục với các nguồn ngôn ngữ khác. Xem xét việc tạo một gói con 36 cho các tệp 3, bên dưới gói gốc cho dự án của bạnVị trí phải là ngôn ngữ bất khả triKhi làm việc với mã Java, thật tiện lợi khi đặt các tệp 3 có liên quan trong cùng thư mục với nguồn Java. Tuy nhiên, nếu bất kỳ mã không phải Java nào sử dụng cùng một protos, thì tiền tố đường dẫn sẽ không còn ý nghĩa nữa. Vì vậy, nói chung, hãy đặt các protos trong một thư mục liên quan đến ngôn ngữ bất khả tri, chẳng hạn như 39Ngoại lệ đối với quy tắc này là khi rõ ràng rằng các proto sẽ chỉ được sử dụng trong ngữ cảnh Java, chẳng hạn như để thử nghiệm |