{"id":27629494,"url":"https://github.com/spring-projects/spring-grpc","last_synced_at":"2025-04-23T15:20:27.045Z","repository":{"id":255465140,"uuid":"851871884","full_name":"spring-projects/spring-grpc","owner":"spring-projects","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-23T09:52:03.000Z","size":1000,"stargazers_count":188,"open_issues_count":8,"forks_count":38,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-23T10:25:48.318Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spring-projects.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-03T20:47:24.000Z","updated_at":"2025-04-23T09:52:06.000Z","dependencies_parsed_at":"2024-09-05T15:11:51.685Z","dependency_job_id":"e659b368-f22e-496e-a8a7-475d513ad322","html_url":"https://github.com/spring-projects/spring-grpc","commit_stats":null,"previous_names":["spring-projects-experimental/spring-grpc","spring-projects/spring-grpc"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spring-projects%2Fspring-grpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spring-projects%2Fspring-grpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spring-projects%2Fspring-grpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spring-projects%2Fspring-grpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spring-projects","download_url":"https://codeload.github.com/spring-projects/spring-grpc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250457778,"owners_count":21433734,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-23T15:20:26.181Z","updated_at":"2025-04-23T15:20:27.032Z","avatar_url":"https://github.com/spring-projects.png","language":"Java","readme":"# Spring gRPC\n![\"Build Status\"](https://github.com/spring-projects/spring-grpc/actions/workflows/deploy.yml/badge.svg)\n\nWelcome to the Spring gRPC project!\n\nThe 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).\n\nFor further information go to our [Spring gRPC reference documentation](https://docs.spring.io/spring-grpc/reference/).\n\n# Getting Started\n\nThis 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/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.\n\nWant to get started? Let’s speedrun a working service.\n\nGo to the [Spring Initializr](https://start.spring.io) and select the `gRPC` dependency.\n\nGenerate the project and unzip the downloaded result.\n\nOpen it in your IDE in the usual way. E.g. if you’re using IntelliJ IDEA: `idea pom.xml`; or for VSCode `code .`.\n\nDefine a `.proto` service definition file `src/main/proto/hello.proto` with the following contents:\n\n```proto\nsyntax = \"proto3\";\n\noption java_multiple_files = true;\noption java_package = \"org.springframework.grpc.sample.proto\";\noption java_outer_classname = \"HelloWorldProto\";\n\n// The greeting service definition.\nservice Simple {\n  // Sends a greeting\n  rpc SayHello (HelloRequest) returns (HelloReply) {\n  }\n  rpc StreamHello(HelloRequest) returns (stream HelloReply) {}\n}\n\n// The request message containing the user's name.\nmessage HelloRequest {\n  string name = 1;\n}\n\n// The response message containing the greetings\nmessage HelloReply {\n  string message = 1;\n}\n```\n\nWe’ll want to define the stubs for a Java service based on this definition:\n\n```shell\n./mvnw clean package\n```\n\nor\n\n```shell\n./gradlew build\n```\n\nYou’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` -\u003e `Generated Source Root`. Eclipse or VSCode will add them automatically for you.\n\nNow you can implement a service based on the generated stubs:\n\n```java\n@Service\nclass GrpcServerService extends SimpleGrpc.SimpleImplBase {\n\n    private static Log log = LogFactory.getLog(GrpcServerService.class);\n\n    @Override\n    public void sayHello(HelloRequest req, StreamObserver\u003cHelloReply\u003e responseObserver) {\n        log.info(\"Hello \" + req.getName());\n        if (req.getName().startsWith(\"error\")) {\n            throw new IllegalArgumentException(\"Bad name: \" + req.getName());\n        }\n        if (req.getName().startsWith(\"internal\")) {\n            throw new RuntimeException();\n        }\n        HelloReply reply = HelloReply.newBuilder().setMessage(\"Hello ==\u003e \" + req.getName()).build();\n        responseObserver.onNext(reply);\n        responseObserver.onCompleted();\n    }\n\n    @Override\n    public void streamHello(HelloRequest req, StreamObserver\u003cHelloReply\u003e responseObserver) {\n        log.info(\"Hello \" + req.getName());\n        int count = 0;\n        while (count \u003c 10) {\n            HelloReply reply = HelloReply.newBuilder().setMessage(\"Hello(\" + count + \") ==\u003e \" + req.getName()).build();\n            responseObserver.onNext(reply);\n            count++;\n            try {\n                Thread.sleep(1000L);\n            } catch (InterruptedException e) {\n                Thread.currentThread().interrupt();\n                responseObserver.onError(e);\n                return;\n            }\n        }\n        responseObserver.onCompleted();\n    }\n}\n```\n\nRun the program in the usual way:\n\n```shell\n./mvnw spring-boot:run\n```\n\nor\n\n```shell\n./gradle bootRun\n```\n\nYou can try it out using a gRPC client like `grpcurl`:\n\n```shell\ngrpcurl -d '{\"name\":\"Hi\"}' -plaintext localhost:9090 Simple.SayHello\n```\n\nYou should get a response like this:\n\n```shell\n{\n  \"message\": \"Hello ==\\u003e Hi\"\n}\n```\n\nMore details on what is going on in the next section.\n\n## Details\n\nYou should follow the steps in each of the following section according to your needs.\n\n**📌 NOTE**\\\nSpring gRPC supports Spring Boot 3.4.x and 3.5.x\n\n### Add Milestone and Snapshot Repositories\n\nIf you prefer to add the dependency snippets by hand, follow the directions in the following sections.\n\nTo use the Milestone and Snapshot version, you need to add references to the Spring Milestone and/or Snapshot repositories in your build file.\n\nFor Maven, add the following repository definitions as needed (if you are using snapshots or milestones):\n\n```xml\n  \u003crepositories\u003e\n    \u003crepository\u003e\n      \u003cid\u003espring-milestones\u003c/id\u003e\n      \u003cname\u003eSpring Milestones\u003c/name\u003e\n      \u003curl\u003ehttps://repo.spring.io/milestone\u003c/url\u003e\n      \u003csnapshots\u003e\n        \u003cenabled\u003efalse\u003c/enabled\u003e\n      \u003c/snapshots\u003e\n    \u003c/repository\u003e\n    \u003crepository\u003e\n      \u003cid\u003espring-snapshots\u003c/id\u003e\n      \u003cname\u003eSpring Snapshots\u003c/name\u003e\n      \u003curl\u003ehttps://repo.spring.io/snapshot\u003c/url\u003e\n      \u003creleases\u003e\n        \u003cenabled\u003efalse\u003c/enabled\u003e\n      \u003c/releases\u003e\n    \u003c/repository\u003e\n  \u003c/repositories\u003e\n```\n\nFor Gradle, add the following repository definitions as needed:\n\n```groovy\nrepositories {\n  mavenCentral()\n  maven { url 'https://repo.spring.io/milestone' }\n  maven { url 'https://repo.spring.io/snapshot' }\n}\n```\n\n### Dependency Management\n\nThe `spring-grpc-dependencies` artifact declares the recommended versions of the dependencies used by a given release of Spring gRPC, excluding dependencies already managed by Spring Boot dependency management.\n\nThe `spring-grpc-build-dependencies` artifact declares the recommended versions of all the dependencies used by a given release of Spring gRPC, including dependencies already managed by Spring Boot dependency management.\n\nIf you are running Spring gRPC in a Spring Boot application then use `spring-grpc-dependencies`, otherwise use `spring-grpc-build-dependencies`.\n\nUsing one of these dependency modules avoids the need for you to specify and maintain the dependency versions yourself.\nInstead, the version of the dependency module you are using determines the utilized dependency versions.\nIt also ensures that you’re using supported and tested versions of the dependencies by default, unless you choose to override them.\n\n**📌 NOTE**\\\nThe examples below assume you are running inside a Spring Boot application and therefore use `spring-grpc-dependencies`.\n\nIf you’re a Maven user, you can use the dependencies by adding the following to your pom.xml file -\n\n```xml\n\u003cdependencyManagement\u003e\n    \u003cdependencies\u003e\n        \u003cdependency\u003e\n            \u003cgroupId\u003eorg.springframework.grpc\u003c/groupId\u003e\n            \u003cartifactId\u003espring-grpc-dependencies\u003c/artifactId\u003e\n            \u003cversion\u003e0.8.0-SNAPSHOT\u003c/version\u003e\n            \u003ctype\u003epom\u003c/type\u003e\n            \u003cscope\u003eimport\u003c/scope\u003e\n        \u003c/dependency\u003e\n    \u003c/dependencies\u003e\n\u003c/dependencyManagement\u003e\n```\n\nGradle users can also use the dependencies by leveraging Gradle (5.0+) native support for declaring dependency constraints using a Maven BOM.\nThis is implemented by adding a 'platform' dependency handler method to the dependencies section of your Gradle build script.\nAs 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.\n\n```gradle\ndependencies {\n  implementation platform(\"org.springframework.grpc:spring-grpc-dependencies:0.8.0-SNAPSHOT\")\n}\n```\n\nYou 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.\n\n### gPRC Server\n\nCreate a `@Bean` of type `BindableService`. For example:\n\n```java\n@Service\npublic class GrpcServerService extends SimpleGrpc.SimpleImplBase {\n...\n}\n```\n\n(`BindableService` is the interface that gRPC uses to bind services to the server and `SimpleImplBase` was created for you from your Protobuf file.)\n\nThen, 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):\n\n```java\n@SpringBootApplication\npublic class GrpcServerApplication {\n\tpublic static void main(String[] args) {\n\t\tSpringApplication.run(GrpcServerApplication.class, args);\n\t}\n}\n```\n\nRun it from your IDE, or on the command line with `mvn spring-boot:run` or `gradle bootRun`.\n\n### gRPC Client\n\nTo 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:\n\n```java\n@Bean\nSimpleGrpc.SimpleBlockingStub stub(GrpcChannelFactory channels) {\n\treturn SimpleGrpc.newBlockingStub(channels.createChannel(\"0.0.0.0:9090\"));\n}\n```\n\nThen you can inject the stub and use it in your application.\n\nThe 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:\n\n```java\n@Bean\nSimpleGrpc.SimpleBlockingStub stub(GrpcChannelFactory channels) {\n\treturn SimpleGrpc.newBlockingStub(channels.createChannel(\"local\"));\n}\n```\n\nthen in `application.properties`:\n\n```properties\nspring.grpc.client.channels.local.address=0.0.0.0:9090\n```\n\nThere is a default named channel that you can configure in the same way via `spring.grpc.client.default-channel.*`. It will be used by default if there is no channel with the name specified in the channel creation.\n\n### Native Images\n\nNative 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).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspring-projects%2Fspring-grpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspring-projects%2Fspring-grpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspring-projects%2Fspring-grpc/lists"}