### Solon Project Dependency

Source: https://bs.zhxu.cn/guide/start/install

This dependency is specifically for Solon projects, offering similar functionality to the SpringBoot starter.

```groovy
implementation 'cn.zhxu:bean-searcher-solon-plugin:4.4.2'
```

--------------------------------

### Basic Search Implementation (Java)

Source: https://bs.zhxu.cn/guide/start/use

Example of implementing a user search interface using MapSearcher with one line of code.

```java
@RestController
@RequestMapping("/user")
public class UserController {
    @Autowired
    private MapSearcher mapSearcher; // Inject the BeanSearcher retriever

    @GetMapping("/index")
    public SearchResult<Map<String, Object>> index(HttpServletRequest request) {
        // One line of code to implement a user search interface
        return mapSearcher.search(User.class, MapUtils.flat(request.getParameterMap()));
    }
}
```

--------------------------------

### Arbitrary Java Project Setup

Source: https://bs.zhxu.cn/guide/start/integration

Demonstrates how to build `MapSearcher` and `BeanSearcher` instances in any Java project at startup using `SearcherBuilder`. It shows how to configure the SQL executor with default and named data sources.

```java
// 使用默认数据源
DefaultSqlExecutor sqlExecutor = new DefaultSqlExecutor(getDefaultDataSource());
// sqlExecutor.addDataSource("slave1", getSlave1DataSource());  // 添加具名数据源 slave1
// sqlExecutor.addDataSource("slave2", getSlave2DataSource());  // 添加具名数据源 slave2
// 构建 Map 检索器
MapSearcher mapSearcher = SearcherBuilder.mapSearcher()
        .sqlExecutor(sqlExecutor)
        .build();
// 构建 Bean 检索器
BeanSearcher beanSearcher = SearcherBuilder.beanSearcher()
        .sqlExecutor(sqlExecutor)
        .build();
```

--------------------------------

### No-Parameter Request Response (JSON)

Source: https://bs.zhxu.cn/guide/start/use

Example JSON response for a no-parameter GET /user/index request.

```json
{
    "dataList": [
        { "id": 1, "name": "Jack", "age": 25 },
    ],
    "totalCount": 100
}
```

--------------------------------

### Solon Plugin Maven Dependency

Source: https://bs.zhxu.cn/guide/start/install

This snippet provides the Maven dependency for the Bean Searcher Solon plugin, which offers similar functionality to the SpringBoot starter but is specifically for Solon projects.

```xml
<dependency>
    <groupId>cn.zhxu</groupId>
    <artifactId>bean-searcher-solon-plugin</artifactId>
    <version>4.4.2</version>
</dependency>
```

--------------------------------

### SpringBoot/Grails Project Dependency

Source: https://bs.zhxu.cn/guide/start/install

This dependency is for SpringBoot or Grails projects. It provides the starter integration for the Bean Searcher library.

```groovy
implementation 'cn.zhxu:bean-searcher-boot-starter:4.4.2'
```

--------------------------------

### Bean Searcher Integration

Source: https://bs.zhxu.cn/guide/info/versions

Guides on how to integrate Bean Searcher into your Java projects, covering different application scenarios and setup procedures.

```Java
/*
 * Integration Guide for Bean Searcher
 *
 * This section provides instructions on how to integrate Bean Searcher into various Java projects.
 * It covers common integration patterns and configurations.
 */

// Example: Maven Dependency
/*
<dependency>
    <groupId>com.troyzhxu</groupId>
    <artifactId>bean-searcher</artifactId>
    <version>...</version>
</dependency>
*/

// Example: Spring Boot Integration (Conceptual)
/*
@Configuration
public class BeanSearcherConfig {

    @Bean
    public Searcher searcher() {
        // Configure and return your Searcher instance
        return Searcher.create("com.your.entity.package");
    }
}
*/
```

--------------------------------

### Paginated Request Response (JSON)

Source: https://bs.zhxu.cn/guide/start/use

Example JSON response structure for a paginated request (e.g., GET /user/index?page=2&size=10).

```json
{
    "dataList": [
        { "id": 1, "name": "Jack", "age": 25 },
    ],
    "totalCount": 100
}
```

--------------------------------

### Core Bean Searcher Dependency

Source: https://bs.zhxu.cn/guide/start/install

This is the core dependency for the Bean Searcher library, usable in any Java framework.

```groovy
implementation 'cn.zhxu:bean-searcher:4.4.2'
```

--------------------------------

### 配置 Bean Searcher SQL 日志级别 (application.properties)

Source: https://bs.zhxu.cn/guide/start/use

在 SpringBoot 项目的 `application.properties` 文件中，通过 `logging.level.cn.zhxu.bs` 设置日志级别为 `DEBUG`，可以打印所有 SQL 日志。

```yml
logging.level.cn.zhxu.bs: DEBUG
```

--------------------------------

### 配置 Bean Searcher SQL 日志级别 (application.yml)

Source: https://bs.zhxu.cn/guide/start/use

在 SpringBoot 项目的 `application.yml` 文件中，将 `cn.zhxu.bs` 的日志级别设置为 `DEBUG`，可以打印所有 SQL 日志（包括慢 SQL 和普通 SQL）。设置为 `INFO` 或 `WARN` 则只打印慢 SQL 日志。

```yml
logging:
  level:
    cn.zhxu.bs: DEBUG
```

--------------------------------

### Bean Searcher Integration

Source: https://bs.zhxu.cn/guide/start/use

Instructions on how to integrate Bean Searcher into a Java project. This typically involves adding dependencies and basic configuration.

