Skip to main content

Java Spring Boot gRPC Service Archetype

Production-ready Spring Boot gRPC microservice with comprehensive observability and testing

Generate a complete enterprise-grade Java Spring Boot gRPC microservice with advanced features including persistence, monitoring, security, and comprehensive testing frameworks.

Overview​

The java-spring-boot-grpc-service archetype creates a modular, production-ready gRPC microservice built on Spring Boot with enterprise patterns and best practices.

Key Characteristics​

  • Framework: Spring Boot 3.x with modern Java patterns
  • Communication: gRPC with Protocol Buffers for high-performance service communication
  • Architecture: Hexagonal architecture with clear separation of concerns
  • Persistence: Hibernate ORM with Liquibase database migrations
  • Testing: Comprehensive test suites with TestContainers integration
  • Observability: Built-in metrics, health checks, and distributed tracing

Service Architecture​

Configuration & Prompts​

When generating this archetype, you'll be prompted for:

PropertyDescriptionExampleRequired
project-prefixService domain name for entities and RPC stubsShoppingCart
suffixService type (Service, Orchestrator, Adapter)Service
group-idMaven group ID for package organizationcom.mycompany.ecommerce
team-nameTeam ownership for artifacts and documentationGrowth
service-portgRPC service port9010
management-portHTTP management/health check port9011
persistenceDatabase persistence typeCockroachDB or None
artifactory-hostPrivate Maven repository hostartifacts.company.com

Derived Properties​

The archetype automatically calculates additional properties:

  • database-port: service-port + 2 (e.g., 9012)
  • debug-port: service-port + 9 (e.g., 9019)
  • Package structure based on group-id and project naming

Generated Project Structure​

The archetype creates a comprehensive multi-module Maven project:

Click to enlarge

Module Breakdown​

Core Modules​

  • {artifact-id}-api - Public API contracts and DTOs
  • {artifact-id}-core - Business logic and domain services
  • {artifact-id}-persistence - JPA entities and repositories
  • {artifact-id}-grpc - Protocol Buffer definitions
  • {artifact-id}-server - Main application and gRPC implementation

Supporting Modules​

  • {artifact-id}-client - Java client library for consumers
  • {artifact-id}-integration-tests - End-to-end test suites
  • {artifact-id}-bom - Bill of Materials for dependency management

Technology Stack & Features​

Core Technologies​

Framework Stack​

  • Spring Boot 3.x
  • Spring Data JPA
  • Spring Boot Actuator
  • Maven 3.8+

gRPC & Communication​

  • gRPC Java
  • Protocol Buffers
  • gRPC Health Checking
  • Reflection Service

Persistence & Database​

  • Hibernate ORM
  • Liquibase migrations
  • CockroachDB support
  • Connection pooling

Production Features​

Comprehensive Observability

Spring Boot Actuator endpoints including /health, /info, /metrics, /env, /liquibase, and /threaddump

Enterprise Security

Built-in security patterns, authentication hooks, and secure configuration management

Database Management

Liquibase changesets, entity versioning, and production-ready database patterns

DevOps Integration

Docker containerization, GitLab CI/CD, Tilt integration for local Kubernetes development

Testing & Quality Assurance​

Comprehensive Testing Strategy​

Unit & Integration Testing​

  • JUnit 5 with Spring Boot Test
  • Mockito for service mocking
  • TestContainers for database integration
  • gRPC testing utilities

Performance & Load Testing​

  • k6 load testing scripts for gRPC
  • HTTP endpoint performance tests
  • Database connection pool testing
  • Memory and CPU profiling hooks

TestContainers Integration​

Out-of-the-box Testing Environment

Includes PostgreSQL and LocalStack TestContainers for realistic integration testing without external dependencies.

Development Workflow​

Local Development Setup​

# Generate the service
archetect render git@github.com:p6m-archetypes/java-spring-boot-grpc-service.archetype.git my-service

cd my-service

# Build all modules
mvn clean install

# Run with local development profile
mvn spring-boot:run -pl my-service-server

# Run integration tests
mvn test -pl my-service-integration-tests

# Start with Tilt for Kubernetes development
tilt up

Service Interaction Examples​

gRPC Service Calls​

# Health check
grpcurl -plaintext localhost:9010 grpc.health.v1.Health/Check

# Service-specific calls (example)
grpcurl -plaintext -d '{"name": "example"}' \
  localhost:9010 com.mycompany.MyService/GetEntity

HTTP Management Endpoints​

# Health status
curl http://localhost:9011/actuator/health

# Application metrics
curl http://localhost:9011/actuator/metrics

# Environment info
curl http://localhost:9011/actuator/env

Database & Persistence Patterns​

Entity Framework​

Click to enlarge

Database Migration Strategy​

  • Liquibase Changesets: Version-controlled database schema evolution
  • Entity Auditing: Automatic created/modified timestamps and user tracking
  • Optimistic Locking: Version-based concurrency control
  • Connection Pooling: Production-ready connection management

Production Deployment​

Container Deployment​

# Multi-stage Docker build included
FROM openjdk:17-jdk-slim as builder
COPY . /app
WORKDIR /app
RUN ./mvnw clean package -DskipTests

FROM openjdk:17-jre-slim
COPY --from=builder /app/target/*.jar app.jar
EXPOSE 9010 9011
ENTRYPOINT ["java", "-jar", "/app.jar"]

Kubernetes Integration​

Tilt Development​

  • Local Kubernetes development with hot reloading
  • Automatic image building and deployment
  • Log streaming and debugging tools
  • Resource monitoring and scaling

Production Deployment​

  • Kubernetes manifests included
  • Health check and readiness probes
  • Resource limits and requests
  • ConfigMap and Secret integration

Monitoring & Observability​

Built-in Monitoring Stack​

Health & Readiness

Comprehensive health checks including database connectivity, external service dependencies, and custom business health indicators.

Metrics Collection

Micrometer metrics integration with support for Prometheus, custom business metrics, and performance monitoring.

Distributed Tracing

OpenTelemetry integration for request tracing across service boundaries and database operations.

Next Steps​

After Generation​

  1. Review Configuration: Update application.yml with environment-specific settings
  2. Define Business Logic: Implement domain services in the core module
  3. Create gRPC Contracts: Define service methods in Protocol Buffer files
  4. Set Up CI/CD: Customize GitLab CI configuration for your environment
  5. Configure Monitoring: Set up metrics collection and alerting

Integration Patterns​

Service Mesh Integration

This archetype is designed to work seamlessly with service mesh solutions like Istio, providing automatic traffic management, security, and observability.

Additional Resources​

This archetype provides a solid foundation for building enterprise-grade Java microservices with modern development practices and production-ready features.