Java Microservice

Java Microservice

Overview

A Java service is six things: config, an HTTP surface, state (DB + cache), async work, outbound calls, and operability. On the JVM the framework supplies most of the plumbing, so the work is choosing the framework, then tuning the runtime — the JVM's defaults were designed for long-lived servers on dedicated hardware, not for containers.

Verified against Java 25 LTS (GA 2025-09-16) and Spring Boot 4.1.0 as of 2026-08. Library versions throughout come from Maven Central, not from blog posts. Note no Spring Boot release is LTS — every minor gets ~12 months of OSS support on a 6-month cadence, so plan an annual minor upgrade.

When to Use

• Starting a new JVM service, or adding an endpoint/listener to an existing one
• Choosing a framework, persistence layer, cache client, or resilience library
• Reviewing Java service code for production-readiness
• Migrating: Boot 2.7 → 3.x/4.x, Java 17 → 21/25, javax → jakarta
• Enabling virtual threads, or diagnosing pinning
• Diagnosing: OOMKills, long GC pauses, pool exhaustion, slow startup, thread starvation
• Containerising a JVM service or tuning it for Kubernetes

Not for: Android, desktop, or non-service JVM work.

Step 0: Choose the framework

Startup/memory differences are real but rarely decisive for a long-running service — startup is a one-time cost. Choose on ecosystem and constraints, not benchmark tables. Full comparison, Boot 4 migration breaks, and benchmark caveats in references/frameworks.md.

Quick Reference

Bootstrap a new service

Two-module Gradle split is a good default — it makes the domain layer's independence structural rather than aspirational:

myservice/
  settings.gradle          # include ':myservice-domain', ':myservice-service'
  build.gradle             # cross-project config only
  domain/                  # entities, value objects, ports. No web/framework deps.
  service/                 # controllers, config, adapters, main class
  Dockerfile

// settings.gradle
rootProject.name = 'myservice'
include(':myservice-domain')
include(':myservice-service')
project(":myservice-domain").projectDir  = file('domain')
project(":myservice-service").projectDir = file('service')

1. Java 25, Spring Boot 4.0.x, dependencies via the BOM/platform (one version source — never mix plugin and starter versions).
2. @ConfigurationProperties records with jakarta.validation annotations, so bad config fails at startup rather than in a request.
3. Constructor injection everywhere. No @Autowired fields.
4. @ControllerAdvice with one error envelope and an error-code enum.
5. Actuator: /actuator/health/liveness and /health/readiness (they are different — see observability.md).
6. HikariCP + explicit timeouts; maxLifetime below the DB/LB idle timeout.
7. spring.threads.virtual.enabled=true — but first replace any fixed pool that was acting as a concurrency limiter with an explicit Semaphore.
8. -XX:MaxRAMPercentage=75 (never -Xmx in a container).

The non-negotiables

1. Never -Xmx in a container. Use -XX:MaxRAMPercentage=75. A fixed heap ignores the pod's actual limit.
2. Every outbound call has a connect and read timeout. An unconfigured RestTemplate/HttpClient waits forever, exhausts the pool, and takes the service down while health checks pass.
3. Constructor injection, final fields. Field @Autowired hides cyclic dependencies, defeats immutability, and needs reflection to test.
4. Config validated at startup. @ConfigurationProperties + @Validated, not 83 scattered @Values.
5. Name the transaction boundary. @Transactional at the service method that must be atomic — not sprinkled, not absent. Beware self-invocation: an internal call bypasses the proxy and the annotation does nothing.
6. Liveness ≠ readiness. Liveness must not check dependencies, or one DB blip restarts every pod at once and turns a blip into an outage.
7. maxLifetime < the shortest idle timeout in front of the DB, or you hand out dead connections.
8. Idempotent consumers, @Valid @Payload on messages, explicit acknowledgement mode, DLQ configured.
9. Structured JSON logs on stdout with an MDC correlation ID. Never secrets.
10. -XX:+ExitOnOutOfMemoryError + HeapDumpOnOutOfMemoryError. A limping post-OOM JVM serves errors while looking alive; better to die and be restarted.

Reference Map

Common Mistakes

Several of these are drawn from real production services — they are the mistakes that actually get made, not hypotheticals.