home / skills / hoangnguyen0403 / agent-skills-standard / microservices

microservices skill

This skill helps you implement Spring Boot microservices with synchronized and asynchronous messaging, enforcing best practices and robust contracts.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill microservices

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.2 KB

---
name: Spring Boot Microservices
description: Standards for synchronous (Feign) and asynchronous (Cloud Stream) communication
metadata:
  labels: [spring-boot, microservices, feign, kafka]
  triggers:
    files: ['**/*Client.java', '**/*Consumer.java']
    keywords: [feign-client, spring-cloud-stream, rabbitmq, resilience4j]
---

# Spring Boot Microservices Standards

## **Priority: P0**

## Implementation Guidelines

### Sync Communication (REST)

- **Clients**: Use **Spring Cloud OpenFeign** or **Http Interfaces** (Spring 6).
- **Resilience**: Wrap calls with **Resilience4j** (Circuit Breaker).
- **Contracts**: Define DTOs in a **Shared Library** (Maven BOM).
- **Versioning**: Enforce **Semantic Versioning** on shared libs.

### Async Communication (Event-Driven)

- **Cloud Stream**: Use `java.util.function.Consumer<T>` composition.
- **Idempotency**: Consumers MUST handle duplicates (DB constraints).
- **Evolution**: Add fields only. Never rename/remove used fields.

## Anti-Patterns

- **Direct DB Access**: `**No Shared DB**: Use APIs/Events.`
- **Coupled Entities**: `**No Shared Entities**: Use DTOs.`
- **Dist. Monolith**: `**No Sync Chains**: Use Async.`

## References

- [Implementation Examples](references/implementation.md)

Overview

This skill codifies standards for building Spring Boot microservices with clear guidelines for synchronous (Feign/HTTP Interfaces) and asynchronous (Spring Cloud Stream) communication. It focuses on resilient client calls, event-driven consumers, and safe evolution of shared contracts to reduce coupling and operational risk. The guidance is framework- and practice-focused so agents can recommend consistent, maintainable designs.

How this skill works

The skill inspects service-to-service interaction patterns and enforces use of OpenFeign or Spring Http Interfaces for REST clients, wrapped with Resilience4j circuit breakers. For async messaging, it recommends Spring Cloud Stream function composition using java.util.function.Consumer<T> and mandates idempotent consumer behavior. It also checks for contract management: DTOs in a shared library and semantic versioning for shared artifacts.

When to use it

Designing new Spring Boot microservices that need reliable sync and async communication.
Refactoring existing services to remove direct DB sharing or tight entity coupling.
Setting up event-driven integrations where duplicate messages or schema evolution are concerns.
Enforcing team standards for client resilience and shared contract versioning.
Evaluating architecture choices to avoid distributed monolith anti-patterns.

Best practices

Use OpenFeign or Spring Http Interfaces for REST clients and wrap calls with Resilience4j circuit breakers and timeouts.
Place DTOs and common types in a versioned shared library (BOM) and apply semantic versioning for changes.
Implement Cloud Stream handlers as java.util.function.Consumer<T> and compose functions for modularity.
Ensure consumers are idempotent and rely on DB constraints or deduplication to tolerate duplicates.
Evolve event schemas by only adding fields; avoid renaming or removing fields that consumers rely on.
Avoid shared databases and shared entity models; communicate via APIs or events and use DTO translation layers.

Example use cases

A payments service calls an orders service via Feign with Resilience4j to prevent cascading failures.
An inventory service publishes stock-change events; multiple consumers implement idempotent handlers.
Migrating two services that previously shared a database to communicate via versioned DTOs and events.
Composing Cloud Stream functions to route and transform messages without tight coupling between services.

FAQ

Why prefer shared DTOs over shared entities?

DTOs decouple service boundaries, prevent schema leakage, and allow each service to evolve independently while keeping contracts explicit and versioned.

How should I handle schema changes for events?

Follow additive changes only: add optional fields, keep existing names and types, and bump the shared library version using semantic versioning so consumers can opt into new data safely.