{"id":13670485,"url":"https://github.com/dapr/java-sdk","last_synced_at":"2026-03-02T17:12:34.895Z","repository":{"id":37743035,"uuid":"213981789","full_name":"dapr/java-sdk","owner":"dapr","description":"Dapr SDK for Java","archived":false,"fork":false,"pushed_at":"2025-05-08T18:32:57.000Z","size":101619,"stargazers_count":270,"open_issues_count":142,"forks_count":216,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-05-11T05:58:57.296Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dapr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-10-09T17:30:19.000Z","updated_at":"2025-05-08T18:33:00.000Z","dependencies_parsed_at":"2023-02-19T04:00:31.264Z","dependency_job_id":"fc610ace-20c2-4759-82fc-156219f681ae","html_url":"https://github.com/dapr/java-sdk","commit_stats":{"total_commits":505,"total_committers":88,"mean_commits":5.738636363636363,"dds":0.5683168316831684,"last_synced_commit":"3dc96d7d730f22681631ef5190bb8e748eca5b51"},"previous_names":[],"tags_count":86,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dapr%2Fjava-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dapr%2Fjava-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dapr%2Fjava-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dapr%2Fjava-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dapr","download_url":"https://codeload.github.com/dapr/java-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149960,"owners_count":22022851,"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":"2024-08-02T09:00:43.156Z","updated_at":"2026-03-02T17:12:34.879Z","avatar_url":"https://github.com/dapr.png","language":"Java","funding_links":[],"categories":["Uncategorized","微服务库"],"sub_categories":["Uncategorized"],"readme":"# Dapr SDK for Java\n\n[![Maven Central](https://img.shields.io/maven-central/v/io.dapr/dapr-sdk.svg?label=Maven%20Central\u0026style=flat)](https://central.sonatype.com/artifact/io.dapr/dapr-sdk) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/dapr/java-sdk/.github%2Fworkflows%2Fbuild.yml?branch=master\u0026label=Build\u0026logo=github)](https://github.com/dapr/java-sdk/actions/workflows/build.yml) [![codecov](https://codecov.io/gh/dapr/java-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/dapr/java-sdk) [![GitHub License](https://img.shields.io/github/license/dapr/java-sdk?style=flat\u0026label=License\u0026logo=github)](https://github.com/dapr/java-sdk/blob/master/LICENSE) [![FOSSA Status](https://app.fossa.com/api/projects/custom%2B162%2Fgithub.com%2Fdapr%2Fjava-sdk.svg?type=shield)](https://app.fossa.com/projects/custom%2B162%2Fgithub.com%2Fdapr%2Fjava-sdk?ref=badge_shield) [![GitHub issue custom search in repo](https://img.shields.io/github/issues-search/dapr/java-sdk?query=type%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22\u0026label=Good%20first%20issues\u0026style=flat\u0026logo=github)](https://github.com/dapr/java-sdk/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) [![Discord](https://img.shields.io/discord/778680217417809931?label=Discord\u0026style=flat\u0026logo=discord)](http://bit.ly/dapr-discord) [![YouTube Channel Views](https://img.shields.io/youtube/channel/views/UCtpSQ9BLB_3EXdWAUQYwnRA?style=flat\u0026label=YouTube%20views\u0026logo=youtube)](https://youtube.com/@daprdev) [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/daprdev?logo=x\u0026style=flat)](https://twitter.com/daprdev)\n\nThis is the Dapr SDK for Java, including the following features:\n\n* PubSub\n* Service Invocation\n* Binding\n* State Store\n* Actors\n* Workflows\n\n## Getting Started\n\n### Architecture Overview\n\nThe diagram below shows how a Java application interacts with the Dapr runtime through the Java SDK:\n\n```mermaid\nflowchart LR\n    A[End User Application] --\u003e|HTTP or gRPC| B[Dapr Java SDK]\n    B --\u003e|Dapr API calls| C[Dapr Sidecar]\n    C --\u003e|Components| D[State Stores, Pub/Sub, Services, etc.]\n\n    %% Optional grouping for clarity\n    subgraph R[Dapr Runtime]\n        C\n        D\n    end\n```\n\nFor the full list of available APIs, see the [Dapr API reference](https://docs.dapr.io/reference/api/)\n\n### Pre-Requisites\n* SDKMAN! installed (recommended):\n    * [SDKMAN!](https://sdkman.io)\n* Java IDE installed:\n    * [IntelliJ](https://www.jetbrains.com/idea/download/)\n    * [Eclipse](https://www.eclipse.org/downloads/)\n    * [Apache NetBeans](https://netbeans.apache.org/download/index.html)\n    * [Visual Studio Code](https://code.visualstudio.com/Download)\n    * Any other IDE for Java that you prefer.\n* Install one of the following build tools for Java:\n    * [Maven 3.x](https://maven.apache.org/install.html)\n    * [Gradle 6.x](https://gradle.org/install/)\n* If needed, install the corresponding plugin for the build tool in your IDE, for example:\n    * [Maven in IntelliJ](https://www.jetbrains.com/help/idea/maven.html)\n    * [Gradle in IntelliJ](https://www.jetbrains.com/help/idea/gradle-settings.html)\n    * [Maven in Eclipse with m2e](https://projects.eclipse.org/projects/technology.m2e)\n    * [Gradle in Eclipse with Buildship](https://projects.eclipse.org/projects/tools.buildship)\n* An existing Java Maven or Gradle project. You may also start a new project via one of the options below:\n    * [New Maven project in IntelliJ](https://www.jetbrains.com/help/idea/maven-support.html#create_new_maven_project)\n    * [Maven in 5 minutes](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html)\n    * [Install toxiproxy-server binary](https://github.com/Shopify/toxiproxy/releases)\n\n### Install JDK\n\nIf using [SDKMAN!](https://sdkman.io), execute `sdk env install` to install the required JDK.\n\n### Importing Dapr's Java SDK\nFor a Maven project, add the following to your `pom.xml` file:\n```xml\n\u003cproject\u003e\n  ...\n  \u003cdependencies\u003e\n    ...\n     \u003c!-- Dapr's core SDK with all features, except Actors. --\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eio.dapr\u003c/groupId\u003e\n      \u003cartifactId\u003edapr-sdk\u003c/artifactId\u003e\n      \u003cversion\u003e1.17.0\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003c!-- Dapr's SDK for Actors (optional). --\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eio.dapr\u003c/groupId\u003e\n      \u003cartifactId\u003edapr-sdk-actors\u003c/artifactId\u003e\n      \u003cversion\u003e1.17.0\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003c!-- Dapr's SDK integration with SpringBoot (optional). --\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eio.dapr\u003c/groupId\u003e\n      \u003cartifactId\u003edapr-sdk-springboot\u003c/artifactId\u003e\n      \u003cversion\u003e1.17.0\u003c/version\u003e\n    \u003c/dependency\u003e\n    ...\n  \u003c/dependencies\u003e\n  ...\n\u003c/project\u003e\n```\n\nFor a Gradle project, add the following to your `build.gradle` file:\n\n```\ndependencies {\n...\n    // Dapr's core SDK with all features, except Actors.\n    compile('io.dapr:dapr-sdk:1.17.0')\n    // Dapr's SDK for Actors (optional).\n    compile('io.dapr:dapr-sdk-actors:1.17.0')\n    // Dapr's SDK integration with SpringBoot (optional).\n    compile('io.dapr:dapr-sdk-springboot:1.17.0')\n}\n```\n\n### Running the examples\nClone this repository including the submodules:\n\n```sh\ngit clone https://github.com/dapr/java-sdk.git\n```\n\nThen head over to build the [Maven](https://maven.apache.org/install.html) (Apache Maven version 3.x) project:\n\n```sh\n# make sure you are in the `java-sdk` directory.\n./mvnw clean install\n```\n\nTry the following examples to learn more about Dapr's Java SDK:\n* [Invoking a Http service](./examples/src/main/java/io/dapr/examples/invoke/http)\n* [Invoking a Grpc service](./examples/src/main/java/io/dapr/examples/invoke/grpc)\n* [State management](./examples/src/main/java/io/dapr/examples/state)\n* [PubSub with subscriber](./examples/src/main/java/io/dapr/examples/pubsub/)\n* [PubSub with streaming subscription](./examples/src/main/java/io/dapr/examples/pubsub/stream/)\n* [Binding with input over Http](./examples/src/main/java/io/dapr/examples/bindings/http)\n* [Actors](./examples/src/main/java/io/dapr/examples/actors/)\n* [Workflows](./examples/src/main/java/io/dapr/examples/workflows/)\n* [Secrets management](./examples/src/main/java/io/dapr/examples/secrets)\n* [Configuration](./examples/src/main/java/io/dapr/examples/configuration)\n* [Distributed tracing with OpenTelemetry SDK](./examples/src/main/java/io/dapr/examples/tracing)\n* [Exception handling](./examples/src/main/java/io/dapr/examples/exception)\n* [Unit testing](./examples/src/main/java/io/dapr/examples/unittesting)\n\n### Running Spring Boot examples\n\nThe Spring Boot integration for Dapr use [Testcontainers](https://testcontainers.com) to set up a local environment development flow that doesn't \nrequire the use of the `dapr` CLI and it integrates with the Spring Boot programming model. \n\nYou can find a [step-by-step tutorial showing this integration here](./spring-boot-examples/README.md).\n\n### API Documentation\n\nPlease, refer to our [Javadoc](https://dapr.github.io/java-sdk/) website.\n\n### Reactor API\n\nThe Java SDK for Dapr is built using [Project Reactor](https://projectreactor.io/). It provides an asynchronous API for Java. A result is consumed synchronously by using the `block()` method, as shown in the examples referenced above.\n\nThe code below does not make any API call, it simply returns the [Mono](https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Mono.html) publisher object. Nothing happens until the application subscribes or blocks on the result:\n\n```java\nMono\u003cVoid\u003e result = daprClient.publishEvent(\"mytopic\", \"my message\");\n```\n\nTo start execution and receive the result object synchronously (`void` or `Void` becomes an empty result), use `block()`. The code below shows how to execute the call and consume an empty response:\n```java\nMono\u003cVoid\u003e result = daprClient.publishEvent(\"mytopic\", \"my message\");\nresult.block();\n```\n\n### How to use a custom serializer\n\nThis SDK provides a basic serialization for request/response objects, and state objects. Applications should provide their own serialization for production scenarios.\n\n1. Implement the [DaprObjectSerializer](https://dapr.github.io/java-sdk/io/dapr/serializer/DaprObjectSerializer.html) interface. See [this class](sdk-actors/src/test/java/io/dapr/actors/runtime/JavaSerializer.java) as an example.\n2. Use your serializer class in the following scenarios:\n    * When building a new instance of [DaprClient](https://dapr.github.io/java-sdk/io/dapr/client/DaprClient.html):\n    ```java\n    DaprClient client = (new DaprClientBuilder())\n        .withObjectSerializer(new MyObjectSerializer()) // for request/response objects.\n        .withStateSerializer(new MyStateSerializer()) // for state objects.\n        .build();\n    ```\n    * When registering an Actor Type:\n    ```java\n    ActorRuntime.getInstance().registerActor(\n      DemoActorImpl.class,\n      new MyObjectSerializer(), // for request/response objects.\n      new MyStateSerializer()); // for state objects.\n    ```\n    * When building a new instance of [ActorProxy](https://dapr.github.io/java-sdk/io/dapr/actors/client/ActorProxy.html) to invoke an Actor instance, use the same serializer as when registering the Actor Type:\n    ```java\n    try (ActorClient actorClient = new ActorClient()) {\n      DemoActor actor = (new ActorProxyBuilder(DemoActor.class, actorClient))\n          .withObjectSerializer(new MyObjectSerializer()) // for request/response objects.\n          .build(new ActorId(\"100\"));\n    }\n    ```\n\n\n### Debug a Java application or Dapr's Java SDK\n\n**In IntelliJ Community Edition, consider [debugging in IntelliJ](https://docs.dapr.io/developing-applications/local-development/ides/intellij/).**\n\n**In Visual Studio Code, consider [debugging in Visual Studio Code](https://docs.dapr.io/developing-applications/local-development/ides/vscode/).**\n\nIf you need to debug your Application, run the Dapr sidecar separately, and then start the application from your IDE (IntelliJ or Eclipse, for example).\nFor Linux and MacOS:\n\n```sh\ndapr run --app-id testapp --app-port 3000 --dapr-http-port 3500 --dapr-grpc-port 5001\n```\n\n\u003e Note: confirm the correct port that the app will listen to and that the Dapr ports above are free, changing the ports if necessary.\n\nWhen running your Java application from your IDE, make sure the following environment variables are set, so the Java SDK knows how to connect to Dapr's sidecar:\n```\nDAPR_HTTP_PORT=3500\nDAPR_GRPC_PORT=5001\n```\n\nNow you can go to your IDE and debug your Java application, using port `3500` to call Dapr while also listening to port `3000` to expose Dapr's callback endpoint.\n\n### Exception handling\n\nMost exceptions thrown from the SDK are instances of `DaprException`. `DaprException` extends from `RuntimeException`, making it compatible with Project Reactor. See the [exception example](./examples/src/main/java/io/dapr/examples/exception) for more details.\n\n## Development\n\n### Update URL to fetch proto files\n\nChange the `dapr.proto.baseurl` property below in [pom.xml](./pom.xml) to point to the URL for the desired commit hash in Git if you need to target a proto file that is not been merged into master yet. \n\nNote: You may need to run `./mvnw clean` after changing this setting to remove any auto-generated files so that the new proto files get downloaded and compiled.\n\n```xml\n\u003cproject\u003e\n  ...\n  \u003cproperties\u003e\n    ...\n    \u003c!-- change this .... --\u003e\n    \u003cdapr.proto.baseurl\u003ehttps://raw.githubusercontent.com/dapr/dapr/(current ref in pom.xml)/dapr/proto\u003c/dapr.proto.baseurl\u003e\n    \u003c!-- to something like this: --\u003e\n    \u003cdapr.proto.baseurl\u003ehttps://raw.githubusercontent.com/dapr/dapr/1ac5d0e8590a7d6772c9957c236351ed992ccb19/dapr/proto\u003c/dapr.proto.baseurl\u003e\n    ...\n  \u003c/properties\u003e\n  ...\n\u003c/project\u003e\n```\n\n### Running Integration Tests (ITs)\n\n#### Pre-Requisites\n* [Pre-Requisites for the SDK](#pre-requisites)\n* Docker installed \n  * [Docker Compose](https://docs.docker.com/compose/install/) \n  * [Docker Desktop](https://www.docker.com/products/docker-desktop)\n* Bash shell\n  * In Windows use [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install)\n  * In Linux and Mac, default shells are enough\n\n#### Code\n\nThe code for the tests are present inside the project [sdk-tests](./sdk-tests). This module alone can be imported as a separate project in IDEs. \nThis project depends on the rest of the JARs built by the other modules in the repo like [sdk](./sdk), [sdk-springboot](./sdk-springboot) etc.\n\nAs a starting point for running the Integration Tests, first run `./mvnw clean install` from the root of the repo to build the JARs for the different modules, except the `sdk-tests` module.\n\n#### Run all the dependent services spun up during build\n\nDuring normal CI build, docker compose is used to bring up services like MongoDB, Hashicorp Vault, Apache Zookeeper, Kafka etc. \n\nSimilarly, all of these need to be run for running the ITs either individually or as a whole.\n\nRun the following commands from the root of the repo to start all the docker containers that the tests depend on.\n\n```bash\ndocker compose -f ./sdk-tests/deploy/local-test.yml up -d\n```\n\nTo stop the containers and services, run the following commands.\n\n```bash\ndocker compose -f ./sdk-tests/deploy/local-test.yml down\n```\n\n\n#### Run all ITs from command line\nFrom the `java-sdk` repo root, change to the `sdk-tests` directory and run the following command.\n\n```bash\n## with current directory as /java-sdk/sdk-tests/\n\n../mvnw clean install\n```\n\nThe above command runs all the integration tests present in the `sdk-tests` project. \n\n#### Run Individual tests from IntelliJ\n\nIn IntelliJ, go to `File \u003e New \u003e Project from Existing Sources...`. Import the `sdk-tests` project. \n\nOnce the project has been imported, the individual tests can be run normally as any Unit Tests, from the IDE itself.\n\n![intellij-integration-test](./examples/src/main/resources/img/intellij-integration-test.png).\n\n\u003e Sometimes when the `sdk-tests` project does not build correctly, try `File \u003e Invalidate Caches...`  and try restarting IntelliJ.\n\nYou should be able to set breakpoints and Debug the test directly from IntelliJ itself as seen from the above image. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdapr%2Fjava-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdapr%2Fjava-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdapr%2Fjava-sdk/lists"}