```Java
// Example Maven dependency
<dependency>
    <groupId>com.troyzhxu</groupId>
    <artifactId>bean-searcher</artifactId>
    <version>4.4.2</version>
</dependency>

// Example Spring Boot integration (conceptual)
@Configuration
public class BeanSearcherConfig {

    @Bean
    public Searcher searcher(DataSource dataSource) {
        // Basic configuration with a DataSource
        return Searcher.builder(dataSource).build();
    }
}
```

--------------------------------

### Run Bean Searcher Spring Boot Demo

Source: https://bs.zhxu.cn/guide/info/bean-searcher

This snippet demonstrates how to navigate to the Spring Boot demo directory and run the application using Maven. This is the second step in the demo setup.

```bash
> cd bean-searcher/bean-searcher-demos/bs-demo-springboot
> mvn spring-boot:run
```

--------------------------------

### Solon Project Integration

Source: https://bs.zhxu.cn/guide/start/integration

Information on integrating Bean Searcher with Solon projects. It requires adding the `bean-searcher-solon-plugin` dependency and is compatible with Solon v2.2.1 and above. The plugin offers similar configuration options to `bean-searcher-boot-starter`.

```text
Add `bean-searcher-solon-plugin` dependency.
Supports Solon v2.2.1 and above.
Provides similar configuration options to `bean-searcher-boot-starter`.
```

--------------------------------

### SpringBoot/Grails Maven Dependency

Source: https://bs.zhxu.cn/guide/start/install

This snippet shows the Maven dependency for integrating Bean Searcher with SpringBoot or Grails projects. It includes the group ID, artifact ID, and version for the starter dependency.

```xml
<dependency>
    <groupId>cn.zhxu</groupId>
    <artifactId>bean-searcher-boot-starter</artifactId>
    <version>4.4.2</version>
</dependency>
```

--------------------------------

### Bean Searcher 忽略大小写查询示例

Source: https://bs.zhxu.cn/guide/start/use

通过在请求参数中添加 '-ic' 后缀，可以实现对字段的忽略大小写查询。例如，`name-ic=true` 表示对 'name' 字段进行忽略大小写匹配。

```APIDOC
GET /user/index?name=Jack&name-ic=true

返回结果：结构同 **（1）** （但只返回 name 等于 Jack (忽略大小写) 的数据，`ic` 是 `IgnoreCase` 的缩写）

TIP
参数名 `name-ic` 中的后缀 `-ic` 可自定义，该参数可与其它的参数组合使用，比如这里检索的是 name 等于 Jack 时忽略大小写，但同样适用于检索 name 已 Jack 开头或结尾时忽略大小写。
```

--------------------------------

### URL Parameter Example

Source: https://bs.zhxu.cn/guide/param/group

Demonstrates how to structure query parameters for logical grouping when passed as URL parameters.

```properties
properties
?name=John&age=30&city=NewYork&gexpr=A|B
?A.name=John&A.age=30&B.city=NewYork&gexpr=A|B
```

--------------------------------

### Simplified Search Implementation (Java)

Source: https://bs.zhxu.cn/guide/start/use

Further simplified search implementation when automatic request parameter reception is configured.

```java
@RestController
@RequestMapping("/user")
public class UserController {
    @Autowired
    private MapSearcher mapSearcher; // Inject the BeanSearcher retriever

    @GetMapping("/index")
    public SearchResult<Map<String, Object>> index() {
        // One line of code to implement a user search interface
        return mapSearcher.search(User.class);
    }
}
```

--------------------------------

### Other Frameworks Java Configuration

Source: https://bs.zhxu.cn/guide/bean/aignore

Java-based configuration for Bean Searcher in frameworks other than Spring Boot. This example shows programmatic setup of `DefaultDbMapping` and `MapSearcher`.

```java
DefaultDbMapping dbMapping = new DefaultDbMapping();
dbMapping.setTablePrefix("t_");     // 表名前缀
dbMapping.setUpperCase(false);      // 是否大写
dbMapping.setUnderlineCase(true);   // 是否驼峰转小写下划线
MapSearcher mapSearcher = SearcherBuilder.mapSearcher()
        // 省略其它配置
        .metaResolver(new DefaultMetaResolver(dbMapping))   // BeanSearcher 检索器也同此配置
        .build();
```

--------------------------------

### Search Parameter Handling

Source: https://bs.zhxu.cn/guide/start/use

Documentation on how to define and use search parameters, including pagination, sorting, field selection, custom SQL conditions, and logical grouping.

```Java
// Example Search Parameters
public class UserQueryParam {
    private PageParam page;
    private SortParam sort;
    private List<FieldParam> fields;
    private String username;

    // Getters and Setters...
}

// Example usage with Searcher (conceptual)
Searcher searcher = ...;
UserQueryParam params = new UserQueryParam();
params.setUsername("john_doe");
params.setPage(new PageParam(1, 10)); // Page 1, 10 items per page

List<User> users = searcher.search(User.class, params);

```

--------------------------------

### Grails Project Configuration (Groovy)

Source: https://bs.zhxu.cn/guide/start/integration

Configuration for Grails projects, defining the necessary beans in `resources.groovy`. It includes SQL executor, BeanSearcher, and MapSearcher.

