Preboot Query

preboot-query

Moduł rozszerzający Spring Data JDBC o dynamiczne filtrowanie, sortowanie, paginację i projekcje. Generuje SQL w runtime na podstawie kryteriów — bez pisania custom queries. Optymalizowany pod PostgreSQL.

Zależność Maven

<dependency>
    <groupId>io.preboot</groupId>
    <artifactId>preboot-query</artifactId>
</dependency>

Wersje zarządzane przez preboot-bom — nie podawaj <version>.

Wymaga: preboot-core, preboot-exporters-api (transitive), spring-boot-starter-data-jdbc, postgresql. Opcjonalnie: spring-boot-starter-web (dla kontrolerów REST), springdoc-openapi (dla OpenAPI docs).

Szybki start

1. Zdefiniuj encję

@Table("orders")
@Data
public class Order {
    @Id
    private Long id;
    private String orderNumber;
    private BigDecimal amount;
    private String status;
    private LocalDateTime createdAt;

    @MappedCollection(idColumn = "order_id")
    private Set<OrderItem> orderItems = new HashSet<>();
}

2. Stwórz interfejs repozytorium

public interface OrderRepository extends FilterableRepository<Order, Long> {}

3. Zaimplementuj repozytorium

@Repository
class OrderRepositoryImpl extends FilterableFragmentImpl<Order, Long> {
    public OrderRepositoryImpl(FilterableFragmentContext context) {
        super(context, Order.class);
    }
}

4. Filtruj

SearchParams params = SearchParams.criteria(
    FilterCriteria.eq("status", "COMPLETED"),
    FilterCriteria.gt("amount", new BigDecimal("100"))
).build();

Page<Order> orders = orderRepository.findAll(params);

5. (Opcjonalnie) Wystaw REST API

@RestController
@RequestMapping("/api/orders")
public class OrderController extends CrudFilterableController<Order, Long> {
    public OrderController(OrderRepository repository) {
        super(repository);
    }
}

Gotowe endpointy: GET /{id}, POST /search, POST /find, POST /count, POST /, PUT /{id}, PATCH /{id}, DELETE /{id}.

Główne koncepty

Architektura

FilterableRepository<T, ID>
├── extends CrudRepository<T, ID>         — standardowe CRUD
└── extends FilterableFragment<T>          — dynamiczne filtrowanie
    ├── findAll(SearchParams)              → Page<T>
    ├── findAllAsStream(SearchParams)      → Stream<T>
    ├── findOne(SearchParams)              → Optional<T>
    ├── count(SearchParams)                → long
    ├── findAllProjectedBy(params, type)   → Page<P>
    └── findOneProjectedBy(params, type)   → Optional<P>

FilterableUuidRepository<T extends HasUuid, ID>
├── extends FilterableRepository<T, ID>
└── extends UuidRepository<T>              — findByUuid, existsByUuid, deleteByUuid

Kluczowe klasy

Hierarchia kontrolerów

FilterableController<T, ID>              — GET /{id}, POST /search, /find, /count, /export
└── CrudFilterableController<T, ID>      — + POST /, PUT /{id}, PATCH /{id}, DELETE /{id}

UuidFilterableController<T, ID>          — GET /{uuid}, POST /search, /find, /count, /export
└── CrudUuidFilterableController<T, ID>  — + POST /, PUT /{uuid}, PATCH /{uuid}, DELETE /{uuid}

Operatory filtrowania

Logiczne AND/OR

// OR
FilterCriteria.or(List.of(
    FilterCriteria.eq("status", "COMPLETED"),
    FilterCriteria.eq("status", "PENDING")
));

// AND (explicit)
FilterCriteria.and(List.of(
    FilterCriteria.eq("status", "COMPLETED"),
    FilterCriteria.gt("amount", 200)
));

// Domyślnie wiele kryteriów w SearchParams.criteria() = AND
SearchParams.criteria(
    FilterCriteria.eq("status", "COMPLETED"),   // AND
    FilterCriteria.gt("amount", 200)             // AND
).build();

Zależności od innych modułów PreBoot

• preboot-core (wymagane) — JsonMapper, utilities
• preboot-exporters-api (wymagane) — DataExporter interfejs dla eksportu danych
• preboot-securedata (opcjonalnie) — rozszerza o multi-tenant security

Typowe przepływy

Filtrowanie + paginacja + sortowanie

SearchParams params = SearchParams.builder()
    .page(0)
    .size(20)
    .sort(List.of(SortOrder.desc("amount"), SortOrder.asc("status")))
    .filters(List.of(
        FilterCriteria.eq("status", "COMPLETED"),
        FilterCriteria.gt("amount", new BigDecimal("100"))
    ))
    .build();

