Under-Utils

https://github.com/yexianglun-d/under-utils
Admin
Under-Utils is an engineering-pattern utility toolkit for Java 21 and Spring Boot projects,...
Tokens:14,930
Snippets:200
Trust Score:4.1
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Under-Utils Starter Configuration Example

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Configure under-utils starters via YAML properties. This example shows settings for web operations, exception handling, rate limiting, repeat submission, and Redis features.

```yaml
under:
  utils:
    web:
      operation-context:
        enabled: true
        task-decorator-enabled: true
        trusted-identity-headers: false
      exception-handling:
        enabled: false
      rate-limit:
        enabled: true
        store: redis
      repeat-submit:
        enabled: true
        store: redis
    redis:
      lock-enabled: true
      cache:
        enabled: true
        ttl: 5m
        null-ttl: 30s
        jitter: 10s
        cache-null: true
        key-prefix: "app:cache:"
        rebuild-lock-enabled: true
      logical-cache:
        enabled: true
        logical-ttl: 5m
        physical-ttl: 30m
        cache-null: true
        key-prefix: "app:logical-cache:"
      observation:
        enabled: true
```

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

### Local Development Setup for Under-Utils

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Clone the repository and run tests locally to set up the development environment.

```bash
git clone https://github.com/yexianglun-d/under-utils.git
cd under-utils
mvn test
```

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

### Running Under-Utils Sample Application

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Start the under-utils sample application using Maven. The default port is 18080, and it does not depend on Redis or MySQL by default.

```bash
mvn -pl under-utils-samples -am spring-boot:run
```

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

### Multi-Datasource MyBatis Configuration

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-mybatis/README.md

Example configuration for a multi-datasource setup, providing separate MyBatis-Plus interceptors for different database types.

```java
@Configuration
public class MultiDatasourceMybatisConfiguration {

    @Bean
    public MybatisPlusInterceptor mysqlInterceptor() {
        return MybatisPlusConfig.mybatisPlusInterceptor(DbType.MYSQL);
    }

    @Bean
    public MybatisPlusInterceptor postgresInterceptor() {
        return MybatisPlusConfig.mybatisPlusInterceptor(DbType.POSTGRE_SQL);
    }

    @Bean
    public DefaultMetaObjectHandler metaObjectHandler(AuditorProvider auditorProvider) {
        return new DefaultMetaObjectHandler(auditorProvider);
    }
}
```

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

### Asynchronous Import Task Example

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Submit asynchronous import tasks using AsyncImportTaskTemplate and an executor. Track task progress using the returned task ID.

```java
AsyncImportTaskTemplate importTasks = new AsyncImportTaskTemplate(executor);
String taskId = importTasks.submit(rows, handler);
ImportProgress progress = importTasks.findProgress(taskId).orElseThrow();
```

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

### Basic MyBatis Configuration

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-mybatis/README.md

Configure MyBatis-Plus interceptors and audit providers. This setup includes a default auditor and meta object handler.

```java
@Configuration
public class MybatisConfiguration {

    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        return MybatisPlusConfig.mybatisPlusInterceptor(DbType.MYSQL);
    }

    @Bean
    public AuditorProvider auditorProvider() {
        return () -> 1001L;
    }

    @Bean
    public DefaultMetaObjectHandler metaObjectHandler(AuditorProvider auditorProvider) {
        return new DefaultMetaObjectHandler(auditorProvider);
    }
}
```

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

### SysUser Entity Example

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-mybatis/README.md

Example entity extending BaseEntity, which includes common audit fields and logic deletion.

```java
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("sys_user")
public class SysUser extends BaseEntity {

    private String username;
    private String email;
    private Integer status;
}
```

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

### Redis Cache-Aside Pattern Example

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Utilize the cache-aside pattern with CacheAsideTemplate to fetch data from the cache or a repository. Configure cache key prefixes and null caching behavior.

```java
UserProfile profile = cacheAsideTemplate.get(
        "user:profile:" + userId,
        UserProfile.class,
        () -> userRepository.findProfile(userId)
);

```

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

