Byte python thành chuỗi
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 Show
Đâ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 tin nhắn
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 mất 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ẽ khiếu nại nếu bạn sử dụng một trong các 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 91 theo mặc định. Bạn có thể tìm hiểu thêm về mã hóa 91 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ư 94 của mình, bạn có thể thêm nó vào cùng một 3 4Thê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 97 và 98 kiểu C/C++ 8Trườ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à 00. 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 tên trường và số trường trong cùng một câu lệnh 00Đ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ự động.proto TypeNotesC++ TypeJava/Kotlin Type[1]Python Type[3]Go TypeRuby TypeC# TypePHP TypeDart Typedoubledoubledoublefloatfloat64Floatdoublefloatdoublefloatfloatfloatfloatfloat32Floatfloatfloatdoubleint32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32Fixnum or Bignum (as required)intintegerintint64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/long[4]int64Bignumlonginteger/string[6]Int64uint32Uses variable-length encoding.uint32int[2]int/long[4]uint32Fixnum or Bignum (as required)uintintegerintuint64Uses variable-length encoding.uint64long[2]int/long[4]uint64Bignumulonginteger/string[6]Int64sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32Fixnum or Bignum (as required)intintegerintsint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/long[4]int64Bignumlonginteger/string[6]Int64fixed32Always four bytes. More efficient than uint32 if values are often greater than 228.uint32int[2]int/long[4]uint32Fixnum or Bignum (as required)uintintegerintfixed64Always eight bytes. More efficient than uint64 if values are often greater than 256.uint64long[2]int/long[4]uint64Bignumulonginteger/string[6]Int64sfixed32Always four bytes.int32intintint32Fixnum or Bignum (as required)intintegerintsfixed64Always eight bytes.int64longint/long[4]int64Bignumlonginteger/string[6]Int64boolboolbooleanboolboolTrueClass/FalseClassboolbooleanboolstringA string must always contain UTF-8 encoded or 7-bit ASCII text, and cannot be longer than 232.stringStringstr/unicode[5]stringString (UTF-8)stringstringStringbytesMay contain any arbitrary sequence of bytes no longer than 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 boolean có được đặt thành 10 hay không) 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 10 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 12 cho mỗi 7, trong đó kho văn bản có thể là 14, 15, 16, 17, 18, 19 hoặc 10. Bạn có thể làm điều này rất đơn giản bằng cách thêm một 11 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 11 được gọi là 13 với tất cả các giá trị có thể và một trường loại 13________số 8Như bạn có thể thấy, hằng số đầu tiên của 13 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 16 thành 17, 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 9Hằng số liệt kê phải nằm trong phạm vi số nguyên 32 bit. Vì các giá trị 11 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 11 bên trong định nghĩa thông báo, như trong ví dụ trên hoặc bên ngoài – những 11 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 11 đượ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 403Khi 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 11, mã được tạo ra sẽ có một 11 tương ứng cho Java, Kotlin hoặc C++ hoặc một lớp 407 đặc biệt 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 11 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 đã xóa của bạn là 00. 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 411 0Lư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 00Sử 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 thông báo 413 trong mỗi thông báo 94 – để làm điều này, bạn có thể xác định loại thông báo 413 trong cùng một 3 và sau đó chỉ định trường loại 413 trong 94 2Nhập định nghĩaTrong ví dụ trên, loại thông báo 413 được xác định trong cùng một tệp với 94 – 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 các định nghĩa từ các tệp 3 khác bằng cách nhập chúng. Để nhập các đị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 1Theo 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 trang 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 mục nhập sang vị trí mới bằng cách sử dụng khái niệm 428Lư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 428 có thể được dựa vào quá độ bởi bất kỳ mã nào nhập proto có chứa câu lệnh 428. Ví dụ 1____240 41Trì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ờ 431/ 432. 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ờ 432 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 lần 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 413 được xác định bên trong thông báo 94 42Nế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à 436 43Bạn có thể lồng các tin nhắn sâu như bạn muốn 44Cậ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 467 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 467 chứa một thông báo được đánh số thứ tự tùy ý là 446, 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 467, bạn cần phải 471 45URL loại mặc định cho một loại thông báo nhất định là 472Các triển khai ngôn ngữ khác nhau sẽ hỗ trợ các trình trợ giúp thư viện thời gian chạy để đóng gói và giải nén các giá trị 467 theo cách an toàn về kiểu – ví dụ: trong Java, loại 467 sẽ có các bộ truy cập đặc biệt 475 và 476, trong khi ở C++ có các phương thức 477 và 478 46Hiện tại các thư viện thời gian chạy để làm việc với các loại 467 đang được phát triểnNếu bạn đã quen thuộc với cú pháp proto2, thì 467 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 phương pháp 481 hoặc 482 đặ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 462 theo sau là tên của một trong số bạn, trong trường hợp này là 485 47Sau đó, 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ề 496/ 497, đ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 81trong đó 498 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à 446). Lưu ý rằng enum không phải là một 498 hợp lệ. 801 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 802 được liên kết với một khóa chuỗi, bạn có thể xác định nó như sau 82
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 83Mọ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 trình xác định 805 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 84Sau đó, 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 85Cá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ụ: 820) 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 94, bạn có thể xác định nó trong tệp 3 của mình như sau 86Hệ 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à 827, 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 829Generates JSON objects. Message field names are mapped to lowerCamelCase and become JSON object keys. If the 830 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 830 option) and the original proto field name. 827 is an accepted value for all field types and treated as the default value of the corresponding field type.enumstring 833The name of the enum value as specified in proto is used. Parsers accept both enum names and integer values.map 834All keys are converted to strings.repeated Varray 835 827 is accepted as the empty list 837.booltrue, false 838stringstring 839bytesbase64 string 840JSON 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 841JSON value will be a decimal number. Either numbers or strings are accepted.int64, fixed64, uint64string 842JSON value will be a decimal string. Either numbers or strings are accepted.float, doublenumber 843JSON 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 844 845If the 467 contains a value that has a special JSON mapping, it will be converted as follows: 847. Otherwise, the value will be converted into a JSON object, and the 848 field will be inserted to indicate the actual data type.Timestampstring 849Uses 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 850Generated 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 844 852Any JSON object. See 853.Wrapper typesvarious types 854Wrappers use the same representation in JSON as the wrapped primitive type, except that 827 is allowed and preserved during data conversion and transfer.FieldMaskstring 856See 857.ListValuearray 858ValuevalueAny JSON value. Check for details.NullValuenullJSON nullEmptyobject 859An 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 861Mộ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 02 trên tệp 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 bất khả tri về ngôn ngữ có liên quan, 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 |