Bean Searcher

Bean Searcher is a Java declarative search framework designed to simplify complex list retrieval. It allows clients to freely specify return fields, filter conditions, sort rules, and pagination via standard HTTP parameters in a single request.

Key Characteristics

• Declarative Search: Entities define the search boundaries, while client-provided parameters drive the query logic.
• Zero-Annotation Search: Single-table entities can be made searchable without any annotations.
• Framework Agnostic: It does not depend on a specific Web framework (e.g., Spring Boot, Solon, Grails, JFinal) or a specific ORM (e.g., MyBatis, Hibernate).
• Protocol Agnostic: It works with standard HTTP parameters (GET, POST, form submissions) and does not require a dedicated protocol like GraphQL.

The project is built using Vue 3.5 (Composition API), Vite 6, TypeScript 5.7, and Ant Design Vue 4.2. Key directories include:

• src/api/: Contains API request logic using native fetch and query parameter construction.
• src/components/: Reusable UI components like DataTable.vue (using a-table) and FilterCard.vue (search forms).
• src/types/: TypeScript definitions and constants for operators and column definitions.
• src/styles/: Global CSS styles.

The Label system is a result-enhancement component introduced in v4.4. It automatically fills specified fields in a SearchBean with human-readable labels based on ID values, enum values, or other field data. This process is often called dictionary translation.

It is designed to resolve foreign-key lookups and enum conversions without requiring complex SQL JOINs or manual post-processing in your application code. It is particularly useful for:

• Cross-Database Lookups in Microservices: When the source data and the reference data reside in different databases/services, making SQL JOINs impossible.
• Dictionary Table Optimization: Avoiding repeated JOINs on small dictionary tables by caching them in memory and using the label system instead.
• Enum Fields: Providing human-readable string representations for enum fields to the front end.

Field parameters are used for filtering query results and are derived from the Java field names in your entity class (not the database column names).

For a field named name, Bean Searcher automatically derives the following parameter patterns using a hyphen (-) as the default separator:

• name-{n}: The nth parameter value (e.g., name-0, name-1).
• name: Equivalent to name-0 (the 0th parameter value).
• name-op: The [field operator](#Field Operators) for the field (e.g., name-eq).
• name-ic: A flag indicating whether to ignore case (e.g., name-ic=true).

Note: If you change the separator via configuration, these patterns will update accordingly (e.g., name_op if the separator is _).

public class User {
    private String name;
    // Omit other..
}

Bean Searcher automatically ignores any fields in an entity class that are declared with the static or transient keywords. This is useful for constants or fields that should not participate in database mapping or search operations.

public class Address {
    public static String SUZHOU = "Suzhou City"; // Automatically ignored
    private String city;    // Not ignored
    private String street;  // Not ignored
    private transient fullAddress;          // Automatically ignored
    // Getter Setter ...
}

Bean Searcher is not an ORM. It is a complementary framework designed to fill the gap in complex list retrieval that ORMs like MyBatis or Hibernate often leave behind.

Bean Searcher handles only database queries (Read operations) and can coexist with any existing ORM in your project.

Field attributes are Java fields in your retrieval entity class that map to database table fields. They are used to carry query results in list queries and to generate WHERE or HAVING conditions based on field parameters.

By default, if you use @SearchBean(autoMapTo = "table_alias"), fields not annotated with @DbField are automatically mapped to that table alias. You can use @DbField("column_name") to explicitly map a field to a specific database column or a joined table column.

A SearchBean is an entity class that maps to a database table (or multiple tables). In Bean Searcher v3.x, you can often omit annotations. If no annotations are present, Bean Searcher treats the class as a single-table entity where field names map to database column names by default.

Example entity:

public class User {
    private Long id;
    private String name;
    private int age;
    // Getters and Setters...
}

public class User {             // By default, it maps to the user table.

    private Long id;            // By default, it maps to the id field.
    private String name;        // By default, it maps to the name field.
    private int age;           // By default, it maps to the age field.

    // Getter and Setter ...
}