### Example Commit Messages

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Illustrates concise and informative commit messages for various types of changes, such as documentation updates, bug fixes, and test additions. These messages help in tracking changes and understanding their purpose.

```text
完善 Redis 缓存模板文档

```

```text
修复 OpenAPI 重试异常处理

```

```text
补充 MyBatis 安全分页测试

```

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

### Operation Context Propagation Example

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Capture and wrap tasks to propagate operation context across threads. Use OperationContextHolder to access context details.

```java
OperationContext context = OperationContextHolder.getContext();
String traceId = context == null ? null : context.getTraceId();

Runnable task = OperationContextSnapshot.capture().wrap(() -> {
    OperationContext asyncContext = OperationContextHolder.getContext();
});
```

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

### Get Cache Metrics

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-redis/README.md

Retrieve basic cache metrics such as hit count, miss count, and hit rate from the cache template.

```java
CacheMetrics metrics = cacheAsideTemplate.getMetrics();
long hitCount = metrics.getHitCount();
long missCount = metrics.getMissCount();
double hitRate = metrics.getHitRate();
```

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

### English Commit Messages

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Examples of acceptable English commit messages, focusing on concise descriptions of the result.

```text
Improve Redis cache template docs
Fix OpenAPI retry exception handling
Add MyBatis safe pagination tests
```

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

### Chinese Commit Messages

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Examples of acceptable Chinese commit messages, focusing on concise descriptions of the result.

```text
完善 Redis 缓存模板文档
修复 OpenAPI 重试异常处理
补充 MyBatis 安全分页测试
```

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

### Run Tests and Package

Source: https://github.com/yexianglun-d/under-utils/blob/main/docs/release-notes-patch-template.md

Commands to execute tests and package the project for release.

```bash
mvn test
mvn -Prelease -DskipTests package
```

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

### Local Build and Package for Release

Source: https://github.com/yexianglun-d/under-utils/blob/main/docs/RELEASE.md

Runs tests, packages the release artifact, and verifies the build with signing enabled, skipping GPG encryption.

```bash
mvn test
mvn -Prelease -DskipTests package
mvn -Prelease,sign-artifacts -Dgpg.skip=true -DskipTests verify
```

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

### Import Under-Utils BOM and Spring Starter

Source: https://github.com/yexianglun-d/under-utils/blob/main/README_EN.md

Import the Bill of Materials (BOM) to manage dependency versions, then add the Spring starter for local Spring cross-cutting features.

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.yexianglun-d</groupId>
            <artifactId>under-utils-bom</artifactId>
            <version>1.0.3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.github.yexianglun-d</groupId>
        <artifactId>under-utils-spring-starter</artifactId>
    </dependency>
</dependencies>
```

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

### Configuring Local Store for Rate Limiting and Repeat Submission Prevention

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-spring/README.md

Configure the capacity and cleanup interval for the local stores used by rate limiting and repeat submission prevention when using the starter. This optimizes resource usage for single-instance deployments.

```yaml
under:
  utils:
    web:
      rate-limit:
        store: local
        local-max-entries: 100000
        local-cleanup-interval: 1s
      repeat-submit:
        store: local
        local-max-entries: 100000
        local-cleanup-interval: 1s
```

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

### Maven Dependency for Under-Utils Starter

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-starter/README.md

Include this dependency in your project's pom.xml to use the Under-Utils starter.

```xml
<dependency>
    <groupId>io.github.yexianglun-d</groupId>
    <artifactId>under-utils-starter</artifactId>
    <version>1.0.3</version>
</dependency>
```

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

### AI Client Initialization

Source: https://github.com/yexianglun-d/under-utils/blob/main/README_EN.md

Build and configure an AI client for making chat requests. Requires base URL, API key, and model name.

```java
AiClient aiClient = AiClient.builder()
        .baseUrl("https://api.example.com/v1")
        .apiKey(apiKey)
        .model("your-model-name")
        .build();
```

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

### Common Maven Commands

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Provides essential Maven commands for compiling, testing, and packaging the project. Use these for local development and build processes.

```bash
mvn -DskipTests compile

```

```bash
mvn test

```

```bash
mvn -Prelease -DskipTests package

