Queries and the condition allowlist

Condition allowlist

• Only fields annotated @QueryField enter the WHERE clause; unannotated ones are ignored, so passing extra fields never changes query semantics.
• Available types: EQ / LIKE / GT / GE / LT / LE / IN / BETWEEN; ignoreEmpty skips empty values by default.
• A condition field must resolve to a real entity column, otherwise the first call throws — a typo must surface during development, not silently return empty in production.

Fuzzy search

LIKE escapes automatically: %, _ and the escape character itself, with an explicit ESCAPE declaration. Do not escape again in business code.

Sorting

• orderBy must be an entity property name or a real column name; it is allowlisted and an illegal value throws.
• When no sort is given, a descending primary-key sort is added so paging order stays stable (otherwise page two repeats page one's first row).
• Join queries use a separate sort allowlist (key is the field a caller may pass, value is the column name with table alias). The two are not interchangeable.

Pagination

• pageSize caps at 100; an out-of-range page number does not wrap around.
• Responses are uniformly PageResult<T>; never expose MyBatis-Plus Page<T> as an endpoint response (it leaks internal fields).
• Prefer the framework for single-table paging: no XML, no carrier class. Write SQL by hand only for multi-table joins, a custom count, or a sort key that is not expressible as an entity property.