```groovy
import cn.zhxu.bs.implement.DefaultSqlExecutor
import cn.zhxu.bs.implement.DefaultBeanSearcher
import cn.zhxu.bs.implement.DefaultMapSearchersqlExecutor(DefaultSqlExecutor) {
    dataSource = ref('dataSource')
}
// 声明 BeanSearcher 检索器，它查询的结果是 SearchBean 泛型对象
beanSearcher(DefaultBeanSearcher) {
    sqlExecutor = ref('sqlExecutor')
}
// 声明 MapSearcher 检索器，它查询的结果是 Map 对象
mapSearcher(DefaultMapSearcher) {
    sqlExecutor = ref('sqlExecutor')
}
```

--------------------------------

### Parameter Builder Example

Source: https://bs.zhxu.cn/guide/param/group

Illustrates using a parameter builder to construct query parameters for logical grouping in Java.

```java
import com.ejlchina.searcher.param.GroupExpression;
import com.ejlchina.searcher.param.ParamGroup;
import com.ejlchina.searcher.param.QueryParam;

// ...

QueryParam param = new QueryParam();

// Group A
ParamGroup groupA = new ParamGroup("A");
groupA.addParam("name", "John");
groupA.addParam("age", 30);

// Group B
ParamGroup groupB = new ParamGroup("B");
groupB.addParam("city", "NewYork");

// Combine groups with OR
GroupExpression gexpr = new GroupExpression();
gexpr.add("A").or("B");

param.addGroup(groupA);
param.addGroup(groupB);
param.setGexpr(gexpr);

// Now param can be used for searching.
```

--------------------------------

### Bean Searcher Core Maven Dependency

Source: https://bs.zhxu.cn/guide/start/install

This snippet shows the core Bean Searcher Maven dependency, which can be used in any Java framework. It is the fundamental dependency for utilizing Bean Searcher's features.

```xml
<dependency>
    <groupId>cn.zhxu</groupId>
    <artifactId>bean-searcher</artifactId>
    <version>4.4.2</version>
</dependency>
```

--------------------------------

### Advanced Features: Filters and Converters

Source: https://bs.zhxu.cn/guide/start/use

Explains how to use parameter and result filters, as well as field and parameter converters to customize data processing and transformation.

```Java
// Example Filter (conceptual)
public class SensitiveDataFilter implements ParamFilter {
    @Override
    public void onFilter(ParamContext context) {
        // Mask sensitive fields
        if (context.getField().equals("email")) {
            context.setValue("*****");
        }
    }
}

// Example Converter (conceptual)
public class DateFormatConverter implements FieldConverter {
    @Override
    public Object convert(Object value, String fieldName) {
        if (value instanceof java.util.Date) {
            return new SimpleDateFormat("yyyy-MM-dd").format((java.util.Date) value);
        }
        return value;
    }
}
```

--------------------------------

### Spring MVC Project Configuration (XML)

Source: https://bs.zhxu.cn/guide/start/integration

Configuration for traditional Spring MVC projects using XML. It sets up the SQL executor and the BeanSearcher/MapSearcher beans.

```xml
<bean id="sqlExecutor"
        class="cn.zhxu.bs.implement.DefaultSqlExecutor"
        p:dataSource-ref="dataSource" />
<!-- 声明 BeanSearcher 检索器，它查询的结果是 SearchBean 泛型对象 -->
<bean id="beanSearcher"
        class="cn.zhxu.bs.implement.DefaultBeanSearcher"
        p:sqlExecutor-ref="sqlExecutor" />
<!-- 声明 MapSearcher 检索器，它查询的结果是 Map 对象 -->
<bean id="mapSearcher"
        class="cn.zhxu.bs.implement.DefaultMapSearcher"
        p:sqlExecutor-ref="sqlExecutor" />
```

--------------------------------

### 非 Boot 的 Spring 项目配置 SqlInterceptor

Source: https://bs.zhxu.cn/guide/advance/interceptor

在非 Boot 的 Spring 项目中，通过 XML 配置将 SqlInterceptor 添加到 DefaultMapSearcher 的 interceptors 列表中。这种方式适用于传统的 Spring XML 配置。

```xml
<bean id="mapSearcher" class="cn.zhxu.bs.implement.DefaultMapSearcher">
    <!-- 省略其它属性配置，BeanSearcher 检索器也同此配置 -->
    <property name="interceptors">
        <list>
            <bean class="com.example.MyFitstSqlInterceptor" />
            <bean class="com.example.MySecondSqlInterceptor" />
        </list>
    </property>
</bean>
```

--------------------------------

### SQL Interceptor and Dialect

Source: https://bs.zhxu.cn/guide/start/use

Details on implementing SQL interceptors for logging or modifying SQL statements, and configuring SQL dialects for different database systems.

```Java
// Example SQL Interceptor (conceptual)
public class LoggingInterceptor implements SqlInterceptor {
    @Override
    public void onQuery(QueryContext context) {
        System.out.println("Executing SQL: " + context.getSql());
    }
}

// Example Dialect Configuration (conceptual)
Searcher searcher = Searcher.builder(dataSource)
    .dialect(new MySqlDialect()) // Or OracleDialect, PostgreSQLDialect, etc.
    .build();
```

--------------------------------

### Commonly Owned Methods

Source: https://bs.zhxu.cn/guide/start/use

Methods available for both MapSearcher and BeanSearcher for data querying and aggregation.

```APIDOC
searchCount(Class<T> beanClass, Map<String, Object> params): Number
  - Queries the total number of data entries matching the specified conditions.

searchSum(Class<T> beanClass, Map<String, Object> params, String field): Number
  - Queries the statistical value of a specific field for data matching the specified conditions.

searchSum(Class<T> beanClass, Map<String, Object> params, String[] fields): Number[]
  - Queries the statistical values of multiple fields for data matching the specified conditions.

Parameters:
  - beanClass: The class of the entity to query.
  - params: A collection of conditions including field filtering, pagination, and sorting.
```