```

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

### Maven Dependency for Under-Utils Redis Starter

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Include the under-utils Redis starter if you require Redis distributed locks, rate limiting, or cache templates.

```xml
<dependency>
    <groupId>io.github.yexianglun-d</groupId>
    <artifactId>under-utils-redis-starter</artifactId>
</dependency>
```

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

### Maven Dependency for Under-Utils AI Starter

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Use the independent AI starter for Spring Boot projects that need to create a default AiClient based on configuration.

```xml
<dependency>
    <groupId>io.github.yexianglun-d</groupId>
    <artifactId>under-utils-ai-starter</artifactId>
</dependency>
```

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

### Default Maven Build and Test Commands

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Compile the project without running tests, then run all tests. These are the default commands for building and verifying the project.

```bash
mvn -DskipTests compile
mvn test
```

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

### Run Tests

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Executes all tests in the project. Ensure your environment is set up correctly before running this command.

```bash
mvn test
```

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

### Public API Compatibility Check Command

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Verify public API compatibility by comparing the current build against the latest stable release. This command targets specific modules and requires the 'api-compat' profile.

```bash
mvn -Papi-compat \
  -pl under-utils-core,under-utils-http,under-utils-ai,under-utils-ai-starter,under-utils-spring,under-utils-redis,under-utils-mybatis,under-utils-biz \
  -am \
  -DskipTests \
  verify
```

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

### Run Integration Tests

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Executes integration tests for the project. This command requires the 'integration-tests' profile to be active.

```bash
mvn -Pintegration-tests -pl under-utils-test -am test
```

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

### Under-Utils Configuration

Source: https://github.com/yexianglun-d/under-utils/blob/main/README_EN.md

Default in-memory configuration for Under-Utils. For Redis, ensure RedissonClient is configured.

```yaml
under:
  utils:
    web:
      operation-context:
        enabled: true
        task-decorator-enabled: true
      rate-limit:
        enabled: true
        store: redis
      repeat-submit:
        enabled: true
        store: redis
    redis:
      lock-enabled: true
      cache:
        enabled: true
        ttl: 5m
        null-ttl: 30s
        jitter: 10s
        cache-null: true
        key-prefix: "app:cache:"
        rebuild-lock-enabled: true
      logical-cache:
        enabled: true
        logical-ttl: 5m
        physical-ttl: 30m
        cache-null: true
        key-prefix: "app:logical-cache:"
      observation:
        enabled: true
```

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

### Handling HTTP Exceptions

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-http/README.md

Demonstrates how to catch specific HTTP exceptions like timeouts, network failures, and general HTTP module errors when making requests.

```java
try {
    String body = HttpUtils.get("https://api.example.com/users");
} catch (HttpTimeoutException e) {
    // timeout
} catch (HttpNetworkException e) {
    // network failure
} catch (HttpException e) {
    // other HTTP module failure
}
```

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

### Safe Pagination with SortFieldMapping

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-mybatis/README.md

Demonstrates secure pagination by mapping public sort field names to database columns and enforcing order by clauses.

```java
SortFieldMapping mapping = SortFieldMapping.builder()
        .add("createdAt", "create_time")
        .add("username", "username")
        .add("status", "status")
        .build();

SafePageQuery pageQuery = SafePageQuery.of(1L, 20L)
        .orderByDesc("createdAt");

IPage<SysUser> page = userMapper.selectPage(
        pageQuery.buildPage(mapping),
        new LambdaQueryWrapper<SysUser>()
                .eq(SysUser::getStatus, 1)
);

PageResult<SysUser> result = PageResult.of(page);
```

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

### Maven Dependency for Under-Utils Spring Starter

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Add the under-utils Spring starter dependency to your project if you only need local Spring cross-cutting capabilities.

```xml
<dependency>
    <groupId>io.github.yexianglun-d</groupId>
    <artifactId>under-utils-spring-starter</artifactId>
</dependency>
```

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

### Enabling Trusted Identity Headers in Spring Boot Starter

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-spring/README.md

Configure the Spring Boot starter to trust identity headers (User-Id, Tenant-Id) if your service is behind a trusted gateway. This simplifies identity propagation.

```yaml
under:
  utils:
    web:
      operation-context:
        trusted-identity-headers: true
