Leia esta página em Português do Brasil
Requests-Common is a lightweight Java library that gives your services a shared language for dealing with incoming requests and outgoing responses. It ships with strongly typed envelopes, pagination helpers, credential handling, error contracts, and optional Spring Boot auto-configuration so that every microservice in your ecosystem can exchange data in a predictable way.
- Why Requests-Common?
- Installation
- Quick Start
- Core Building Blocks
- Spring Boot Auto-configuration
- End-to-end REST Example
- Building from Source
- License
- Contact
When every service in a distributed system invents its own request and response wrappers, you end up re-implementing the same features repeatedly (IDs, headers, pagination metadata, error payloads, etc.). Requests-Common centralizes those patterns so you can:
- share DTO contracts across JVM services without copy/paste;
- automatically enrich responses with metadata such as
responseId, payload size, and pagination totals;【F:src/main/java/dev/nishisan/requests/common/response/AbsResponse.java†L34-L114】 - attach credentials, trace IDs, and custom headers to every request in a consistent manner;【F:src/main/java/dev/nishisan/requests/common/request/AbsRequest.java†L30-L97】
- expose uniform error objects and HTTP statuses across your APIs.【F:src/main/java/dev/nishisan/requests/common/dto/ApiErrorDTO.java†L23-L78】【F:src/main/java/dev/nishisan/requests/common/exception/BasicException.java†L10-L90】
Add the dependency to your build tool. Replace 1.2.12 with the most recent release if necessary.
Maven
<dependency>
<groupId>dev.nishisan</groupId>
<artifactId>requests-common</artifactId>
<version>1.2.15</version>
</dependency>
Gradle (Kotlin DSL)
dependencies {
implementation("dev.nishisan:requests-common:1.2.15")
}
Gradle (Groovy DSL)
dependencies {
implementation 'dev.nishisan:requests-common:1.2.15'
}
The snippet below demonstrates the typical flow of modelling a product creation endpoint.
// 1. Define your payload
public record ProductDTO(String sku, String name, double price) {}
// 2. Wrap the payload in a request
public class CreateProductRequest extends AbsRequest<ProductDTO> {
public CreateProductRequest(ProductDTO payload) {
super(payload);
}
}
// 3. Wrap the payload in a response
public class ProductResponse extends AbsResponse<ProductDTO> {
public ProductResponse(ProductDTO payload) {
super(payload);
setStatusCode(201);
}
}
// 4. Use the envelopes inside your service
@Service
public class ProductService {
public ProductResponse create(CreateProductRequest request) {
// access metadata
var credentials = request.getUserCredential();
var traceId = request.getTraceId();
// perform your domain logic
ProductDTO saved = saveProduct(request.getPayload());
// build a standardized response
ProductResponse response = new ProductResponse(saved);
response.setSourceRequestId(request.getRequestId());
response.setTraceId(traceId);
response.addResponseHeader("X-Correlation-Id", traceId);
return response;
}
}
💡
AbsResponseautomatically generates aresponseIdand calculates payload metadata such as collection size or total pages forPage<?>objects.【F:src/main/java/dev/nishisan/requests/common/response/AbsResponse.java†L42-L101】
AbsRequest<T>implementsIRequest<T>and ships with fields forrequestId,traceId, payload, arbitrary headers, and a user credential object.【F:src/main/java/dev/nishisan/requests/common/request/AbsRequest.java†L30-L97】- Use
setRequestId,setTraceId, andaddRequestHeaderto pass metadata downstream; they are stored internally in a thread-safeConcurrentHashMapfor safe reuse across threads.【F:src/main/java/dev/nishisan/requests/common/request/AbsRequest.java†L30-L79】
AbsResponse<T>implementsIResponse<T>and is responsible for- generating a unique
responseIdwithUUID.randomUUID(); - keeping a
sourceRequestId,traceId, and HTTPstatusCode; - capturing payload size for
List,Map, andPagepayloads; - storing arbitrary response headers.【F:src/main/java/dev/nishisan/requests/common/response/AbsResponse.java†L34-L114】
- generating a unique
setStatusCodeis especially useful together with the Spring Boot advice, which will propagate it to the HTTP layer automatically.【F:src/main/java/dev/nishisan/requests/common/spring/servlet/ResponseStatusAdvice.java†L22-L72】
- Define your own credential classes by extending
AbsUserCredential<T>or reusingGenericUserCredentialwhen you just need an ID and optional opaque data.【F:src/main/java/dev/nishisan/requests/common/uc/AbsUserCredential.java†L22-L70】【F:src/main/java/dev/nishisan/requests/common/uc/GenericUserCredential.java†L17-L32】 - Attach them to a request via
request.setUserCredential(...)and retrieve them later to authorize operations.【F:src/main/java/dev/nishisan/requests/common/request/AbsRequest.java†L32-L97】
AbsPageableRequestcreates aPageableDTOpayload for you, so your controller only needs to extend it and pass the pagination parameters.【F:src/main/java/dev/nishisan/requests/common/request/AbsPageableRequest.java†L24-L38】PageableDTOstorespage,size,sort,direction, and an optional free-textquery, covering the majority of pagination use cases.【F:src/main/java/dev/nishisan/requests/common/dto/PageableDTO.java†L23-L94】
- Use
@RequiredFieldto mark DTO fields that must be present. You can optionally restrict values with nested@AllowedValuedeclarations (e.g., enum-like constraints).【F:src/main/java/dev/nishisan/requests/common/annotations/RequiredField.java†L1-L15】 - Because the annotation retention is
RUNTIME, you can reflect on it in service or validation layers to enforce custom rules.【F:src/main/java/dev/nishisan/requests/common/annotations/RequiredField.java†L5-L15】
- Extend
BasicExceptionfor domain-specific errors. It keeps a reference to the originalIRequest, a customizable HTTP status code, and a mutabledetailsmap that you can enrich fluently usingdetails(key, value)in your subclass.【F:src/main/java/dev/nishisan/requests/common/exception/BasicException.java†L10-L90】 - Serialize errors uniformly with
ApiErrorDTO, which carries the message, class name, status code, details, and optionally the request snapshot.【F:src/main/java/dev/nishisan/requests/common/dto/ApiErrorDTO.java†L23-L78】
Requests-Common provides an auto-configuration that registers ResponseStatusAdvice in servlet-based Spring Boot applications. When enabled, any controller method returning an AbsResponse (or throwing a BasicException) will have its HTTP status automatically synchronized with the value set inside the object.【F:src/main/java/dev/nishisan/requests/common/spring/servlet/ResponseStatusAdvice.java†L22-L72】【F:src/main/java/dev/nishisan/requests/common/spring/servlet/config/NishiRequestsCommonAutoConfiguration.java†L1-L22】
Enable it with the property below:
# application.properties
nishi.requests.common.enabled=true
Or in YAML:
# application.yml
nishi:
requests:
common:
enabled: true
Because the configuration is conditional on a servlet web application, you can safely add the dependency to libraries and non-web services without activating the advice.【F:src/main/java/dev/nishisan/requests/common/spring/servlet/config/NishiRequestsCommonAutoConfiguration.java†L5-L22】
The following controller illustrates how the pieces fit together in a Spring Boot project:
@RestController
@RequestMapping("/products")
public class ProductController {
private final ProductService service;
public ProductController(ProductService service) {
this.service = service;
}
@PostMapping
public ProductResponse create(@RequestBody ProductDTO dto,
@RequestHeader(value = "X-Trace-Id", required = false) String traceId) {
CreateProductRequest request = new CreateProductRequest(dto);
request.setRequestId(UUID.randomUUID().toString());
request.setTraceId(traceId);
request.setUserCredential(new GenericUserCredential("user-123"));
request.addRequestHeader("X-Trace-Id", traceId);
return service.create(request);
}
@GetMapping
public AbsResponse<Page<ProductDTO>> list(@RequestParam int page, @RequestParam int size) {
ListProductsRequest request = new ListProductsRequest(page, size);
AbsResponse<Page<ProductDTO>> response = service.list(request);
response.setStatusCode(200);
return response;
}
@GetMapping("/{sku}")
public ProductResponse findBySku(@PathVariable String sku) throws ProductNotFoundException {
return service.findBySku(sku);
}
}
Error handling with a custom BasicException subclass:
public class ProductNotFoundException extends BasicException {
public ProductNotFoundException(String sku, IRequest<?> request) {
super("Product not found", request, 404, Map.of("sku", sku));
}
@Override
public ProductNotFoundException details(String key, Object value) {
addDetail(key, value);
return this;
}
}
@RestControllerAdvice
public class ProductExceptionHandler {
@ExceptionHandler(ProductNotFoundException.class)
public ResponseEntity<ApiErrorDTO> handle(ProductNotFoundException ex) {
ApiErrorDTO error = new ApiErrorDTO();
error.setMsg(ex.getMessage());
error.setStatusCode(ex.getStatusCode());
error.setClassName(ex.getClass().getName());
error.setDetails(ex.details());
error.setRequest(ex.getRequest());
return ResponseEntity.status(ex.getStatusCode()).body(error);
}
}
With auto-configuration enabled, ResponseStatusAdvice ensures the HTTP status reflects the value set on the AbsResponse or BasicException, so there is no need to set it manually in each controller.【F:src/main/java/dev/nishisan/requests/common/spring/servlet/ResponseStatusAdvice.java†L22-L72】
Clone the repository and run:
mvn clean package
The project targets Java 21 and Spring Boot 3.5, so ensure those toolchains are available in your environment.【F:pom.xml†L40-L48】
This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.
Questions or feedback? Open an issue or reach out via github@nishisan.dev.