--------------------------------

### 其他项目配置 SqlInterceptor

Source: https://bs.zhxu.cn/guide/advance/interceptor

在非 Spring Boot 或 Grails 的其他项目中，可以使用 SearcherBuilder 来构建 MapSearcher，并通过 addInterceptor 方法添加 SqlInterceptor。这种方式提供了更灵活的配置选项。

```java
MapSearcher mapSearcher = SearcherBuilder.mapSearcher()
        // 省略其它属性配置，BeanSearcher 检索器也同此配置
        .addInterceptor(new MyFitstSqlInterceptor())
        .addInterceptor(new MySecondSqlInterceptor())
        .build();
```

--------------------------------

### SpringBoot/Grails 项目配置 SqlInterceptor

Source: https://bs.zhxu.cn/guide/advance/interceptor

在 SpringBoot 或 Grails 项目中，通过将 SqlInterceptor 实现类声明为 Bean 来配置。这使得 Bean Searcher 能够自动发现并使用自定义的拦截器。

```java
@Bean
public SqlInterceptor myFitstSqlInterceptor() {
    return new MyFitstSqlInterceptor();
}
@Bean
public SqlInterceptor mySecondSqlInterceptor() {
    return new MySecondSqlInterceptor();
}
```

--------------------------------

### Entity Class Configuration

Source: https://bs.zhxu.cn/guide/start/use

Details on configuring entity classes for Bean Searcher, including concepts, handling multi-table relationships, and various annotation options for fields and parameters.

```Java
// Example Entity Class
public class User {
    private Long id;
    private String username;
    private String email;

    // Getters and Setters...
}

// Example with multi-table association (conceptual)
@Table("users")
public class UserWithProfile {
    private Long id;
    private String username;

    @Join("user_id") // Foreign key relationship
    private UserProfile profile;

    // Getters and Setters...
}
```

--------------------------------

### Configuring ParamResolver with Custom Filters

Source: https://bs.zhxu.cn/guide/advance/safe

Provides an example of how to configure a custom ParamResolver with multiple ParamFilters in projects not using the starter dependencies. This allows for advanced parameter processing and filtering.

```java
DefaultParamResolver paramResolver = new DefaultParamResolver();
// 添加参数过滤器
paramResolver.setParamFilters(new ParamFilter[] { 
    new MyParamFilter1(),
    new MyParamFilter2(),
});
// 构建 Map 检索器
MapSearcher mapSearcher = SearcherBuilder.mapSearcher()
        // 省略其它配置
        .paramResolver(paramResolver)   // BeanSearcher 检索器也同此配置
        .build();
```

--------------------------------

### Root Group Parameter Example

Source: https://bs.zhxu.cn/guide/param/group

Demonstrates the use of the root group parameter '$' for defining conditions that are always combined with the 'gexpr' using a logical AND. It shows how to set a parameter within the root group.

```properties
$.age = 20
```

--------------------------------

### Configure Dialect in Non-Boot Spring Projects (XML)

Source: https://bs.zhxu.cn/guide/advance/dialect

Provides an XML configuration example for setting up Bean Searcher dialects in traditional Spring projects. It includes defining the dialect bean, operator pool, parameter resolver, SQL resolver, and the map searcher itself.

```xml
<!-- Define Oracle dialect -->
<bean id="dialect" class="cn.zhxu.bs.dialect.MyDialect" />
<!-- v3.3+ requires operator pool configuration -->
<bean id="fieldOpPool" class="cn.zhxu.bs.FieldOpPool"
    p:dialect-ref="dialect" />
<bean id="paramResolver" class="cn.zhxu.bs.implement.DefaultParamResolver"
    p:fieldOpPool-ref="fieldOpPool" />
<bean id="sqlResolver" class="cn.zhxu.bs.implement.DefaultSqlResolver"
    p:dialect-ref="dialect" />
<bean id="mapSearcher" class="cn.zhxu.bs.implement.DefaultMapSearcher">
    <!-- Omit other property configurations, BeanSearcher searcher is configured similarly -->
    <property name="paramResolver" ref="paramResolver" />
    <property name="sqlResolver" ref="sqlResolver" />
</bean>
```

--------------------------------

### Spring Boot / Grails Integration

Source: https://bs.zhxu.cn/guide/start/integration

Integrates Bean Searcher into Spring Boot and Grails projects by adding the `bean-searcher-boot-starter` dependency. For Grails, specific configurations are needed to ignore certain runtime-added properties.

```java
<!-- Add this dependency for Spring Boot/Grails integration -->
<dependency>
    <groupId>com.github.troyzhxu</groupId>
    <artifactId>bean-searcher-boot-starter</artifactId>
    <version>LATEST_VERSION</version>
</dependency>
```

--------------------------------

### API Field Filtering: Start With (SW) and End With (EW)

Source: https://bs.zhxu.cn/guide/start/use

Explains how to filter string fields based on whether they start with (sw) or end with (ew) a specified string. These operators are useful for prefix and suffix matching. The '-op' suffix can be customized.

```APIDOC
GET /user/index?name=Jack&name-op=sw

Description: Returns user data where the 'name' field starts with 'Jack'.

GET /user/index?name=Jack&name-op=ew

Description: Returns user data where the 'name' field ends with 'Jack'.
```

--------------------------------

### Bean Searcher Boot Starter v3.4 Configuration

Source: https://bs.zhxu.cn/guide/info/versions