```

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

### Package Project for Release

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Packages the project for release, skipping tests. This command is typically used for building distributable artifacts.

```bash
mvn -Prelease -DskipTests package
```

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

### Enabling Global Exception Handling in Spring Boot Starter

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-spring/README.md

Configure the Spring Boot starter to automatically enable global exception handling. This centralizes exception management and provides consistent error responses.

```yaml
under:
  utils:
    web:
      exception-handling:
        enabled: true
```

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

### Public API Compatibility Check

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Verifies public API compatibility across specified modules. This command is crucial for ensuring backward compatibility before releasing changes.

```bash
mvn -Papi-compat \
  -pl under-utils-core,under-utils-http,under-utils-spring,under-utils-redis,under-utils-mybatis,under-utils-biz \
  -am \
  -DskipTests \
  verify
```

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

### Maven Central Server Configuration

Source: https://github.com/yexianglun-d/under-utils/blob/main/docs/RELEASE.md

Configures the Maven settings.xml file with server credentials for Maven Central deployment using environment variables for username and password.

```xml
<settings>
  <servers>
    <server>
      <id>central</id>
      <username>${env.CENTRAL_TOKEN_USERNAME}</username>
      <password>${env.CENTRAL_TOKEN_PASSWORD}</password>
    </server>
  </servers>
</settings>
```

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

### Maven Dependency Management for Under-Utils BOM

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Include the under-utils BOM in your Maven project to manage dependency versions. This is recommended before importing starters or modules.

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.yexianglun-d</groupId>
            <artifactId>under-utils-bom</artifactId>
            <version>1.0.3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

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

### Integration Test Command

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-mybatis/README.md

Command to run integration tests for the under-utils-test module using Maven, specifically targeting MybatisIntegrationTest.

```bash
mvn -Pintegration-tests -pl under-utils-test -am test -Dtest=MybatisIntegrationTest
```

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

### Manual Maven Central Release Deployment

Source: https://github.com/yexianglun-d/under-utils/blob/main/docs/RELEASE.md

Deploys the release artifact to Maven Central, enabling GPG signing and configuring the Central plugin to wait for validation before automatic publishing.

```bash
mvn -Prelease,sign-artifacts,central-publish \
  -Dgpg.sign=true \
  -Dcentral.skipPublishing=false \
  -Dcentral.autoPublish=false \
  -Dcentral.waitUntil=validated \
  -DskipTests \
  deploy
```

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

### Compile Project

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Compiles the project without running tests. Useful for checking compilation errors or preparing for packaging.

```bash
mvn -DskipTests compile
```

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

### Implement Custom AiClientProvider

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-ai/README.md

Extend AiClientProvider to integrate with non-compatible AI protocols. This involves returning a unique provider name and creating a custom AiClient implementation.

```java
AiClientProvider provider = new AiClientProvider() {
    @Override
    public String provider() {
        return "native-vendor";
    }

    @Override
    public AiClient create(AiClientOptions options) {
        return new NativeVendorAiClient(options);
    }
};

AiClient client = AiClient.builder()
        .baseUrl("https://api.example.com")
        .model("vendor-model")
        .provider(provider)
        .build();
```

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

### Maven Integration Tests

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Executes integration tests for the 'under-utils-test' module using the 'integration-tests' Maven profile. This is useful for verifying end-to-end functionality.

```bash
mvn -Pintegration-tests -pl under-utils-test -am test

```

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

### Local State Storage Configuration

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-starter/README.md

Configure local state storage for web operations, rate limiting, and repeat submission prevention. Ensure 'under.utils.web.operation-context.enabled' is true to activate context features.

```yaml
under:
  utils:
    web:
      operation-context:
        enabled: true
        task-decorator-enabled: true
      rate-limit:
        enabled: true
        store: local
      repeat-submit:
        enabled: true
        store: local
```

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

### Maven Dependency for Under-Utils AI Module

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Import the under-utils AI module if you only need basic AI large model call encapsulation.

```xml
<dependency>
    <groupId>io.github.yexianglun-d</groupId>
    <artifactId>under-utils-ai</artifactId>
