Spring/spring-grpc
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Tidy up README

Browse Source
This commit is contained in:
Dave Syer
2024-12-20 14:39:33 +00:00
parent 780f8e61ea
commit 8b91ebd86a
2 changed files with 46 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
README.md
View File

@@ -11,13 +11,9 @@ For further information go to our [Spring gRPC reference documentation](https://
This section offers jumping off points for how to get started using Spring gRPC. There is a simple sample project in the `samples` directory (e.g. [`grpc-server`](https://github.com/spring-projects-experimental/spring-grpc/tree/main/samples/grpc-server)). You can run it with `mvn spring-boot:run` or `gradle bootRun`. You will see the following code in that sample.
Want to get started? Let’s speedrun a working service. Go to the [Spring Initializr](https://start.spring.io), select `gRPC`, `Web`, and `GraalVM`. I’ll be using Apache Maven in this tutorial but Gradle works, too.
Want to get started? Let’s speedrun a working service. Go to the [Spring Initializr](https://start.spring.io), select `gRPC`, `Web`, and `GraalVM`. Both Apache Maven and Gradle should work. Download the `.zip` file and unzip it. Open it in your IDE in the usual way. E.g. if you’re using IntelliJ IDEA: `idea pom.xml`; or for VSCode `code .`.
If you want to use GraalVM native images, make sure you have the GraalVM distribution of OpenJDK installed. You can do so with [sdkman.io](https://sdkman.io). e.g.: `sdk install java 23.0.1-graalce && sdk default java 23.0.1-graalce`.
Download the `.zip` file and unzip it. Open it in your IDE in the usual way. If you’re using IntelliJ IDEA: `idea pom.xml`.
Define a `.proto` service definition:
Define a `.proto` service definition file `src/main/proto/hello.proto` with the following contents:
```proto
syntax = "proto3";
@@ -51,7 +47,13 @@ We’ll want to define the stubs for a Java service based on this definition:
./mvnw clean package
```
You’ll get two new folders in the `target` directory: `target/target/generated-sources/protobuf/grpc-java` and `target/target/generated-sources/protobuf/java`. You may need to instruct your IDE to mark them as source roots. In IntelliJ IDEA, you’d right click the folder, choose `Mark Directory As` -> `Generated Source Root`.
or
```shell
./gradlew build
```
You’ll get two new folders in the `target` directory (or `build` for Gradle): `target/target/generated-sources/protobuf/grpc-java` and `target/target/generated-sources/protobuf/java`. You may need to instruct your IDE to mark them as source roots. In IntelliJ IDEA, you’d right click the folder, choose `Mark Directory As` -> `Generated Source Root`. Eclipse or VSCode will add them automatically for you.
Now you can implement a service based on the generated stubs:
@@ -102,13 +104,19 @@ Run the program in the usual way:
./mvnw spring-boot:run
```
or
```shell
./gradle bootRun
```
You can try it out using a gRPC client like `grpcurl`:
```shell
grpcurl -d '{"name":"Hi"}' -plaintext localhost:9090 Simple.SayHello
```
You should get a response like:
You should get a response like this:
```shell
{
@@ -116,7 +124,7 @@ You should get a response like:
}
```
Want some more details on what’s happening? Read on!
More details on what is going on in the next section.
## Details
@@ -254,3 +262,7 @@ spring.grpc.client.channels.local.address=0.0.0.0:9090
```
There is a default named channel (named "default") that you can configure in the same way, and then it will be used by default if there is no channel with the name specified in the channel creation.
### Native Images
Native images are supported for gRPC servers and clients. You can build in the [normal Spring Boot](https://docs.spring.io/spring-boot/how-to/native-image/developing-your-first-application.html) way for your build tool (Maven or Gradle).

35
spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc
View File

@@ -3,13 +3,9 @@
This section offers jumping off points for how to get started using Spring gRPC. There is a simple sample project in the `samples` directory (e.g. https://github.com/spring-projects-experimental/spring-grpc/tree/main/samples/grpc-server[`grpc-server`]). You can run it with `mvn spring-boot:run` or `gradle bootRun`. You will see the following code in that sample.
Want to get started? Let's speedrun a working service. Go to the [Spring Initializr](https://start.spring.io), select `gRPC`, `Web`, and `GraalVM`. I'll be using Apache Maven in this tutorial but Gradle works, too.
Want to get started? Let's speedrun a working service. Go to the [Spring Initializr](https://start.spring.io), select `gRPC`, `Web`, and `GraalVM`. Both Apache Maven and Gradle should work. Download the `.zip` file and unzip it. Open it in your IDE in the usual way. E.g. if you're using IntelliJ IDEA: `idea pom.xml`; or for VSCode `code .`.
If you want to use GraalVM native images, make sure you have the GraalVM distribution of OpenJDK installed. You can do so with [sdkman.io](https://sdkman.io). e.g.: `sdk install java 23.0.1-graalce && sdk default java 23.0.1-graalce`.
Download the `.zip` file and unzip it. Open it in your IDE in the usual way. If you're using IntelliJ IDEA: `idea pom.xml`.
Define a `.proto` service definition:
Define a `.proto` service definition file `src/main/proto/hello.proto` with the following contents:
[source,proto]
----
@@ -45,7 +41,14 @@ We'll want to define the stubs for a Java service based on this definition:
./mvnw clean package
----
You'll get two new folders in the `target` directory: `target/target/generated-sources/protobuf/grpc-java` and `target/target/generated-sources/protobuf/java`. You may need to instruct your IDE to mark them as source roots. In IntelliJ IDEA, you'd right click the folder, choose `Mark Directory As` -> `Generated Source Root`.
or
[source,shell]
----
./gradlew build
----
You'll get two new folders in the `target` directory (or `build` for Gradle): `target/target/generated-sources/protobuf/grpc-java` and `target/target/generated-sources/protobuf/java`. You may need to instruct your IDE to mark them as source roots. In IntelliJ IDEA, you'd right click the folder, choose `Mark Directory As` -> `Generated Source Root`. Eclipse or VSCode will add them automatically for you.
Now you can implement a service based on the generated stubs:
@@ -98,6 +101,13 @@ Run the program in the usual way:
./mvnw spring-boot:run
----
or
[source,shell]
----
./gradle bootRun
----
You can try it out using a gRPC client like `grpcurl`:
[source,shell]
@@ -105,7 +115,7 @@ You can try it out using a gRPC client like `grpcurl`:
grpcurl -d '{"name":"Hi"}' -plaintext localhost:9090 Simple.SayHello
----
You should get a response like:
You should get a response like this:
[source,shell]
----
@@ -114,7 +124,8 @@ You should get a response like:
}
----
Want some more details on what's happening? Read on!
More details on what is going on in the next section.
== Details
@@ -262,4 +273,8 @@ then in `application.properties`:
spring.grpc.client.channels.local.address=0.0.0.0:9090
----
There is a default named channel (named "default") that you can configure in the same way, and then it will be used by default if there is no channel with the name specified in the channel creation.
There is a default named channel (named "default") that you can configure in the same way, and then it will be used by default if there is no channel with the name specified in the channel creation.
=== Native Images
Native images are supported for gRPC servers and clients. You can build in the https://docs.spring.io/spring-boot/how-to/native-image/developing-your-first-application.html[normal Spring Boot] way for your build tool (Maven or Gradle).