Details new configuration options for Bean Searcher Boot Starter in v3.4, including global ignore fields and the parameter name for ordering.

```Properties
bean-searcher.sql.default-mapping.ignore-fields
bean-searcher.params.order-by
```

--------------------------------

### Entity Class Definition (Java)

Source: https://bs.zhxu.cn/guide/start/use

Example of a default entity class (SearchBean) in Bean Searcher, mapping to a database table.

```java
public class User {
    // Default mapping to user table
    private Long id;            // Default mapping to id field
    private String name;        // Default mapping to name field
    private int age;            // Default mapping to age field
    // Getter and Setter ...
}
```

--------------------------------

### Clone Bean Searcher Demo Repository

Source: https://bs.zhxu.cn/guide/info/bean-searcher

This snippet shows how to clone the Bean Searcher demo repository from GitHub using Git. This is the first step to setting up and running the demo.

```bash
> git clone https://github.com/troyzhxu/bean-searcher.git
```

--------------------------------

### Bean Searcher Boot Starter v3.5 Configuration

Source: https://bs.zhxu.cn/guide/info/versions

Explains new configuration options for Bean Searcher Boot Starter in v3.5, related to parameter grouping, expression caching, separators, and TimeFieldConvertor.

```Properties
bean-searcher.params.group.enable=true
bean-searcher.params.group.expr-name=gexpr
bean-searcher.params.group.expr-cache-size=50
bean-searcher.params.group.separator=.
bean-searcher.field-convertor.use-time=true
```

--------------------------------

### Bean Searcher Boot Starter v3.7.1 Configuration

Source: https://bs.zhxu.cn/guide/info/versions

Configuration options for Bean Searcher Boot Starter in v3.7.1, including settings for slow SQL thresholds, default mapping style, enum conversion behavior, and support for custom `SlowListener` beans.

```properties
Added `bean-searcher.sql.slow-sql-threshold` configuration key for slow SQL threshold (in milliseconds), defaults to 500.
Added `bean-searcher.sql.default-mapping.underline-case` configuration key to enable camelCase to snake_case conversion for automatic mapping, defaults to `true`.
Added `bean-searcher.field-convertor.enum-fail-on-error` configuration key to control error reporting on enum conversion failures, defaults to `true`.
Added `bean-searcher.field-convertor.enum-ignore-case` configuration key for case-insensitive enum string matching, defaults to `false`.
Supports configuring a `SqlExecutor.SlowListener` Spring Bean to listen for slow SQL.
Supports configuring `bean-searcher.sql.dialect` to `SqlServer` for using Sql Server dialect.
Optimized: Adding custom parameter filters does not overwrite built-in parameter filters (since v3.7.1).
Upgraded `spring-boot` to v2.6.8.
```

--------------------------------

### Bean Searcher Boot Starter Configuration

Source: https://bs.zhxu.cn/guide/info/versions

Details new configuration options for parameter merging, filter enablement, and timezone settings for DateTimeParamConvertor.

```APIDOC
bean-searcher.params.group.mergeable: Boolean - Specifies if group expressions are mergeable. Default: true.
bean-searcher.params.filter.use-size-limit: Boolean - Enables SizeLimitParamFilter. Default: true.
bean-searcher.params.filter.use-array-value: Boolean - Enables ArrayValueParamFilter. Default: true.
bean-searcher.params.filter.use-suffix-op: Boolean - Enables SuffixOpParamFilter. Default: false.
bean-searcher.params.filter.use-json-array: Boolean - Enables JsonArrayParamFilter. Default: false.
bean-searcher.params.convertor.zone-id: String - Configures the timezone for DateTimeParamConvertor. (since v4.3.2)

New Components:
- SpringSqlExecutor: Supports Spring transactions and is used by default (since v4.3.2).
- Custom JoinParaSerializer: Can be provided as a Bean.
```

--------------------------------

### Bean Searcher Boot Starter Configuration

Source: https://bs.zhxu.cn/guide/info/versions

Configuration options for Bean Searcher Boot Starter, including enabling IndexArrayParamFilter and enabling automatic configuration for Bean Searcher Label.

```APIDOC
bean-searcher.params.filter.use-index-array: boolean
  - Description: Controls whether to enable IndexArrayParamFilter.
  - Default: false

bean-searcher.label.auto-configuration: boolean
  - Description: Enables automatic configuration for Bean Searcher Label.
  - Default: true (assumed)

```

--------------------------------

### Bean Searcher Boot Starter v4.2 Configuration

Source: https://bs.zhxu.cn/guide/info/versions

Outlines new configuration options for Bean Searcher Boot Starter in v4.2. Focuses on enabling dynamic dialects, mapping data sources to dialects, automatic enum parameter conversion, and controlling parameter error handling.

```properties
bean-searcher.sql.dialect-dynamic=false

# When dynamic data source is enabled, map data sources and dialects via DataSourceDialect Bean injection

# Auto-configures EnumParamConvertor

bean-searcher.params.fail-on-error=false
bean-searcher.params.convertor.date-target=
bean-searcher.params.convertor.date-time-target=
bean-searcher.params.convertor.time-target=
```

--------------------------------

### API Field Filtering: Between (BT)

Source: https://bs.zhxu.cn/guide/start/use

Explains how to filter data within a specific range using the 'bt' (Between) operator. This requires specifying a start and end value for the field. The syntax uses indexed parameters like 'field-0' and 'field-1'. The '-op' suffix can be customized.

```APIDOC
GET /user/index?age-0=20&age-1=30&age-op=bt

Description: Returns user data where 'age' is between 20 and 30 (inclusive). The syntax 'age=20' is a shorthand for 'age-0=20'.
```