</dependency>
```

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

### Use Micrometer Cache Operation Observer

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-redis/README.md

Utilize the built-in MicrometerCacheOperationObserver for seamless integration with Micrometer monitoring if your project already uses it.

```java
CacheOperationObserver observer = new MicrometerCacheOperationObserver(meterRegistry, observationRegistry);
CacheAsideTemplate template = new CacheAsideTemplate(redissonClient, codec, options, observer);
```

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

### Maven API Compatibility Check

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Runs a check for public API compatibility across specified modules using the 'api-compat' Maven profile. This ensures that API changes are backward compatible where intended.

```bash
mvn -Papi-compat \
  -pl under-utils-core,under-utils-http,under-utils-spring,under-utils-redis,under-utils-mybatis,under-utils-biz \
  -am \
  -DskipTests \
  verify

```

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

### Run Integration Tests for Redis Cache

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-redis/README.md

Execute integration tests for the Redis cache template using Maven, specifically targeting RedisCacheTemplateIntegrationTest with Testcontainers.

```bash
mvn -Pintegration-tests -pl under-utils-test -am test -Dtest=RedisCacheTemplateIntegrationTest
```

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

### Maven Central Dry Run Deployment

Source: https://github.com/yexianglun-d/under-utils/blob/main/CONTRIBUTING.md

Performs a dry run of the deployment process to the Central Maven Repository using a specific settings file and profile. This helps in verifying the release packaging and metadata without actually publishing.

```bash
mvn -s docs/central-dry-run-settings.xml \
  -Prelease,central-publish \
  -Dcentral.publishing.server.id=central-dry-run \
  -Dcentral.skipPublishing=true \
  -Dgpg.skip=true \
  -DskipTests \
  deploy

```

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

### MyBatis-Plus Dependency

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-mybatis/README.md

Add this dependency to your project to use the under-utils-mybatis module.

```xml
<dependency>
    <groupId>io.github.yexianglun-d</groupId>
    <artifactId>under-utils-mybatis</artifactId>
    <version>1.0.3</version>
</dependency>
```

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

### Async Import Task Submission

Source: https://github.com/yexianglun-d/under-utils/blob/main/README_EN.md

Submit asynchronous import tasks using a template and an executor. Returns a task ID.

```java
AsyncImportTaskTemplate importTasks = new AsyncImportTaskTemplate(executor);
String taskId = importTasks.submit(rows, handler);
```

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

### Dependency for Under-Utils Core

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-core/README.md

Include this dependency in your Maven project to use the Under-Utils Core library.

```xml
<dependency>
    <groupId>io.github.yexianglun-d</groupId>
    <artifactId>under-utils-core</artifactId>
    <version>1.0.3</version>
</dependency>
```

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

### Secure Pagination with Sort Field Mapping

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Implement secure pagination using SafePageQuery and SortFieldMapping to define allowed sorting fields and prevent arbitrary sorting. Order results by creation date in descending order.

```java
SortFieldMapping mapping = SortFieldMapping.builder()
        .add("createdAt", "create_time")
        .add("status", "status")
        .build();

SafePageQuery query = SafePageQuery.of(page, size)
        .orderByDesc("createdAt");
```

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

### Central Portal Dry Run Deployment

Source: https://github.com/yexianglun-d/under-utils/blob/main/docs/RELEASE.md

Executes a dry run of the deployment to Maven Central, simulating the upload process without actually publishing.

```bash
mvn -s docs/central-dry-run-settings.xml \
  -Prelease,central-publish \
  -Dcentral.publishing.server.id=central-dry-run \
  -Dcentral.skipPublishing=true \
  -Dgpg.skip=true \
  -DskipTests \
  deploy
```

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

### Redis Cache-Aside Usage

Source: https://github.com/yexianglun-d/under-utils/blob/main/README_EN.md

Fetch data from cache or load and cache it if not present. Supports custom TTL and null value TTL.

```java
UserProfile profile = cacheAsideTemplate.cache("user:profile:" + userId, UserProfile.class)
        .ttl(Duration.ofMinutes(3))
        .nullValueTtl(Duration.ofSeconds(10))
        .getOrLoad(key -> userRepository.findProfile(userId));
