{"id":16119877,"url":"https://github.com/piomin/sample-microservices-protobuf","last_synced_at":"2025-10-11T00:12:13.375Z","repository":{"id":22165501,"uuid":"93274182","full_name":"piomin/sample-microservices-protobuf","owner":"piomin","description":"creating microservices with rest http api exposed over google protocol buffer on spirng-boot ","archived":false,"fork":false,"pushed_at":"2025-09-13T23:05:03.000Z","size":176,"stargazers_count":44,"open_issues_count":2,"forks_count":35,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-09-14T01:07:08.922Z","etag":null,"topics":["exposing-microservices","http","performance","protocol-buffers","rest-api","rest-protocol-buffers","spring-boot"],"latest_commit_sha":null,"homepage":"https://piotrminkowski.com/","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/piomin.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-06-03T21:12:10.000Z","updated_at":"2025-09-13T23:04:56.000Z","dependencies_parsed_at":"2023-10-05T05:05:48.103Z","dependency_job_id":"73540ede-6aad-4792-a7bd-c8ff9b9de701","html_url":"https://github.com/piomin/sample-microservices-protobuf","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/piomin/sample-microservices-protobuf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piomin%2Fsample-microservices-protobuf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piomin%2Fsample-microservices-protobuf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piomin%2Fsample-microservices-protobuf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piomin%2Fsample-microservices-protobuf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piomin","download_url":"https://codeload.github.com/piomin/sample-microservices-protobuf/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piomin%2Fsample-microservices-protobuf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005649,"owners_count":26083940,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["exposing-microservices","http","performance","protocol-buffers","rest-api","rest-protocol-buffers","spring-boot"],"created_at":"2024-10-09T20:55:20.710Z","updated_at":"2025-10-11T00:12:13.367Z","avatar_url":"https://github.com/piomin.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Spring Boot with Protocol Buffers and gRPC [![Twitter](https://img.shields.io/twitter/follow/piotr_minkowski.svg?style=social\u0026logo=twitter\u0026label=Follow%20Me)](https://twitter.com/piotr_minkowski)\n\n[![CircleCI](https://circleci.com/gh/piomin/sample-microservices-protobuf.svg?style=svg)](https://circleci.com/gh/piomin/sample-microservices-protobuf)\n\n[![SonarCloud](https://sonarcloud.io/images/project_badges/sonarcloud-black.svg)](https://sonarcloud.io/dashboard?id=piomin_sample-microservices-protobuf)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=piomin_sample-microservices-protobuf\u0026metric=bugs)](https://sonarcloud.io/dashboard?id=piomin_sample-microservices-protobuf)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=piomin_sample-microservices-protobuf\u0026metric=coverage)](https://sonarcloud.io/dashboard?id=piomin_sample-microservices-protobuf)\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=piomin_sample-microservices-protobuf\u0026metric=ncloc)](https://sonarcloud.io/dashboard?id=piomin_sample-microservices-protobuf)\n\nThere are two articles related to that repo:\n1. How to expose Protocol Buffers over REST. Detailed description can be found here: [Exposing Microservices over REST Protocol Buffers](https://piotrminkowski.com/2017/06/05/exposing-microservices-over-rest-protocol-buffers/)\n2. How to create gRPC service with Spring Boot and integrate gRPC client with Spring Cloud discovery. Detailed description can be found here: [Introduction to gRPC with Spring Boot](https://piotrminkowski.com/2023/08/29/introduction-to-grpc-with-spring-boot/)\n\n## Application Architecture\n\nThis project demonstrates a microservices architecture using Spring Boot with two distinct inter-service communication approaches: **REST with Protocol Buffers** and **gRPC**. The same business logic (Account and Customer management) is implemented in parallel for hands-on comparison.\n\n### Microservices Overview\n\nThe repository contains **5 Spring Boot applications** and one service discovery component:\n\n#### Service Discovery\n- **discovery-service**  \n  - **Port:** 8761  \n  - **Role:** Netflix Eureka server for service registration and discovery  \n  - **Dashboard URL:** http://localhost:8761  \n\n#### Business Services (REST + Protocol Buffers)\n- **account-service**  \n  - **Port:** 2222 (configurable via `PORT` env var)  \n  - **Communication:** HTTP + Protobuf  \n  - **Proto file:** `account-service/src/main/proto/account.proto`  \n\n- **customer-service**  \n  - **Port:** 3333 (configurable via `PORT` env var)  \n  - **Communication:** HTTP + Protobuf  \n  - **Proto file:** `customer-service/src/main/proto/customer.proto`  \n\n#### Business Services (gRPC)\n- **account-service-grpc**  \n  - **HTTP Port:** 8081  \n  - **gRPC Port:** 9091  \n  - **Library:** `grpc-server-spring-boot-starter`  \n  - **Services:** `FindByNumber`, `FindByCustomer`, `FindAll`, `AddAccount`\n\n- **customer-service-grpc**  \n  - **HTTP Port:** 8081  \n  - **gRPC Port:** 9091  \n  - **Services:** `FindByPesel`, `FindById`, `FindAll`, `AddCustomer`  \n  - **Discovery:** Registers with Eureka\n\n### Technology Stack\n\n- **Java 21**  \n- **Spring Boot 3.4.5**  \n- **Spring Cloud 2024.0.1** (Eureka, LoadBalancer, OpenFeign)  \n- **Protocol Buffers 4.31.1**  \n- **gRPC 1.63.0**  \n- **Maven 3.8+**  \n- **Docker \u0026 Docker Compose** (optional)\n\n### Communication Patterns\n\n#### REST + Protobuf\n\n```\nClient → API Gateway → Service Discovery → Customer Service (HTTP:3333, Protobuf) → Account Service (HTTP:2222, Protobuf)\n```\n\n#### gRPC\n\n```\nClient → gRPC Client → Service Discovery → Customer Service gRPC (9091) → Account Service gRPC (9091)\n```\n\n#### Service Discovery Flow\n\n1. Start **discovery-service** (8761).  \n2. Each microservice registers with Eureka.  \n3. Clients and services discover each other by querying Eureka.  \n4. Spring Cloud LoadBalancer handles service-side load balancing.  \n5. Health checks via Spring Boot Actuator endpoints.\n\n## Running Applications Locally\n\n### Prerequisites\n\n- **Java 21+** (`java --version`)  \n- **Maven 3.8+** (`mvn --version`)  \n- **Git 2+** (`git --version`)  \n- Optional: **Docker \u0026 Docker Compose**  \n\n### Building the Applications\n\n1. Clone the repo:\n   ```bash\n   git clone https://github.com/piomin/sample-microservices-protobuf.git\n   cd sample-microservices-protobuf\n   ```\n2. Compile (includes Protobuf \u0026 gRPC codegen):\n   ```bash\n   mvn clean compile\n   ```\n3. Package JARs (skip tests for speed):\n   ```bash\n   mvn clean package -DskipTests\n   ```\n\n### Service Startup Order\n\n\u003e **Important:** Always start in this sequence to ensure proper registration.\n\n1. **Discovery Service**  \n   ```bash\n   cd discovery-service  \n   mvn spring-boot:run\n   ```\n2. **REST + Protobuf Approach**  \n   ```bash\n   # In parallel terminals:\n   cd account-service \u0026\u0026 mvn spring-boot:run\n   cd customer-service \u0026\u0026 mvn spring-boot:run\n   ```\n   **OR**  \n   **gRPC Approach**  \n   ```bash\n   cd account-service-grpc \u0026\u0026 mvn spring-boot:run\n   cd customer-service-grpc \u0026\u0026 mvn spring-boot:run\n   ```\n\n### Running with JARs\n\n```bash\n# Discovery\njava -jar discovery-service/target/discovery-service-*.jar\n# Choose one approach per microservice:\njava -jar account-service/target/*.jar\njava -jar customer-service/target/*.jar\n# OR for gRPC:\njava -jar account-service-grpc/target/*.jar\njava -jar customer-service-grpc/target/*.jar\n```\n\n### Verification \u0026 Testing\n\n- **Eureka Dashboard:** http://localhost:8761  \n- **Health Checks:**  \n  ```bash\n  curl http://localhost:8761/actuator/health\n  curl http://localhost:2222/actuator/health\n  curl http://localhost:3333/actuator/health\n  curl http://localhost:9091/actuator/health\n  ```\n- **REST API Example:**  \n  ```bash\n  curl -H \"Accept: application/json\" http://localhost:3333/customers\n  ```\n- **gRPC Example (using grpcurl):**  \n  ```bash\n  grpcurl -plaintext -d '{}' localhost:9091 model.CustomersService/FindAll\n  ```\n\n### Port Reference\n\n| Service                   | HTTP Port | gRPC Port | Env Var | Protocol        |\n|---------------------------|-----------|-----------|---------|-----------------|\n| discovery-service         | 8761      | –         | –       | HTTP            |\n| account-service           | 2222      | –         | PORT    | HTTP + Protobuf |\n| customer-service          | 3333      | –         | PORT    | HTTP + Protobuf |\n| account-service-grpc      | 8081      | 9091      | –       | gRPC            |\n| customer-service-grpc     | 8081      | 9091      | –       | gRPC            |\n\n### Troubleshooting \u0026 Tips\n\n- **Port Conflicts:**  \n  ```bash\n  lsof -ti:8761 | xargs kill -9\n  ```\n- **Protobuf Errors:**  \n  ```bash\n  mvn clean compile -X\n  ```\n- **Increase JVM Memory:**  \n  ```bash\n  export MAVEN_OPTS=\"-Xmx2G -Xms1G\"\n  mvn spring-boot:run\n  ```\n- **Hot Reloading:** Add DevTools dependency:\n  ```xml\n  \u003cdependency\u003e\n    \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n    \u003cartifactId\u003espring-boot-devtools\u003c/artifactId\u003e\n    \u003cscope\u003eruntime\u003c/scope\u003e\n    \u003coptional\u003etrue\u003c/optional\u003e\n  \u003c/dependency\u003e\n  ```\n- **gRPC Testing:** Use `grpcurl` or BloomRPC for introspection.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiomin%2Fsample-microservices-protobuf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiomin%2Fsample-microservices-protobuf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiomin%2Fsample-microservices-protobuf/lists"}