Giải thích chi tiết về quy tắc mẫu tùy chỉnh protoc-gen-doc

Hỗ trợ dự án trình diễn.

Tệp proto được sử dụng trong dự án này nằm trong thư mục ./proto và lấy từ ví dụ proto chính thức.

Tất cả các tệp trường hợp mẫu được liệt kê trong dự án này đều nằm trong thư mục ./tmpl.

Hướng dẫn này dựa trên việc trình diễn văn bản đánh dấu.

Lời nói đầu

Gần đây, có nhu cầu tạo tài liệu giao diện của nó thông qua các tệp proto, nhưng định dạng do protoc-gen-doc tạo ra không thể đáp ứng tốt nhu cầu. Tôi thấy rằng nó hỗ trợ các mẫu tùy chỉnh, nhưng hầu như không có bài viết nào có thể giải thích chi tiết cách tùy chỉnh nó, những trường nào sẽ sử dụng để tùy chỉnh, cách viết các giao dịch truyền tải và câu lệnh điều kiện khác nhau, cách truy cập Tùy chọn ServiceMethod, v.v.

Sau gần một ngày phân loại và đào sâu các cạm bẫy, bài viết này đã được ra đời, ghi lại cú pháp chung cần có cho các mẫu tùy chỉnh.

Giới thiệu về protoc-gen-doc

protoc-gen-doc là một plug-in protoc để tạo proto. Nó nhanh chóng tạo ra nhiều loại tài liệu giao diện khác nhau bằng cách phân tích các định nghĩa tệp proto.

Nguyên tắc tạo tài liệu dựa trên mẫu tệp, bằng cách phân tích các thuộc tính của tệp proto và điền vào vị trí được chỉ định trong mẫu. Nó có thể được tạo dựa trên các mẫu có sẵn hoặc có thể sử dụng các mẫu tùy chỉnh.

Hỗ trợ mẫu tích hợp:

• json
• html
• giảm giá
• sách tài liệu

Cách sử dụng:

1. Tải xuống lần đầu qua go get protoc-gen-doc File nhị phân, đường dẫn tới file này sẽ được thông qua khi sử dụng. . Để thuận tiện cho việc trình diễn, tôi đặt một protoc-gen-doc tài liệu.

                        
                          hãy lấy -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc

                        
                      