```

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

### Redis State Storage and Cache Configuration

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-starter/README.md

Configure Redis-based state storage for rate limiting and repeat submission, along with distributed lock and cache templates. Note that 'under.utils.redis.logical-cache.physical-ttl' must be greater than 'logical-ttl'.

```yaml
under:
  utils:
    web:
      rate-limit:
        store: redis
      repeat-submit:
        store: redis
    redis:
      lock-enabled: true
      cache:
        enabled: true
        ttl: 5m
        null-ttl: 30s
        jitter: 10s
        rebuild-lock-enabled: true
      logical-cache:
        enabled: true
        logical-ttl: 5m
        physical-ttl: 30m
```

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

### Maven Dependency for Under-Utils Spring

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-spring/README.md

Include this dependency in your project's pom.xml to use the Under-Utils Spring module.

```xml
<dependency>
    <groupId>io.github.yexianglun-d</groupId>
    <artifactId>under-utils-spring</artifactId>
    <version>1.0.3</version>
</dependency>
```

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

### Configure Repeat Submit with Release on Failure

Source: https://github.com/yexianglun-d/under-utils/blob/main/docs/articles/spring-boot-repeat-submit.md

Use the @PreventRepeat annotation to configure repeat submit protection. Set releaseOnFailure to true to release the key when the business method throws an exception, allowing users to resubmit after correction.

```java
@PreventRepeat(
        timeout = 5,
        timeUnit = TimeUnit.SECONDS,
        releaseOnFailure = true,
        message = "请勿重复提交"
)
```

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

### Custom AuditorProvider Implementation

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-mybatis/README.md

Provides a custom implementation for AuditorProvider to fetch the current user ID from the Security Context.

```java
@Bean
public AuditorProvider auditorProvider() {
    return () -> {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (authentication == null || !(authentication.getPrincipal() instanceof YourUserDetails user)) {
            return null;
        }
        return user.getId();
    };
}
```

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

### Configure Local Repeat Submit Store in application.yaml

Source: https://github.com/yexianglun-d/under-utils/blob/main/docs/articles/spring-boot-repeat-submit.md

Configure the local store for repeat submit protection in your Spring Boot application's YAML file. This allows setting the maximum number of entries and the cleanup interval for the local store.

```yaml
under:
  utils:
    web:
      repeat-submit:
        store: local
        local-max-entries: 100000
        local-cleanup-interval: 1s
```

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

### Standard API Response with Result Wrapper

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-spring/README.md

Return API responses using the Result wrapper for consistent success and data encapsulation. This is a common pattern for RESTful APIs.

```java
@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public Result<User> getUser(@PathVariable Long id) {
        return Result.success(userService.getById(id));
    }
}
```

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

### Customizing Audit Fill Options

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-mybatis/README.md

Configure custom field names and values for audit fields and logic deletion when they differ from BaseEntity defaults.

```java
@Bean
public DefaultMetaObjectHandler metaObjectHandler(AuditorProvider auditorProvider) {
    AuditFillOptions options = AuditFillOptions.builder()
            .createTimeField("createdAt")
            .updateTimeField("updatedAt")
            .createByField("creatorId")
            .updateByField("updaterId")
            .deletedField("isDeleted")
            .notDeletedValue(false)
            .build();
    return new DefaultMetaObjectHandler(auditorProvider, options);
}
```

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

### Money Calculation with BigDecimal

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-core/README.md

Utilize MoneyUtils for common BigDecimal operations like converting between Yuan and Fen, addition, division, and formatted display. Default settings use 2 decimal places and HALF_UP rounding.

```java
Long fen = MoneyUtils.yuan2Fen(new BigDecimal("10.50"));
BigDecimal yuan = MoneyUtils.fen2Yuan(1050L);

BigDecimal total = MoneyUtils.add(
        new BigDecimal("10.50"),
        new BigDecimal("20.30")
);