--------------------------------

### Bean Searcher Boot Starter v3.6 Configuration

Source: https://bs.zhxu.cn/guide/info/versions

Details new configuration options for Bean Searcher Boot Starter in v3.6, including default mapping inheritance, sort types, result filter integration, PostgreSQL dialect, and field convertor settings.

```Properties
bean-searcher.sql.default-mapping.inherit-type=ALL
bean-searcher.sql.default-mapping.sort-type=ALLOW_PARAM
Supports `Spring Bean` for adding `ResultFilter` to `BeanSearcher` and `MapSearcher`.
bean-searcher.sql.dialect=PostgreSQL or PgSQL
bean-searcher.field-convertor.use-b2-m=false
bean-searcher.field-convertor.use-bool-num=true (since v3.6.1)
```

--------------------------------

### Java Entity Example

Source: https://bs.zhxu.cn/guide/param/field

An example of a Java User entity class used to illustrate field parameter derivation. The 'name' field is used as a basis for generating various search parameters.

```java
public class User {
    private String name;
    // 省略其它..
}
```

--------------------------------

### Data Scope Rule Example: Key Tables

Source: https://bs.zhxu.cn/guide/usage/datascope

Defines the key tables and fields used in the data scope rule example. This includes the 'dept' table for department information, the 'user' table for user details, and the 'order' table as a sample business data table.

```APIDOC
Table: dept
  Fields:
    id: Department ID
    parent_id: Parent Department ID

Table: user
  Fields:
    id: User ID
    dept_id: Department ID of the user

Table: order (Business Data Table)
  Fields:
    id: Order ID
    owner_id: Owner ID
    dept_id: Department ID of the order
```

--------------------------------

### Bean Searcher Boot Starter v3.8.2 Configuration

Source: https://bs.zhxu.cn/guide/info/versions

Configuration options for Bean Searcher Boot Starter in v3.8.2, including support for custom `ParamResolver.Convertor` beans and new configuration properties for parameter filtering, grouping, and pagination.

```properties
Supports configuring a `ParamResolver.Convertor` Spring Bean for extended parameter value conversion.
Removed `bean-searcher.sql.use-date-value-corrector` configuration item.
Upgraded `spring-boot` to v2.6.9.
Added `bean-searcher.params.filter.max-para-map-size` configuration item, default `150` (since v3.8.1).
Added `bean-searcher.params.group.max-expr-length` configuration item, default `50` (since v3.8.1).
Added `bean-searcher.params.pagination.max-allowed-offset` configuration item, default `20000` (since v3.8.1).
Added configuration item validation: `bean-searcher.params.pagination.default-size` cannot be larger than `bean-searcher.params.pagination.max-allowed-size`, and both must be greater than 0 (since v3.8.1).
Optimized: Standardized exception messages to be entirely in English (since v3.8.1).
```

--------------------------------

### MapSearcher Methods

Source: https://bs.zhxu.cn/guide/start/use

Methods specific to MapSearcher for retrieving data as Map objects.

```APIDOC
search(Class<T> beanClass, Map<String, Object> params): SearchResult<Map<String, Object>> 
  - Performs a paginated search for data lists and total count matching the specified conditions.

search(Class<T> beanClass, Map<String, Object> params, String[] summaryFields): SearchResult<Map<String, Object>>
  - Same as above, but also includes multi-field statistics.

searchFirst(Class<T> beanClass, Map<String, Object> params): Map<String, Object>
  - Retrieves the first data entry matching the specified conditions.

searchList(Class<T> beanClass, Map<String, Object> params): List<Map<String, Object>>
  - Performs a paginated search for data lists matching the specified conditions.

searchAll(Class<T> beanClass, Map<String, Object> params): List<Map<String, Object>>
  - Retrieves all data lists matching the specified conditions.

Note: Data retrieved by these methods is presented as Map objects.
```

--------------------------------

### BeanSearcher Methods

Source: https://bs.zhxu.cn/guide/start/use

Methods specific to BeanSearcher for retrieving data as generic type T objects.

```APIDOC
search(Class<T> beanClass, Map<String, Object> params): SearchResult<T>
  - Performs a paginated search for data lists and total count matching the specified conditions.

search(Class<T> beanClass, Map<String, Object> params, String[] summaryFields): SearchResult<T>
  - Same as above, but also includes multi-field statistics.

searchFirst(Class<T> beanClass, Map<String, Object> params): T
  - Retrieves the first data entry matching the specified conditions.

searchList(Class<T> beanClass, Map<String, Object> params): List<T>
  - Performs a paginated search for data lists matching the specified conditions.

searchAll(Class<T> beanClass, Map<String, Object> params): List<T>
  - Retrieves all data lists matching the specified conditions.

Note: Data retrieved by these methods is presented as generic type T objects.
```

--------------------------------

### Bean Searcher Solon Plugin v4.2 Configuration

Source: https://bs.zhxu.cn/guide/info/versions

Details new configuration options for the Bean Searcher Solon Plugin in v4.2. Mirrors the Boot Starter configurations for dynamic dialects, data source mapping, enum conversion, and parameter error handling.

```properties
bean-searcher.sql.dialect-dynamic=false

# When dynamic data source is enabled, map data sources and dialects via DataSourceDialect Bean injection

# Auto-configures EnumParamConvertor

bean-searcher.params.fail-on-error=false
bean-searcher.params.convertor.date-target=
bean-searcher.params.convertor.date-time-target=
bean-searcher.params.convertor.time-target=
```

