From 67f13411a35322b35b6ef724c6259d009a42b966 Mon Sep 17 00:00:00 2001 From: Freeman Liu Date: Fri, 29 Sep 2023 00:21:21 +0800 Subject: [PATCH] update docs --- README.md | 2 +- docs/en-us/extension/protobuf-validation.md | 69 +++++++++++++--- docs/zh-cn/extension/protobuf-validation.md | 91 +++++++++++++++------ 3 files changed, 123 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index cb40a2f2..05e982b2 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ This project provides out-of-the-box, highly scalable Spring Boot starters for t ***Extensions:*** - [JSON transcoder](https://danielliu1123.github.io/grpc-starter/#/en-us/extension/json-transcoder): A single codebase to simultaneously support both gRPC and HTTP/JSON. -- [Protobuf validation](https://danielliu1123.github.io/grpc-starter/#/en-us/extension/protobuf-validation): Protobuf message validation implemented by [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate). +- [Protobuf validation](https://danielliu1123.github.io/grpc-starter/#/en-us/extension/protobuf-validation): Protobuf message validation implemented by [protovalidate](https://github.com/bufbuild/protovalidate-java)/[protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate). - [Metric](https://danielliu1123.github.io/grpc-starter/#/en-us/extension/metrics): Spring Boot Actuator integration with gRPC service. - [Tracing](https://danielliu1123.github.io/grpc-starter/#/en-us/extension/tracing): Spring Boot Actuator integration with gRPC server and client. - [Testing](https://danielliu1123.github.io/grpc-starter/#/en-us/extension/test): Integration with `SpringBootTest`. diff --git a/docs/en-us/extension/protobuf-validation.md b/docs/en-us/extension/protobuf-validation.md index 90fd3de6..628f080a 100644 --- a/docs/en-us/extension/protobuf-validation.md +++ b/docs/en-us/extension/protobuf-validation.md @@ -1,6 +1,9 @@ ## Overview -The Validation extension module provides parameter validation functionality for gRPC servers and clients using [protobuf](https://developers.google.com/protocol-buffers) and implemented through [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate). +The Validation extension module provides parameter validation functionality for gRPC servers and clients +using [protobuf](https://developers.google.com/protocol-buffers) and implemented +through [protovalidate](https://github.com/bufbuild/protovalidate-java)(3.x only, former +protoc-gen-validate) / [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate). ## Service Structure @@ -12,10 +15,46 @@ user ├── user-server ``` -- `user-api`: Contains the proto files defining the interface and data structures of the user service, which can be used by external dependencies. +- `user-api`: Contains the proto files defining the interface and data structures of the user service, which can be used + by external dependencies. - `user-server`: Contains the server implementation of the API. -## Usage Steps +## protovalidate Usage + +1. Add the dependency + + ```groovy + implementation("com.freemanan:grpc-starter-protovalidate") + ``` + + > In most cases, you only need the API module to depend on the `grpc-starter-protovalidate` module. + +2. Write the proto file + + ```protobuf + syntax = "proto3"; + + package fm.user.v1; + + import "google/protobuf/timestamp.proto"; + import "buf/validate/validate.proto"; + + option java_package = "com.freemanan.user.v1.api"; + option java_multiple_files = true; + + message User { + string id = 1; + string name = 2 [(buf.validate.field).string = {min_len: 1, max_len: 100}]; + } + + service UserService { + rpc Create(User) returns (User) {} + } + ``` + + > protovalidate doesn't need code generation! + +## protoc-gen-validate Usage 1. Add the dependency @@ -23,7 +62,7 @@ user implementation("com.freemanan:grpc-starter-validation") ``` - > In most cases, you only need the API module to depend on the validation module. + > In most cases, you only need the API module to depend on the `grpc-starter-validation` module. 2. Write the proto file @@ -39,8 +78,8 @@ user option java_multiple_files = true; message User { - string id = 1 [(validate.rules).string = {min_len: 1, max_len: 100}]; - string name = 2; + string id = 1; + string name = 2 [(validate.rules).string = {min_len: 1, max_len: 100}]; } service UserService { @@ -48,7 +87,8 @@ user } ``` - For the usage of `proto-gen-validation`, you can refer to the [official documentation](https://github.com/bufbuild/protoc-gen-validate). + For the usage of `proto-gen-validation`, you can refer to + the [official documentation](https://github.com/bufbuild/protoc-gen-validate). 3. Generate the code @@ -78,13 +118,18 @@ user } ``` - For Maven configuration, you can refer to the documentation [here](https://github.com/bufbuild/protoc-gen-validate#java). + For Maven configuration, you can refer to the + documentation [here](https://github.com/bufbuild/protoc-gen-validate#java). -You can refer to the [user](https://github.com/DanielLiu1123/grpc-starter/tree/main/examples/user) example for more information. +You can refer to the [user](https://github.com/DanielLiu1123/grpc-starter/tree/main/examples/user) example for more +information. ## Usage Instructions -If the server/client depends on the API module with the `grpc-starter-validation` module, by default, both the server and client will automatically enable the validation feature. Before sending a request, the client will validate the request parameters, and upon receiving a request, the server will also validate the request parameters. +If the server/client depends on the API module with the `grpc-starter-validation` module, by default, both the server +and client will automatically enable the validation feature. +Before sending a request, the client will validate the request parameters, and upon receiving a request, the server will +also validate the request parameters. If you want to disable the validation feature, you can configure it in the `application.yml` file: @@ -94,7 +139,9 @@ grpc: enabled: false ``` -The implementation of Validation is essentially a gRPC interceptor, so you can control the execution order of validation by configuring the order of the interceptor. By default, the order of the validation interceptor is 0. You can modify the order by configuring `grpc.validation.client.order` and `grpc.validation.server.order`. +The implementation of Validation is essentially a gRPC interceptor, so you can control the execution order of validation +by configuring the order of the interceptor. By default, the order of the validation interceptor is 0. You can modify +the order by configuring `grpc.validation.client.order` and `grpc.validation.server.order`. ## Related Configuration diff --git a/docs/zh-cn/extension/protobuf-validation.md b/docs/zh-cn/extension/protobuf-validation.md index 484ea725..c21e8a33 100644 --- a/docs/zh-cn/extension/protobuf-validation.md +++ b/docs/zh-cn/extension/protobuf-validation.md @@ -1,11 +1,12 @@ -## Overview +## 概述 -Validation 扩展模块为 gRPC 服务端和客户端提供 [protobuf](https://developers.google.com/protocol-buffers) -参数校验功能，通过 [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate) 实现。 +Validation 扩展模块为基于 [protobuf](https://developers.google.com/protocol-buffers) 的 gRPC +服务器和客户端提供参数验证功能，通过 [protovalidate](https://github.com/bufbuild/protovalidate-java)（仅支持 3.x，前身为 +protoc-gen-validate）和 [protoc-gen-validate](https://github.com/bufbuild/protoc-gen-validate) 实现。 ## 服务结构 -假设你正在编写一个 user 服务，那么你的项目结构可能如下： +假设您正在开发一个 user 服务，您的项目结构可能如下： ```text user @@ -13,20 +14,55 @@ user ├── user-server ``` -- `user-api`：包含 proto 文件，定义 user 服务的接口和数据结构，可供外部依赖 -- `user-server`：包含 api 的服务端实现 +- `user-api`：包含定义用户服务接口和数据结构的 proto 文件，可以被外部依赖使用。 +- `user-server`：包含 API 的服务器实现。 -## 使用步骤 +## protovalidate 使用 -1. 引入依赖 +1. 添加依赖项 + + ```groovy + implementation("com.freemanan:grpc-starter-protovalidate") + ``` + + > 在大多数情况下，您只需要 API 模块依赖 `grpc-starter-protovalidate` 模块。 + +2. 编写 proto 文件 + + ```protobuf + syntax = "proto3"; + + package fm.user.v1; + + import "google/protobuf/timestamp.proto"; + import "buf/validate/validate.proto"; + + option java_package = "com.freemanan.user.v1.api"; + option java_multiple_files = true; + + message User { + string id = 1; + string name = 2 [(buf.validate.field).string = {min_len: 1, max_len: 100}]; + } + + service UserService { + rpc Create(User) returns (User) {} + } + ``` + + > protovalidate 不需要代码生成！ + +## protoc-gen-validate 使用 + +1. 添加依赖项 ```groovy implementation("com.freemanan:grpc-starter-validation") ``` - > 一般情况下只需要 api 模块依赖 validation 模块即可！ + > 在大多数情况下，您只需要 API 模块依赖 `grpc-starter-validation` 模块。 -2. 编写 proto +2. 编写 proto 文件 ```protobuf syntax = "proto3"; @@ -40,8 +76,8 @@ user option java_multiple_files = true; message User { - string id = 1 [(validate.rules).string = {min_len: 1, max_len: 100}]; - string name = 2; + string id = 1; + string name = 2 [(validate.rules).string = {min_len: 1, max_len: 100}]; } service UserService { @@ -49,11 +85,11 @@ user } ``` - 关于 `proto-gen-validation` 的使用，可以参考 [官方文档](https://github.com/bufbuild/protoc-gen-validate)。 + 有关 `proto-gen-validation` 的使用，您可以参考 [官方文档](https://github.com/bufbuild/protoc-gen-validate)。 3. 生成代码 - 配置 `com.google.protobuf` 插件，用于生成 gRPC 和 validation 相关的代码： + 配置 `com.google.protobuf` 插件以生成 gRPC 和与验证相关的代码： ```groovy apply plugin: 'com.google.protobuf' @@ -79,16 +115,16 @@ user } ``` - 有关 Maven 的配置，可以参考 [here](https://github.com/bufbuild/protoc-gen-validate#java)。 + 对于 Maven 配置，您可以在[此处](https://github.com/bufbuild/protoc-gen-validate#java)的文档中查找。 -可以参考 [user](https://github.com/DanielLiu1123/grpc-starter/tree/main/examples/user) example。 +您可以参考 [user](https://github.com/DanielLiu1123/grpc-starter/tree/main/examples/user) 示例获取更多信息。 ## 使用说明 -如果 server/client 依赖的 api 有 `grpc-starter-validation` 模块，那么在默认情况下，server 和 client 都会自动启用 -validation 功能。在 client 发送请求前，会对请求参数进行校验；在 server 收到请求后，也会对请求参数进行校验。 +如果服务器/客户端依赖带有 `grpc-starter-validation` 模块的 API +模块，默认情况下，服务器和客户端都会自动启用验证功能。发送请求之前，客户端会验证请求参数，在接收请求时，服务器也会验证请求参数。 -如果你想禁用 validation 功能，可以在 `application.yml` 中进行配置： +如果您想禁用验证功能，可以在 `application.yml` 文件中进行配置： ```yaml grpc: @@ -96,19 +132,20 @@ grpc: enabled: false ``` -Validation 的实现本质上就是一个 gRPC 的拦截器，所以可以通过配置拦截器的顺序来控制 validation 的执行顺序。默认情况下，validation -拦截器的顺序为 0，你可以通过配置 `grpc.validation.client.order` 和 `grpc.validation.server.order` 来修改拦截器的顺序。 +验证的实现本质上是一个 gRPC +拦截器，所以您可以通过配置拦截器的顺序来控制验证的执行顺序。默认情况下，验证拦截器的顺序为0。您可以通过配置 `grpc.validation.client.order` +和 `grpc.validation.server.order` 来修改顺序。 ## 相关配置 ```yaml grpc: validation: - enabled: true # enable validation + enabled: true # 启用验证 client: - enabled: true # enable validation for client - order: 0 # order of validating client interceptor + enabled: true # 为客户端启用验证 + order: 0 # 验证客户端拦截器的顺序 server: - enabled: true # enable validation for server - order: 0 # order of validating server interceptor -``` + enabled: true # 为服务器启用验证 + order: 0 # 验证服务器拦截器的顺序 +``` \ No newline at end of file