BigDecimal avg = MoneyUtils.divide(total, new BigDecimal("3"));
String display = MoneyUtils.formatWithSymbol(total);
```

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

### Rate Limiting with Annotation

Source: https://github.com/yexianglun-d/under-utils/blob/main/README_EN.md

Apply rate limiting to a POST endpoint. Rejects requests with 'too many requests' message if limit is exceeded.

```java
@RateLimit(limit = 10, period = 60, message = "too many requests")
@PostMapping("/sms/send")
public void sendSms(@RequestBody SendSmsCommand command) {
    smsService.send(command);
}
```

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

### Implement Custom Cache Operation Observer

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-redis/README.md

Implement the CacheOperationObserver interface to handle cache events like hits and load failures, integrating with custom monitoring or logging.

```java
CacheOperationObserver observer = new CacheOperationObserver() {
    @Override
    public void onHit(CacheOperationEvent event) {
        metrics.counter("cache.hit", "type", event.getOperationType().name()).increment();
    }

    @Override
    public void onLoadFailure(CacheOperationEvent event) {
        log.warn("cache load failed: {}", event.getCacheKey(), event.getError());
    }
};

CacheAsideTemplate template = new CacheAsideTemplate(redissonClient, codec, options, observer);
```

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

### Local Central Dry Run Verification

Source: https://github.com/yexianglun-d/under-utils/blob/main/docs/RELEASE.md

Performs a dry run of the Maven Central deployment using a specified settings file and profile, skipping tests and GPG signing.

```bash
mvn -gs docs/central-dry-run-settings.xml -s docs/central-dry-run-settings.xml \
  -Papi-compat \
  -pl under-utils-core,under-utils-http,under-utils-ai,under-utils-ai-starter,under-utils-spring,under-utils-redis,under-utils-mybatis,under-utils-biz \
  -am \
  -DskipTests \
  verify
```

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

### Async Import Task Progress

Source: https://github.com/yexianglun-d/under-utils/blob/main/README_EN.md

Retrieve the progress of an asynchronous import task using its ID.

```java
ImportProgress progress = importTasks.findProgress(taskId).orElseThrow();
```

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

### Generate and Parse Snowflake IDs

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-core/README.md

Instantiate IdGenerator with datacenter and worker IDs to generate unique IDs. You can also parse generated IDs to retrieve their components.

```java
IdGenerator generator = new IdGenerator(1, 1);

long id = generator.nextId();
String idText = generator.nextIdStr();

IdGenerator.IdInfo info = generator.parseId(id);
long timestamp = info.getTimestamp();
long datacenterId = info.getDatacenterId();
long workerId = info.getWorkerId();
```

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

### AI Chat Request

Source: https://github.com/yexianglun-d/under-utils/blob/main/README_EN.md

Send a user message to the AI client for a chat response.

```java
ChatResponse response = aiClient.chat(ChatRequest.user("Summarize this text."));
```

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

### Applying Rate Limiting to an API Endpoint

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-spring/README.md

Use the @RateLimit annotation to protect an API endpoint from excessive requests. Configure the limit, period, and a custom message for exceeding the rate.

```java
@RateLimit(limit = 10, period = 60, message = "请求过于频繁")
@PostMapping("/sms/send")
public void sendSms(@RequestBody SendSmsCommand command) {
    smsService.send(command);
}
```

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

### Logic Deletion Configuration

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-mybatis/README.md

Configure MyBatis-Plus for logic deletion by specifying the field name and values for deleted and non-deleted states.

```yaml
mybatis-plus:
  global-config:
    db-config:
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0
```

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

### Accessing Operation Context

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-spring/README.md

Retrieve the current operation context to access details like the trace ID. This is typically done within a request processing flow.

```java
OperationContext context = OperationContextHolder.getContext();
String traceId = context == null ? null : context.getTraceId();
```

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

### Streaming AI Chat

Source: https://github.com/yexianglun-d/under-utils/blob/main/README_EN.md

Stream chat responses from the AI client. Filters for text events and prints them.

```java
if (aiClient instanceof StreamingAiClient streamingAiClient) {
    try (ChatStream stream = streamingAiClient.streamChat(ChatRequest.user("Write step by step."))) {
        stream.stream()
                .filter(ChatStreamEvent::hasText)
                .forEach(event -> System.out.print(event.text()));
    }
}
```

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

### Rate Limiting and Repeat Submission Annotations

Source: https://github.com/yexianglun-d/under-utils/blob/main/README.md

Apply @RateLimit and @PreventRepeat annotations to controller methods to enforce request limits and prevent duplicate submissions. Customize messages and timeouts.

```java
@RateLimit(limit = 10, period = 60, message = "请求过于频繁")
@PostMapping("/sms/send")
public void sendSms(@RequestBody SendSmsCommand command) {
    smsService.send(command);
}