--------------------------------

### Custom Parameter Filter (Other Projects)

Source: https://bs.zhxu.cn/guide/advance/filter

Example of configuring custom parameter filters in projects other than SpringBoot, by adding them to a DefaultParamResolver.

```java
DefaultParamResolver paramResolver = new DefaultParamResolver();
// Add parameter filters
paramResolver.addParamFilter(new MyParamFilter1());
paramResolver.addParamFilter(new MyParamFilter2());
// Build Map searcher
MapSearcher mapSearcher = SearcherBuilder.mapSearcher()
        // Other configurations omitted
        .paramResolver(paramResolver)   // BeanSearcher searcher also configured this way
        .build();
```

--------------------------------

### Bean Searcher Boot Starter v3.1 New Features

Source: https://bs.zhxu.cn/guide/info/versions

Describes new features for the Bean Searcher Boot Starter in v3.1. This includes support for configuring NamedDataSource beans for multiple named data sources, automatic addition of 'spring-boot-starter-jdbc' dependency, and default auto-configuration for NumberFieldConvertor, StrNumFieldConvertor, BoolFieldConvertor, DateFieldConvertor, and DateFormatFieldConvertor. It also covers configuration for table name mapping and prefixes.

```Properties
# Supports configuring NamedDataSource type Beans to add multiple named data sources
# Automatically adds spring-boot-starter-jdbc dependency
# Default auto-configuration adds NumberFieldConvertor, StrNumFieldConvertor, BoolFieldConvertor, DateFieldConvertor, DateFormatFieldConvertor

# Supports configuring table name and field default lowercase or uppercase mapping
# Supports configuring table name default mapping prefix
```

--------------------------------

### Bean Searcher Boot Starter v4.1 Features

Source: https://bs.zhxu.cn/guide/info/versions

Highlights new features for Bean Searcher Boot Starter in v4.1, including the ability to customize GroupPairResolver via Bean injection.

```java
// Supports customizing GroupPairResolver via Bean injection
```

--------------------------------

### Convert Comma-Separated String to List<String>

Source: https://bs.zhxu.cn/guide/advance/convertor

Example of a SearchBean designed to receive a comma-separated string field from a database and convert it into a List of Strings.

```java
public class User {
    // 直接用数组 List 接收用户标签即可
    private List<String> tags;
    // 省略其它字段...
}
```

--------------------------------

### Bean Searcher Boot Starter v4.0 Enhancements

Source: https://bs.zhxu.cn/guide/info/versions

Details enhancements for the Bean Searcher Boot Starter in v4.0, including Spring Boot 3 support and new configuration properties for SQL default mapping and field converters.

```properties
# Bean Searcher Boot Starter v4.0 Configuration:

# Supports Spring Boot 3 (also supports SpringBoot 1.4 ~ 2.x).

# Configure identifier delimiters (e.g., MySQL's ` ` character).
bean-searcher.sql.default-mapping.around-char = 

# Whether to automatically add JsonFieldConvertor (default: true).
bean-searcher.field-convertor.use-json = true

# Whether to throw an exception on JSON parsing errors (default: true).
bean-searcher.field-convertor.json-fail-on-error = true

# Whether to automatically add ListFieldConvertor (default: true).
bean-searcher.field-convertor.use-list = true

# Configure how a string field is split into a List field.
bean-searcher.field-convertor.list-item-separator = ,

# Optimize date formats, supports replacing ':' with '-' (default: yyyy-MM-dd HH:mm:ss).
bean-searcher.field-convertor.date-formats = yyyy-MM-dd HH-mm-ss
```

--------------------------------

### Custom Parameter Filter (SpringBoot)

Source: https://bs.zhxu.cn/guide/advance/filter

Example of creating a custom parameter filter in a SpringBoot application by defining a Bean that implements the ParamFilter interface.

```java
@Bean
public ParamFilter myParamFilter() {
    return new ParamFilter() {
        @Override
        public <T> Map<String, Object> doFilter(BeanMeta<T> beanMeta, Map<String, Object> paraMap) {
            // beanMeta is the metadata of the entity being searched, paraMap is the current search parameters
            // TODO: Add custom parameter filtering rules here
            return paraMap;      // Return filtered search parameters
        }
    };
}
```

--------------------------------

### Bean Searcher Solon Plugin Configuration

Source: https://bs.zhxu.cn/guide/info/versions

Configuration options for Bean Searcher Solon Plugin, mirroring the Boot Starter regarding IndexArrayParamFilter and Label auto-configuration.

```APIDOC
bean-searcher.params.filter.use-index-array: boolean
  - Description: Controls whether to enable IndexArrayParamFilter.
  - Default: false

bean-searcher.label.auto-configuration: boolean
  - Description: Enables automatic configuration for Bean Searcher Label.
  - Default: true (assumed)

```

--------------------------------

### NumberFieldConvertor Configuration

Source: https://bs.zhxu.cn/guide/advance/convertor

Demonstrates how to configure the NumberFieldConvertor in Spring Boot, Spring MVC, and other project setups. This converter handles conversions between various numeric types.

```properties
bean-searcher.field-convertor.use-number = false
```

```java
@Bean
public NumberFieldConvertor numberFieldConvertor() {
    return new NumberFieldConvertor();
}
```

```xml
<bean id="beanReflector" class="cn.zhxu.bs.implement.DefaultBeanReflector">
    <property name="convertors">
        <list>
            <bean class="cn.zhxu.bs.convertor.NumberFieldConvertor" />
            <!-- 省略其它自段转换器的配置 -->
        <list>
    </property>
</bean>
<bean id="beanSearcher" class="cn.zhxu.bs.implement.DefaultBeanSearcher">
    <!-- 省略其它属性的配置 -->
    <property name="beanReflector" ref="beanReflector">
</bean>
```