1. Sử dụng lệnh protoc

                        
                          giao thức \ --plugin=protoc-gen-doc=./protoc-gen-doc \ --proto_path=./proto \ --proto_path=./third_party \ --doc_out=./out \ --doc_opt=markdown,index.md \ ./proto/*.proto

                        
                      

Phân tích tham số:

• --phần bổ trợ : Chỉ định protoc-gen-doc và chỉ định đường dẫn đến file thực thi protoc-gen-doc
• --đường dẫn nguyên mẫu : Đường dẫn thư mục chứa tệp proto đích. Nếu nó phụ thuộc vào các tệp proto trong các thư mục khác, thì cũng sử dụng tham số này để chỉ định thư mục của nó. Ví dụ bên thứ ba Mục lục.
• --doc_ra : Thư mục đầu ra của tài liệu giao diện
• --doc_opt : Chỉ định mẫu tài liệu và tên tệp sẽ xuất ra
• Dòng cuối cùng: Chỉ định tệp proto đích

Chỉ định mẫu tùy chỉnh

Nếu bạn muốn chỉ định một mô hình tùy chỉnh, bạn có thể sửa đổi tham số đầu tiên của --doc_opt.

Ví dụ: nếu tôi tùy chỉnh tệp mẫu case1.tmpl trong thư mục ./tmpl, thì --doc_opt phải được đặt thành:

                        
                          --doc_opt=./tmpl/case1.tmpl,index.md

                        
                      

Ví dụ về mẫu tùy chỉnh chính thức

Các quan chức ở đây có hai mẫu tùy chỉnh đơn giản, cho thấy cách sử dụng phổ biến, nhưng không có nhiều lời giải thích. Việc viết các mẫu tùy chỉnh của riêng bạn vẫn khá khó khăn. Có sẵn để tham khảo.

Ví dụ về mẫu tùy chỉnh chính thức.

Cấu trúc dữ liệu và định nghĩa hàm

Để hiểu mẫu, bạn phải hiểu ý nghĩa của từng tham số giữ chỗ.

Tất cả các tham số giữ chỗ trong mẫu có thể được tìm thấy trong mã nguồn: templates.go.

Không cần phải hiểu mã nguồn làm gì hoặc nó chạy như thế nào. Bạn chỉ cần nhìn vào cấu trúc:

                        
                          type Template struct { // Các tệp đã được phân tích Files []*File `json:"files"` // Chi tiết về các giá trị vô hướng và các kiểu tương ứng của chúng trong các ngôn ngữ được hỗ trợ. Scalars []*ScalarValue `json:"scalarValueTypes"` }

                        
                      

Đây là cấu trúc Tệp được phân tích từ proto dưới dạng tệp. Nhập từ Tệp, bạn có thể xem thêm chi tiết và bạn cũng có thể đi sâu hơn vào Dịch vụ và Tin nhắn.

                        
                          loại Tệp struct { Tên chuỗi `json:"name"` Mô tả chuỗi `json:"description"` Gói chuỗi `json:"package"` HasEnums bool `json:"hasEnums"` HasExtensions bool `json:"hasExtensions"` HasMessages bool `json:"hasMessages"` HasServices bool `json:"hasServices"` Enums orderedEnums `json:"enums"` Phần mở rộng orderedExtensions `json:"extensions"` Tin nhắn orderedMessages `json:"messages"` Dịch vụ orderedServices `json:"services"` Tùy chọn map[string]interface{} `json:"options,omitempty"` }

                        
                      

So sánh nó với ví dụ chính thức, bạn có thể thấy rằng các trường giữ chỗ là tất cả các trường được xác định ở đây. Tên trường ở đây là như vậy và không cần phải giải thích chi tiết.

Trường Mô tả tương ứng với các nhận xét trong tệp proto. Khi chú thích được viết phía trên dịch vụ, nó có thể được đọc từ trường Mô tả của cấu trúc Dịch vụ.

Ngoài ra, mỗi cấu trúc còn định nghĩa nhiều phương thức, cũng có thể được gọi trong các mẫu tùy chỉnh. Xem bên dưới để biết chi tiết.

ngữ pháp cơ bản

chú thích

Nó chủ yếu được xác định bởi loại tài liệu được tạo ra.

Ví dụ: trong markdown và html, không thể hiển thị, vì vậy bạn có thể sử dụng để viết nhận xét.

Giá trị trường đầu ra

Nếu bạn muốn lấy giá trị của một trường nhất định, bạn có thể sử dụng ký hiệu {{}}. Trong tệp mô hình tùy chỉnh, .

{{.}} ban đầu đại diện cho cấu trúc Mẫu.

{{.Files}} đại diện cho trường Tệp của Mẫu đầu ra.

Nếu bạn muốn lấy một Tệp để thao tác, bạn phải sử dụng câu lệnh truyền tải để duyệt qua nó.

Câu lệnh truyền tải

Lặp lại danh sách Tệp từ Mẫu như sau:

                        
                           {{range .Files}} # {{.Name}} {{.Description}} {{.}} {{end}}

                        
                      

Trong ví dụ trên, {{Range .Files}} được sử dụng để duyệt qua danh sách Tệp và kết thúc tại {{end}}. Giữa phạm vi và kết thúc, {{.}} đại diện cho cấu trúc của Tệp và {{.Name}} là File.Name.

Sửa đổi các tham số --doc_opt=./tmpl/case1.tmpl,case1.md và xem kết quả đang chạy:

Các câu lệnh truyền tải được sử dụng rất phổ biến và có thể được lồng vào nhau. Không chỉ Tệp mà cả Dịch vụ, Thông báo, Phương thức dịch vụ và các cấu trúc khác cũng cần được duyệt qua bằng cách sử dụng Phạm vi để có được cấu trúc bên trong của chúng.

Ví dụ nhập File và File.Services để in thông tin Service:

                        
                           {{range .Files}} # {{.Name}} {{.Description}} {{.}} {{range .Services}} ## ServiceName: {{.Name}} {{.Description}} {{.}} {{end}}  {{end}} 


                        
                      

Ở đây chúng ta duyệt và in các cấu trúc Service.Name, Service.Description và Service.

Sửa đổi các tham số --doc_opt=./tmpl/case2.tmpl,case2.md và xem kết quả đang chạy:

Gán tham số

Bạn có thể thấy rằng mỗi lần ở trong phạm vi, {{.}} sẽ trở thành một Mục trong danh sách mục tiêu của phạm vi. Khi có nhiều phạm vi lồng nhau, rất dễ bị nhầm lẫn. Mục có thể được gán cho một tham số và sau đó được gọi bằng tham số đó.

Sửa đổi dựa trên trường hợp 2:

                        
                           {{range .Files}} {{$file := .}} # {{$file.Name}} {{$file.Description}} {{$file}} {{range $file.Services}} {{$service := .}} ## ServiceName: {{$service.Name}} {{$service.Description}} {{$service}} {{end}}  {{end}} 

                        
                      

Nhìn vào kết quả chạy có thể thấy kết quả của case3 sử dụng tham số hoàn toàn giống với case2:

câu lệnh có điều kiện

Sử dụng {{if}} {{end}} hoặc thêm {{else}} vào đó.

{{if}} Hiện tại có hai cách sử dụng:

                        
                          {{nếu eq param1 param2}} {{kết thúc}} {{nếu boolParam}} {{kết thúc}}

                        
                      

Cái trước so sánh xem hai tham số có bằng nhau hay không. Cái sau xác định liệu boolParam có đúng hay không.

Ví dụ sau dựa trên trường hợp 3 và sẽ xác định xem file.Name có bằng Booking.proto hay không. Nếu vậy, thông tin liên quan sẽ được xuất ra. Nếu không, đầu ra sẽ bỏ qua xxx.

Tiếp tục xác định xem dịch vụ HasServices có tồn tại trong Booking.proto hay không và nếu có thì xuất thông tin liên quan.

                        
                           {{range .Files}} {{$file := .}} {{if eq $file.Name "Booking.proto"}} # {{$file.Name}} {{$file.Description}} {{$file}} {{if $file.HasServices}} {{range $file.Services}} {{$service := .}} ## ServiceName: {{$service.Name}} {{$service.Description}} {{$service}} {{end}}  {{end}}  {{else}} # Thêm {{$file.Name}} {{end}}  {{end}} 

                        
                      

chức năng gọi

Nếu muốn biết chức năng của một hàm nào đó, bạn cũng nên tự đọc mã nguồn về cách triển khai từng hàm cấu trúc: templates.go.

Cách sử dụng:

                        
                          {{functionName tham số... }}

                        
                      

Hầu hết các chức năng được sử dụng để đọc nội dung của Tùy chọn. Hầu hết mọi cấu trúc đều có Tùy chọn, đó là cấu trúc map[string]interface{}.

Các tùy chọn được sử dụng phổ biến hơn như sau: Định nghĩa http của Dịch vụ:

Để truy xuất Tùy chọn tại đây, bạn có thể sử dụng phương thức Tùy chọn của ServiceMethod.

Sửa đổi dựa trên trường hợp 3:

                        
                           {{range .Files}} {{$file := .}} # {{$file.Name}} {{$file.Description}} {{$file}} {{range $file.Services}} {{$service := .}} ## ServiceName: {{$service.Name}} {{$service.Description}} {{range $service.Methods}} {{$method := .}} ### ServiceMethod: {{$method.Name}} {{range ($method.Option "google.api.http").Rules}} - {{.Method}} - {{.Pattern}} - \{{.Body}}  {{end}}  {{end}}  {{end}}  {{end}} 

                        
                      

Kết quả sau khi chạy

($method.Option "google.api.http"). Các quy tắc thực hiện chuyển đổi loại trên loại giao diện{} được truy xuất. Tại sao Quy tắc được sử dụng để chuyển đổi có thể được tìm thấy trong mã nguồn:

khác

                        
                           {{ .XXX | mặc định ""}}  {{ .XXX | low}}  {{ .XXX | thay thế "a" ""}}  {{ .XXX | }} 

                        
                      

Ngoài ra, còn rất nhiều cách sử dụng khác chưa được tìm hiểu sâu nhưng nắm vững những điều trên là có thể đáp ứng được nhu cầu của các mẫu tùy chỉnh.

Nếu ai có gì bổ sung thêm thì tôi xin cảm ơn.

Tóm tắt tài liệu tham khảo

1. Hỗ trợ dự án trình diễn https://github.com/csuqiyuan/custom-protoc-doc-example
2. ví dụ chính thức về tệp proto https://github.com/pseudouto/protoc-gen-doc/tree/master/examples/proto
3. Ví dụ chính thức về các mẫu tùy chỉnh https://github.com/pseudouto/protoc-gen-doc/tree/master/examples/templates
4. mẫu.go https://github.com/pseudomuto/protoc-gen-doc/blob/master/template.go
5. google.api.http Chuyển đổi loại tùy chọn https://github.com/pseudouto/protoc-gen-doc/blob/master/extensions/google_api_http/google_api_http.go

Cuối cùng, bài viết này về giải thích chi tiết về quy tắc mẫu tùy chỉnh protoc-gen-doc kết thúc ở đây. Nếu bạn muốn biết thêm về giải thích chi tiết về quy tắc mẫu tùy chỉnh protoc-gen-doc, vui lòng tìm kiếm các bài viết CFSDN hoặc tiếp tục duyệt các bài viết liên quan. , Tôi hy vọng bạn sẽ ủng hộ blog của tôi trong tương lai! .