Page<Order> result = orderRepository.findAll(params);

Encja z UUID

@Table("orders")
public class Order implements HasUuid {
    @Id private Long id;
    private UUID uuid;
    // ... pola

    @Override public UUID getUuid() { return uuid; }
    @Override public void setUuid(UUID uuid) { this.uuid = uuid; }
}

public interface OrderRepository extends FilterableUuidRepository<Order, Long> {}

@Repository
class OrderRepositoryImpl extends FilterableUuidFragmentImpl<Order, Long> {
    public OrderRepositoryImpl(FilterableFragmentContext context) {
        super(context, Order.class);
    }
}

// Użycie:
Optional<Order> order = orderRepository.findByUuid(uuid);
orderRepository.deleteByUuid(uuid);

Projekcje z @Value (SpEL)

public interface OrderSummary {
    String getOrderNumber();
    BigDecimal getAmount();

    @Value("#{target.amount > 150 ? 'High Value' : 'Standard'}")
    String getValueCategory();
}

Page<OrderSummary> summaries = orderRepository.findAllProjectedBy(
    SearchParams.empty(), OrderSummary.class
);

REST API — JSON request

POST /api/orders/search
{
  "page": 0,
  "size": 20,
  "sort": [
    {"field": "amount", "direction": "DESC"}
  ],
  "filters": [
    {"field": "status", "operator": "eq", "value": "COMPLETED"},
    {"field": "amount", "operator": "gt", "value": 100}
  ]
}

Nested filtering (relacje)

SearchParams params = SearchParams.criteria(
    FilterCriteria.eq("orderItems.productCode", "PROD-A"),
    FilterCriteria.gt("orderItems.quantity", 3)
).build();

Page<Order> orders = orderRepository.findAll(params);

Database views

@Table("v_order_summary")
@Data
public class OrderSummaryView {
    @Id private Long id;
    @Column("order_number") private String orderNumber;
    private BigDecimal amount;
    private String status;
    @Column("item_count") private Long itemCount;
}

public interface OrderSummaryViewRepository extends FilterableRepository<OrderSummaryView, Long> {}

@Repository
class OrderSummaryViewRepositoryImpl extends FilterableFragmentImpl<OrderSummaryView, Long> {
    public OrderSummaryViewRepositoryImpl(FilterableFragmentContext context) {
        super(context, OrderSummaryView.class);
    }
}

Pułapki i częste błędy

1. Brak implementacji repozytorium — sam interfejs extends FilterableRepository nie wystarczy. Musisz stworzyć *Impl rozszerzający FilterableFragmentImpl. Nazwa klasy MUSI kończyć się na Impl i odpowiadać nazwie interfejsu.

2. @Immutable na encji widoku — NIE używaj @Immutable z Spring Data JDBC na encjach widoków. W Spring Data JDBC 4.0.0 powoduje to null we wszystkich polach.

3. Nazewnictwo kolumn w widokach — jeśli kolumna widoku ma alias inny niż snake_case pola Java, użyj @Column("alias"). Spring Data JDBC konwertuje camelCase → snake_case automatycznie.

4. like operator dodaje % automatycznie — FilterCriteria.like("name", "ORD") generuje ILIKE 'ORD%'. Nie dodawaj % sam.

5. UUID entity bez HasUuid — jeśli chcesz findByUuid(), encja MUSI implementować HasUuid, repo FilterableUuidRepository, impl FilterableUuidFragmentImpl.

6. Async EventPublisher z kontrolerami eksportu — asynchroniczny eksport wymaga QueryControllersPort — bez niego isAsyncExportSupported() zwraca false.

7. Max page size — domyślnie 100. Przekroczenie zwraca 400 Bad Request. Override getMaxPageSize() w kontrolerze jeśli potrzebujesz więcej.

8. Sort precedence — gdy podasz zarówno sortField/sortDirection jak i sort, sort wygrywa. sortField/sortDirection jest deprecated.

9. Brak FilterableFragmentContext beana — ten bean jest @Service i wymaga NamedParameterJdbcTemplate, SqlBuilder, RelationalMappingContext, JdbcConverter, ConversionService, JdbcAggregateTemplate, PropertyResolver w kontekście. Wszystkie są auto-konfigurowane przez Spring Boot.

10. between z null — FilterCriteria.between(field, null, to) rzuci IllegalArgumentException. Oba argumenty muszą być non-null.

Kiedy sięgnąć do references/

• api-reference.md — pełne sygnatury metod, parametry, wyjątki, hierarchia kontrolerów, hooki CRUD
• examples.md — kompletne przykłady: filtrowanie, OR/AND, projekcje, @AggregateReference, kontrolery REST, JSON requests, widoki bazodanowe, eksport, testowanie