```java
DefaultBeanReflector beanReflector = new DefaultBeanReflector();
beanReflector.addConvertor(new NumberFieldConvertor());         // 添加转换器
// 构建 Bean 检索器
BeanSearcher beanSearcher = SearcherBuilder.beanSearcher()
        // 省略其它属性的配置
        .beanReflector(beanReflector)
        .build();
```

--------------------------------

### BoolFieldConvertor Configuration (Others)

Source: https://bs.zhxu.cn/guide/advance/convertor

Standalone Java configuration for BoolFieldConvertor by manually adding it to DefaultBeanReflector and building the BeanSearcher. Includes an example of adding custom false values.

```java
DefaultBeanReflector beanReflector = new DefaultBeanReflector();
beanReflector.addConvertor(new BoolFieldConvertor());           // 添加转换器
// 构建 Bean 检索器
BeanSearcher beanSearcher = SearcherBuilder.beanSearcher()
        // 省略其它属性的配置
        .beanReflector(beanReflector)
        .build();

BoolFieldConvertor convertor = new BoolFieldConvertor();
// 添加将数据库中的字符串值 "Nothing" 转换为 false，同样不区分大小写
convertor.addFalseValues(new String[] { "Nothing" });
```

--------------------------------

### BeanAware 接口实现

Source: https://bs.zhxu.cn/guide/bean/optional

实现 BeanAware 接口的 afterAssembly 方法，可以在 Bean 属性装配完成后执行自定义逻辑。此方法会在所有 @DbField 注解的字段被赋值后自动调用。

```java
public class User implements BeanAware {
    // 省略其它代码
    @Override
    public void afterAssembly() {
        // 该方法会在 User 的字段值装配完后自动执行 
        // 代码走到这里说明，说明被 @DbField 注解的字段都已经被赋过值
        System.out.println("id = " + id + ", name = " + name);
    }
}
```

--------------------------------

### JsonFieldConvertor Usage Case: JSON Array to Simple List

Source: https://bs.zhxu.cn/guide/advance/convertor

Example showing the JsonFieldConvertor converting a JSON array string to a List of simple types (e.g., Strings).

```java
public class User {
    // 数据库值：["新生","优秀"]
    @DbField(type = DbType.JSON)
    private List<String> tags;
    // 省略其它字段...
}
```

--------------------------------

### ParamAware 接口实现

Source: https://bs.zhxu.cn/guide/bean/optional

实现 ParamAware 接口的 afterAssembly 方法，可以在 Bean 属性装配完成后监听到当前的检索参数。该方法接收一个 Map<String, Object> 类型的参数，其中包含当前的检索参数。

```java
public class User implements ParamAware {
    // 省略其它代码
    @Override
    public void afterAssembly(Map<String, Object> paraMap) {
        // 该方法可接收到当前的检索参数
        System.out.println(paraMap);
    }
}
```

--------------------------------

### Bean Searcher Grouping Configuration

Source: https://bs.zhxu.cn/guide/param/group

Lists the configuration keys available for customizing the logical grouping functionality when using the `bean-searcher-boot-starter` dependency. This allows fine-tuning of expression parameters, length, cache size, separators, and mergeability.

```properties
bean-searcher.params.group.enable
bean-searcher.params.group.expr-name
bean-searcher.params.group.max-expr-length 
bean-searcher.params.group.cache-size
bean-searcher.params.group.separator
bean-searcher.params.group.mergeable
```

--------------------------------

### Page 分页用法示例

Source: https://bs.zhxu.cn/guide/param/page

演示了在 Page 分页模式下，如何使用 `MapUtils.builder().page(0, 15)` 或直接 `put("page", 0)` 和 `put("size", 15)` 来构建分页参数，并执行搜索。

```java
Map<String, Object> params = MapUtils.builder()
        .page(0, 15)                    // 第 0 页，每页 15 条（推荐写法）
        .put("page", 0)                 // 等效写法
        .put("size", 15)                // 等效写法
        .build();
SearchResult<User> result = searcher.search(User.class, params);
```

--------------------------------

### SuffixOpParamFilter Configuration

Source: https://bs.zhxu.cn/guide/advance/filter

Simplifies front-end parameter passing by combining field names and operators. For example, 'age=30' and 'age-op=eq' can be combined into 'age-eq=30'. Disabled by default since v4.3.0.

```properties
# Whether to enable this filter, defaults to false
bean-searcher.params.filter.use-suffix-op = true
```

--------------------------------

### JsonFieldConvertor Usage Case: JSON Array to Complex List

Source: https://bs.zhxu.cn/guide/advance/convertor

Example demonstrating the JsonFieldConvertor's capability to convert JSON array strings into a List of complex objects (POJOs).

```java
public class User {
    // 数据库值：[{id: 1, name: "管理员"},{id: 2, name: "财务"}]
    @DbField(type = DbType.JSON)
    private List<Role> roles;
    // 省略其它字段...
}
```

--------------------------------

### Grails Domain Property Ignore Configuration

Source: https://bs.zhxu.cn/guide/start/integration

Configuration for Grails projects to ignore the `_errors` property added by Grails to domain classes, preventing potential conflicts with Bean Searcher.

```yml
bean-searcher:
    sql:
        default-mapping:
            ignore-fields: org_grails_datastore_gorm_GormValidateable__errors
```