You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+69-54Lines changed: 69 additions & 54 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,62 +1,98 @@
1
-
# Spring gRPC [](https://github.com/spring-projects/spring-grpc/actions/workflows/deploy.yml)
The Spring gRPC project provides a Spring-friendly API and abstractions for developing gRPC applications. There is a core library that makes it easy to work with gRPC and dependency injection, and a Spring Boot starter that makes it easy to get started with gRPC in a Spring Boot application (with autoconfiguration and configuration properties, for instance).
6
7
7
8
For further information go to our [Spring gRPC reference documentation](https://docs.spring.io/spring-grpc/reference/).
8
9
9
-
## Quick Start
10
+
#Getting Started
10
11
11
-
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.
12
+
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.
12
13
13
-
To create a simple gRPC server, you can use the Spring Boot starter. For Maven:
14
+
You should follow the steps in each of the following section according to your needs.
15
+
16
+
**📌 NOTE**\
17
+
Spring gRPC supports Spring Boot 3.3.x
18
+
19
+
## Add Milestone and Snapshot Repositories
20
+
21
+
If you prefer to add the dependency snippets by hand, follow the directions in the following sections.
22
+
23
+
To use the Milestone and Snapshot version, you need to add references to the Spring Milestone and/or Snapshot repositories in your build file.
24
+
25
+
For Maven, add the following repository definitions as needed (if you are using snapshots or milestones):
For convenience, you can use the Spring gRPC BOM to manage dependencies. With Maven:
58
+
## Dependency Management
59
+
60
+
The Spring gRPC Dependencies declares the recommended versions of all the dependencies used by a given release of Spring gRPC.
61
+
Using the dependencies from your application’s build script avoids the need for you to specify and maintain the dependency versions yourself.
62
+
Instead, the version you’re using determines the utilized dependency versions.
63
+
It also ensures that you’re using supported and tested versions of the dependencies by default, unless you choose to override them.
64
+
65
+
If you’re a Maven user, you can use the dependencies by adding the following to your pom.xml file -
30
66
31
67
```xml
32
68
<dependencyManagement>
33
-
<dependencies>
34
-
<dependency>
35
-
<groupId>org.springframework.grpc</groupId>
36
-
<artifactId>spring-grpc-dependencies</artifactId>
37
-
<version>0.1.0-SNAPSHOT</version>
38
-
<type>pom</type>
39
-
<scope>import</scope>
40
-
</dependency>
41
-
</dependencies>
69
+
<dependencies>
70
+
<dependency>
71
+
<groupId>org.springframework.ai</groupId>
72
+
<artifactId>spring-grpc-dependencies</artifactId>
73
+
<version>1.0.0-SNAPSHOT</version>
74
+
<type>pom</type>
75
+
<scope>import</scope>
76
+
</dependency>
77
+
</dependencies>
42
78
</dependencyManagement>
43
79
```
44
80
45
-
or Gradle:
81
+
Gradle users can also use the Spring gRPC Dependencies by leveraging Gradle (5.0+) native support for declaring dependency constraints using a Maven BOM.
82
+
This is implemented by adding a 'platform' dependency handler method to the dependencies section of your Gradle build script.
83
+
As shown in the snippet below this can then be followed by version-less declarations of the Starter Dependencies for the one or more spring-grpc modules you wish to use, e.g. spring-grpc-openai.
Then you can omit the version from the dependencies.
56
-
57
93
You need a Protobuf file that defines your service and messages, and you will need to configure your build tools to compile it into Java sources. This is a standard part of gRPC development (i.e. nothing to do with Spring). We now come to the Spring gRPC features.
58
94
59
-
###gPRC Server
95
+
## gPRC Server
60
96
61
97
Create a `@Bean` of type `BindableService`. For example:
62
98
@@ -69,7 +105,7 @@ public class GrpcServerService extends SimpleGrpc.SimpleImplBase {
69
105
70
106
(`BindableService` is the interface that gRPC uses to bind services to the server and `SimpleImplBase` was created for you from your Protobuf file.)
71
107
72
-
Then, you can just run your application and the gRPC server will be started on the default port (9090). Here's a simple example (standard Spring Boot application):
108
+
Then, you can just run your application and the gRPC server will be started on the default port (9090). Here’s a simple example (standard Spring Boot application):
73
109
74
110
```java
75
111
@SpringBootApplication
@@ -82,9 +118,9 @@ public class GrpcServerApplication {
82
118
83
119
Run it from your IDE, or on the command line with `mvn spring-boot:run` or `gradle bootRun`.
84
120
85
-
###gRPC Client
121
+
## gRPC Client
86
122
87
-
To create a simple gRPC client, you can use the Spring Boot starter (see above - it's the same as for the server). Then you can inject a bean of type `GrpcChannelFactory` and use it to create a gRPC channel. The most common usage of a channel is to create a client that binds to a service, such as the one above. The Protobuf-generated sources in your project will contain the stub classes, and they just need to be bound to a channel. For example, to bind to the `SimpleGrpc` service on a local server:
123
+
To create a simple gRPC client, you can use the Spring Boot starter (see above - it’s the same as for the server). Then you can inject a bean of type `GrpcChannelFactory` and use it to create a gRPC channel. The most common usage of a channel is to create a client that binds to a service, such as the one above. The Protobuf-generated sources in your project will contain the stub classes, and they just need to be bound to a channel. For example, to bind to the `SimpleGrpc` service on a local server:
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.
114
-
115
-
## Building
116
-
117
-
To build with unit tests
118
-
119
-
```shell
120
-
./mvnw clean package
121
-
```
122
-
123
-
```
124
-
To build the docs
125
-
```shell
126
-
./mvnw -pl spring-grpc-docs antora
127
-
```
128
-
129
-
The docs are then in the directory `spring-grpc-docs/target/antora/site/index.html`
130
-
131
-
To reformat using the [java-format plugin](https://github.com/spring-io/spring-javaformat)
where [`asciidoctor-reducer`](https://github.com/asciidoctor/asciidoctor-reducer) is a gem (so probably in `~/.gem/ruby/<version>/bin/asciidoctor-reducer`) and [`downdoc`](https://github.com/opendevise/downdoc) is an `npm` module, so `./node_modules/.bin/downdoc`.
13
+
3
14
## Configuration Properties
4
15
The Spring gRPC configuration properties are automatically documented as follows:
The Spring gRPC project provides a Spring-friendly API and abstractions for developing gRPC applications. There is a core library that makes it easy to work with gRPC and dependency injection, and a Spring Boot starter that makes it easy to get started with gRPC in a Spring Boot application (with autoconfiguration and configuration properties, for instance).
14
+
15
+
For further information go to our [Spring gRPC reference documentation](https://docs.spring.io/spring-grpc/reference/).
Copy file name to clipboardExpand all lines: spring-grpc-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc
+71-7Lines changed: 71 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,8 @@
1
1
[[getting-started]]
2
2
= Getting Started
3
3
4
-
This section offers jumping off points for how to get started using Spring gRPC.
4
+
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.
5
+
5
6
6
7
You should follow the steps in each of the following section according to your needs.
7
8
@@ -14,7 +15,7 @@ If you prefer to add the dependency snippets by hand, follow the directions in t
14
15
15
16
To use the Milestone and Snapshot version, you need to add references to the Spring Milestone and/or Snapshot repositories in your build file.
16
17
17
-
For Maven, add the following repository definitions as needed:
18
+
For Maven, add the following repository definitions as needed (if you are using snapshots or milestones):
18
19
19
20
[source,xml]
20
21
----
@@ -53,12 +54,12 @@ repositories {
53
54
[[dependency-management]]
54
55
== Dependency Management
55
56
56
-
The Spring gRPC Bill of Materials (BOM) declares the recommended versions of all the dependencies used by a given release of Spring gRPC.
57
-
Using the BOM from your application’s build script avoids the need for you to specify and maintain the dependency versions yourself.
58
-
Instead, the version of the BOM you’re using determines the utilized dependency versions.
57
+
The Spring gRPC Dependencies declares the recommended versions of all the dependencies used by a given release of Spring gRPC.
58
+
Using the dependencies from your application’s build script avoids the need for you to specify and maintain the dependency versions yourself.
59
+
Instead, the version you’re using determines the utilized dependency versions.
59
60
It also ensures that you’re using supported and tested versions of the dependencies by default, unless you choose to override them.
60
61
61
-
If you’re a Maven user, you can use the BOM by adding the following to your pom.xml file -
62
+
If you’re a Maven user, you can use the dependencies by adding the following to your pom.xml file -
62
63
63
64
[source,xml]
64
65
----
@@ -75,7 +76,7 @@ If you’re a Maven user, you can use the BOM by adding the following to your po
75
76
</dependencyManagement>
76
77
----
77
78
78
-
Gradle users can also use the Spring gRPC BOM by leveraging Gradle (5.0+) native support for declaring dependency constraints using a Maven BOM.
79
+
Gradle users can also use the Spring gRPC Dependencies by leveraging Gradle (5.0+) native support for declaring dependency constraints using a Maven BOM.
79
80
This is implemented by adding a 'platform' dependency handler method to the dependencies section of your Gradle build script.
80
81
As shown in the snippet below this can then be followed by version-less declarations of the Starter Dependencies for the one or more spring-grpc modules you wish to use, e.g. spring-grpc-openai.
You need a Protobuf file that defines your service and messages, and you will need to configure your build tools to compile it into Java sources. This is a standard part of gRPC development (i.e. nothing to do with Spring). We now come to the Spring gRPC features.
93
+
94
+
== gPRC Server
95
+
96
+
Create a `@Bean` of type `BindableService`. For example:
97
+
98
+
[source,java]
99
+
----
100
+
@Service
101
+
public class GrpcServerService extends SimpleGrpc.SimpleImplBase {
102
+
...
103
+
}
104
+
----
105
+
106
+
(`BindableService` is the interface that gRPC uses to bind services to the server and `SimpleImplBase` was created for you from your Protobuf file.)
107
+
108
+
Then, you can just run your application and the gRPC server will be started on the default port (9090). Here's a simple example (standard Spring Boot application):
Run it from your IDE, or on the command line with `mvn spring-boot:run` or `gradle bootRun`.
121
+
122
+
== gRPC Client
123
+
124
+
To create a simple gRPC client, you can use the Spring Boot starter (see above - it's the same as for the server). Then you can inject a bean of type `GrpcChannelFactory` and use it to create a gRPC channel. The most common usage of a channel is to create a client that binds to a service, such as the one above. The Protobuf-generated sources in your project will contain the stub classes, and they just need to be bound to a channel. For example, to bind to the `SimpleGrpc` service on a local server:
Then you can inject the stub and use it in your application.
135
+
136
+
The default `GrpcChannelFactory` implementation can also create a "named" channel, which you can then use to extract the configuration to connect to the server. For example:
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.
0 commit comments