@PreventRepeat(timeout = 5, message = "请勿重复提交")
@PostMapping("/orders")
public Long createOrder(@RequestBody CreateOrderCommand command) {
    return orderService.create(command);
}
```

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

### JSON Serialization and Deserialization

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-core/README.md

Use JsonUtils for basic JSON operations like converting objects to JSON strings and parsing JSON strings back into objects. It uses an internal ObjectMapper, which should not be modified by callers.

```java
String json = JsonUtils.toJson(payload);
Payload parsed = JsonUtils.fromJson(json, Payload.class);
```

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

### Capturing and Restoring Operation Context in Async Tasks

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-spring/README.md

Wrap asynchronous tasks to ensure the operation context is preserved and available. This is crucial for maintaining request context across threads.

```java
Runnable task = OperationContextSnapshot.capture().wrap(() -> {
    OperationContext asyncContext = OperationContextHolder.getContext();
});
```

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

### SysUser Table Schema

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-mybatis/README.md

SQL schema for the sys_user table, including standard audit and logic deletion fields.

```sql
CREATE TABLE sys_user (
  id BIGINT PRIMARY KEY,
  username VARCHAR(50) NOT NULL,
  email VARCHAR(100),
  status INT DEFAULT 1,
  create_time DATETIME,
  update_time DATETIME,
  create_by BIGINT,
  update_by BIGINT,
  deleted INT DEFAULT 0
);
```

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

### Importing Legacy AOP Aspects in Spring Configuration

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-spring/README.md

Explicitly import legacy AOP aspects like OperationLog, Retry, and TimeLog in your Spring configuration if needed. Note that these are for compatibility and not the primary focus of new development.

```java
@Configuration
@EnableAspectJAutoProxy
@Import({
    OperationLogAspect.class,
    RetryAspect.class,
    TimeLogAspect.class
})
public class LegacyAopConfiguration {
}
```

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

### Prevent Repeat Submission with Annotation

Source: https://github.com/yexianglun-d/under-utils/blob/main/README_EN.md

Prevent duplicate requests within a specified timeout. Rejects requests with 'duplicate request' message.

```java
@PreventRepeat(timeout = 5, message = "duplicate request")
@PostMapping("/orders")
public Long createOrder(@RequestBody CreateOrderCommand command) {
    return orderService.create(command);
}
```

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

### Preventing Duplicate Submissions with @PreventRepeat

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-spring/README.md

Annotate endpoints with @PreventRepeat to avoid duplicate submissions within a specified timeout. Configure the timeout duration and a message for repeated submissions.

```java
@PreventRepeat(timeout = 5, timeUnit = TimeUnit.SECONDS, message = "请勿重复提交")
@PostMapping("/orders")
public Long createOrder(@RequestBody CreateOrderCommand command) {
    return orderService.create(command);
}
```

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

### Disabling Logic Deletion Fill

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-mybatis/README.md

Use AuditFillOptions to disable the logic deletion field from being filled by the handler if the entity does not use it.

```java
AuditFillOptions.builder().fillDeleted(false).build()
```

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

### Applying Sensitive Data Masking to a Field

Source: https://github.com/yexianglun-d/under-utils/blob/main/under-utils-spring/README.md

Use the @Sensitive annotation with a SensitiveType to automatically mask sensitive data fields during JSON serialization. Ensure Jackson serializers are registered.

```java
public class UserView {

    @Sensitive(type = SensitiveType.PHONE)
    private String phone;
}
```
Tokens:
Raw