From ebef344d55b295a1b25055ed592a72b7da07f078 Mon Sep 17 00:00:00 2001 From: seeflood <349895584@qq.com> Date: Tue, 11 Jan 2022 14:32:12 +0800 Subject: [PATCH 1/2] improve contributor guide --- README-zh.md | 75 +++++++++++++++++++++++++++++++++------------------- README.md | 3 +++ 2 files changed, 51 insertions(+), 27 deletions(-) diff --git a/README-zh.md b/README-zh.md index 7665946..9c7e07a 100644 --- a/README-zh.md +++ b/README-zh.md @@ -1,36 +1,39 @@ ## 如何使用java sdk + ### 1. import sdk + 对于 Maven 项目，将以下配置添加进 `pom.xml` 文件: + ```xml + - ... - ... - - io.mosn.layotto - runtime-sdk-parent - 1.0.0 - + + ... + + io.mosn.layotto + runtime-sdk-parent + 1.0.0 + + ... + ... - - ... ``` ### 2. 运行 examples 示例 + 可以本地部署redis和Layotto，然后运行java应用示例，通过java sdk调Layotto，Layotto转发给redis #### 第一步：部署redis -1. 取最新版的 Redis 镜像。 - 这里我们拉取官方的最新版本的镜像： +1. 取最新版的 Redis 镜像。 这里我们拉取官方的最新版本的镜像： ```shell docker pull redis:latest ``` -2. 查看本地镜像 - 使用以下命令来查看是否已安装了 redis： +2. 查看本地镜像 使用以下命令来查看是否已安装了 redis： ```shell docker images @@ -74,37 +77,46 @@ mvn clean install ``` #### 第三步：运行java sdk示例 + 通过以下Examples示例来了解如何使用SDK: + * [Hello world](./examples/src/test/java/io/mosn/layotto/examples/helloworld) * [State management](./examples/src/test/java/io/mosn/layotto/examples/state) * [Pubsub API](./examples/src/test/java/io/mosn/layotto/examples/pubsub) * [File API](./examples/src/test/java/io/mosn/layotto/examples/file) -## java sdk开发指南 -### java sdk职责 -1. sdk负责对Layotto的grpc API进行封装、不应该有任何中间件的定制逻辑，比如不应该出现redis、rocketmq等产品相关的逻辑。 +## sdk开发指南 + +### layotto sdk的职责 + +![](https://user-images.githubusercontent.com/26001097/148891505-57b734fa-ac8c-4349-9703-16d3f3d7aa9a.png) + +1. sdk负责对Layotto的grpc API进行封装。sdk内不应该有任何中间件的定制逻辑，比如不应该出现redis、rocketmq等产品相关的逻辑。 + +2. sdk需要把所有跟通信协议相关的东西（比如proto编译出来的stub类）屏蔽掉，请勿让public方法暴露出任何跟协议相关的东西，最好protected方法也不暴露proto相关的东西。 这么做是因为将来可能改grpc + API的package路径，甚至哪天不用grpc了（比如换成http协议）。总之请让用户不用关心协议。 -2. sdk需要把所有跟通信协议相关的东西（比如proto编译出来的stub类）屏蔽掉，请勿让public方法暴露出任何跟协议相关的东西，最好protected方法也不暴露proto相关的东西。 - 这么做是因为将来可能改grpc API的package路径，甚至哪天不用grpc了（谁知道呢）。总之请让用户不用关心协议。 +举个例子, state API对应有个`deleteState`方法，需要传`DeleteStateRequest`对象。 -举个例子, state API对应有个`deleteState`方法，需要传`DeleteStateRequest`对象。 ```java - /** - * Delete a state. - * - * @param request Request to delete a state. - */ +/** + * Delete a state. + * + * @param request Request to delete a state. + */ void deleteState(DeleteStateRequest request); ``` + 这个`DeleteStateRequest`是sdk定义的，其实sdk会把它转成 `RuntimeProto.DeleteStateRequest` (proto编译出来的类) 。 -你可能会问：为什么不能直接传`RuntimeProto.DeleteStateRequest` 呢？ +你可能会问：为什么不能让用户直接传`RuntimeProto.DeleteStateRequest` 呢？ -这就是上面说的原因，sdk需要封装掉协议相关的东西 +这就是上面说的原因，sdk需要封装掉协议相关的东西，如果让用户直接传pb类，以后换协议就不好换了 ### 想为某个grpc API提供java sdk，需要做哪些事情？ + 举个例子，grpc API里添加了file API，现在想为java sdk开发file API相关功能，需要做哪些事情？ 1. 先找个java sdk的demo跑起来，然后看懂java sdk是怎么创建对象、怎么调用的。其实java sdk就是把grpc包了一层，封装掉grpc的一些stub类，逻辑不多。 @@ -112,36 +124,45 @@ mvn clean install 2. 参考pr [feat(java-sdk): java sdk support File API](https://github.com/mosn/layotto/pull/325) . 这个pr 给java sdk添加了file API相关功能 ### 如何格式化 java sdk 代码 + 提交pull request之前先用maven编译一下 ```shell mvn clean compile ``` + 会自动格式化您的代码 ### 如何将proto文件编译成java代码 #### 1. 下载编译工具 [protoc](https://github.com/protocolbuffers/protobuf/releases) + my protoc version: + ```shell $ protoc --version libprotoc 3.11.2 ``` #### 2. 修改对应`proto`文件生成类名包名等信息 + (需先修改文件内部service名) -`spec/proto/runtime/v1/appcallback.proto` : +`spec/proto/runtime/v1/appcallback.proto` : + ```protobuf option java_outer_classname = "AppCallbackProto"; option java_package = "spec.proto.runtime.v1"; ``` + `spec/proto/runtime/v1/runtime.proto` : + ```protobuf option java_outer_classname = "RuntimeProto"; option java_package = "spec.proto.runtime.v1"; ``` #### 3. 编译其对应`JAVA`文件 + ```shell cd ${your PROJECT path}/spec/proto/runtime/v1 protoc -I=. --java_out=../../../../sdk/java-sdk/sdk/src/main/java/ runtime.proto diff --git a/README.md b/README.md index ac984bd..9e42cc3 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,9 @@ Try the following examples to learn more about this SDK: * [File API](./examples/src/test/java/io/mosn/layotto/examples/file) ## java sdk developer guide + +![](https://user-images.githubusercontent.com/26001097/148891505-57b734fa-ac8c-4349-9703-16d3f3d7aa9a.png) + ### How to format java sdk code Compile before submit your pull request: From cacb0043a67a1ce840a6b1cd979c9beec2806eb5 Mon Sep 17 00:00:00 2001 From: seeflood <349895584@qq.com> Date: Tue, 11 Jan 2022 14:37:04 +0800 Subject: [PATCH 2/2] improve contributor guide --- README-zh.md | 21 ++++++++------------- README.md | 11 ----------- 2 files changed, 8 insertions(+), 24 deletions(-) diff --git a/README-zh.md b/README-zh.md index 9c7e07a..7936d29 100644 --- a/README-zh.md +++ b/README-zh.md @@ -5,20 +5,11 @@ 对于 Maven 项目，将以下配置添加进 `pom.xml` 文件: ```xml - - - ... - - ... io.mosn.layotto runtime-sdk-parent 1.0.0 - ... - - ... - ``` ### 2. 运行 examples 示例 @@ -27,13 +18,17 @@ #### 第一步：部署redis -1. 取最新版的 Redis 镜像。 这里我们拉取官方的最新版本的镜像： +1. 取最新版的 Redis 镜像。 + +这里我们拉取官方的最新版本的镜像： ```shell docker pull redis:latest ``` -2. 查看本地镜像 使用以下命令来查看是否已安装了 redis： +2. 查看本地镜像 + +使用以下命令来查看是否已安装了 redis： ```shell docker images @@ -93,8 +88,8 @@ mvn clean install 1. sdk负责对Layotto的grpc API进行封装。sdk内不应该有任何中间件的定制逻辑，比如不应该出现redis、rocketmq等产品相关的逻辑。 -2. sdk需要把所有跟通信协议相关的东西（比如proto编译出来的stub类）屏蔽掉，请勿让public方法暴露出任何跟协议相关的东西，最好protected方法也不暴露proto相关的东西。 这么做是因为将来可能改grpc - API的package路径，甚至哪天不用grpc了（比如换成http协议）。总之请让用户不用关心协议。 +2. sdk需要把所有跟通信协议相关的东西（比如proto编译出来的stub类）屏蔽掉，请勿让public方法暴露出任何跟协议相关的东西，最好protected方法也不暴露proto相关的东西。 +这么做是因为将来可能改grpc API的package路径，甚至哪天不用grpc了（比如换成http协议）。总之请让用户不用关心协议。 举个例子, state API对应有个`deleteState`方法，需要传`DeleteStateRequest`对象。 diff --git a/README.md b/README.md index 9e42cc3..51d2fe4 100644 --- a/README.md +++ b/README.md @@ -3,19 +3,11 @@ ### 1. import sdk For a Maven project, add the following to your `pom.xml` file: ```xml - - ... - - ... io.mosn.layotto runtime-sdk-parent 1.0.0 - ... - - ... - ``` ### 2. Run the examples @@ -42,9 +34,6 @@ cd ${projectpath}/sdk/java-sdk mvn clean install ``` - - - Try the following examples to learn more about this SDK: * [Hello world](./examples/src/test/java/io/mosn/layotto/examples/helloworld) * [State management](./examples/src/test/java/io/mosn/layotto/examples/state)