Focus on tough problems and not on CRUD that the main focus of commons-rest. We @rocketbase.io develop many microservices and tried many tools and projects. All of them didn't matched our needs. By using for example spring-data-rest you loose flexibility when you leave the basic path or by using jHipster you have a full blown setup with many dependencies. Commons-rest focus on CRUD and leaves flexibility to you as developer. Additionally we've crafted a yeoman project and service generator in order to write less code :)
The implementation bases on spring-boot: mainly on spring-mvc and spring-data
We believe in separation of Entity and DTO. We go one step forward and separate also the DTO into Read (response structure) and Write (create/update structure). This has many advantages for example separation of concern and allow edit by reference id and response with object. Furthermore it improves readability.
Conversion between each object can be automatically generated with mapstruct see sample-project for details.
Features:
- basic DTOs as per example a missing PageableResult
- custom RuntimeExceptions, ExceptionHandler and BeanValidationExceptions
- abstract CRUD controller also for parent child situations
- abstract CRUD resources to consume REST-Services
- prodivded a project and service generator via yeoman
- provided a jwt security module that is simply pluggable name commons-auth
Within the wiki-pages you can find some explanations to the different classes, helpers and dtos.
This module provides some useful runtime exceptions like NotFoundException and basic DTO classes. Mainly ErrorResponse for rending details to error and also field-validation exceptions (this is handled a BeanValidationExceptionHandler provided by rest-server) and PageableResult to provide results in a paged wrapper. Additionally, you can find abstract implements of resources to consume REST-Services within java-code by use of RestTemplate and Jackson.
Containing ExceptionHandlers for common errors like BeanValidationExceptions or the custom NotFoundException. Abstract classes to implement CRUD SpringRestController. Also a parent child solution is provided.
Simple designed error pages for 400, 401, 403, 404 and 500 error-codes.
Library to build rest-clients + react-query hooks with custom annotations and converts.
| property | default | explanation |
|---|---|---|
| commons.openapi.generator.base-url | /api | used as prefix for alle urls |
| commons.openapi.generator.group-name | ModuleApi | client generator added all "methods" within one group |
| commons.openapi.generator.hook-folder | hooks | folder within zip |
| commons.openapi.generator.client-folder | clients | folder within zip |
| commons.openapi.generator.model-folder | model | folder within zip |
| commons.openapi.generator.model-create | true | should models get generated |
| commons.openapi.generator.model-imports | _ | |
| unset_ | list that will get added to model/index.ts | |
| commons.openapi.generator.default-stale-time | 2 | default value for infinite + query hook (when value is -1) |
Implementation for obfuscatedId interface introduced within the api. Uses hashids as library to obfuscate long ids.
| property | default | explanation |
|---|---|---|
| hashids.salt | salt for hashIds | |
| hashids.minHashLength | 8 | min length of hasid |
| hashids.alphabet | abcdefghijklmnopqrstuvwxyz1234567890 | alphabet of hashid (by default we've skipped uppercase) |
| hashids.handler.enabled | true | enable/disable ExceptionHandler for ObfuscatedDecodeException |
| hashids.invalid.allowed | false | ObfuscatedIdSupport will return NotFound in invalid case. When allowed invalid ObfuscatedId will get inject as Parameter text is available but id is null! |
Adds a RequestLoggingAspect that wraps around all RestController Mappings and loggs: method, path, parameter, duration...
GET /api/company ツ username 🕓 61 ms ⮐ find({}) ⮑ PageableResult(totalElements=100, totalPages=4, page=0, pageSize=25, content=[CompanyRead(id=5dc3...
Furthermore you can annotate a Service Method with @Loggable and get a duration tracking as well. It's only working on Services that are wrappable by aspect. So you can only use it on Services calls from other services - no internal calls within the same Service.
@Service
public class SampleService {
@SneakyThrows
@Loggable
public void exampleService(Instant startExecution) {
TimeUnit.SECONDS.sleep(2);
}
}exampleService(2019-11-07T12:19:08.800Z) ツ username 🕓 2 sec 9 ms
| property | default | explanation |
|---|---|---|
| commons.logging.mvc.enabled | true | in case you only want to use Loggable Method aspect - disable RestController aspect |
| commons.logging.trim | true | trim result |
| commons.logging.trimLength | 100 | trim after string length |
| commons.logging.duration | true | track duration |
| commons.logging.audit | true | when AuditorAware is present log value of |
| commons.logging.args | false | log each args.toString() with trimLength |
| commons.logging.result | false | log result.toString() with trimLength |
| commons.logging.query | true | add query parameter to url |
| commons.logging.logLevel | DEBUG | level to log a normal hit |
| commons.logging.errorLogLevel | WARN | level to log an error hit |
Normally the RequestLoggerAspect would log only the time of returning a Mono. If you would like to get the time for processing the request you need to create your own Aspect that could look like this.
@Aspect
public class FluxLogger extends AbstractRequestLogger {
public FluxLogger(AuditorAware auditorAware, LoggableConfig config) {
super(auditorAware, config);
}
@Around("execution(* *(..)) && @annotation(org.springframework.web.bind.annotation.RequestMapping)")
public Object wrapMethod(ProceedingJoinPoint point) throws Throwable {
Method method = ((MethodSignature) point.getSignature())
.getMethod();
return this.wrap(point, method);
}
private Object wrap(ProceedingJoinPoint point, Method method) throws Throwable {
long start = System.currentTimeMillis();
Logger log = getLog(point);
try {
Optional<?> currentAuditor = getAuditorAware().getCurrentAuditor();
Object result = point.proceed();
if (result instanceof Mono) {
Mono<?> requestMono = (Mono<?>) result;
Mono<? extends Tuple2<Long, ?>> elapsed = requestMono.elapsed();
if (isLogEnabled(log, getConfig().getLogLevel())) {
elapsed.subscribe(o -> {
Long elapsedTime = o.getT1();
afterSuccess(log, point, method, System.currentTimeMillis() - elapsedTime, result, currentAuditor);
});
}
if (isLogEnabled(log, getConfig().getErrorLogLevel())) {
requestMono.toFuture()
.exceptionally(throwable -> {
logError(point, getConfig(), start, log, throwable);
return null;
});
}
}
return result;
} catch (Throwable ex) {
logError(point, getConfig(), start, log, ex);
throw ex;
}
}
}Sample spring-boot application to demonstrate the use of the provided commons-rest libraries.
This module uses the auto configuration feature of spring-boot-starter so that all necessary beans will get configured automatically. Nevertheless you can customize the configuration by the following properties
| property | default | explanation |
|---|---|---|
| locale.resolver.enabled | true | enable/disable default configuration of the LocaleResolver |
| locale.resolver.default | en | |
| locale.resolver.supported | you can specify a comma separated list of locales | |
| handler.badRequest.enabled | true | enable/disable ExceptionHandler for BadRequestException |
| handler.notFound.enabled | true | enable/disable ExceptionHandler for NotFoundException |
| handler.beanValidation.enabled | true | enable/disable ExceptionHandler for MethodArgumentNotValidException (bean validation issues from spring-boot) |
| handler.insufficientPrivileges.enabled | true | enable/disable ExceptionHandler for InsufficientPrivilegesException |
Copyright (c) 2019 rocketbase.io
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.