append asynchronous env guide docs

Author: Hyeon9mak

README-EN.md

@@ -0,0 +1,137 @@
+# 🖥️ Multi-DataSource Query Counter
+
+[한국어](README.md) | **English**
+
+## 🖥️ Introduction
+
+This project is a simple tool to measuring query counts in a JDBC API(Spring Data JPA(Hibernate), MyBatis, ...) environment.  
+You can seamlessly measure query counts also in a Multi-DataSource environment.
+
+```
+Hibernate: 
+    select
+        id,
+        name
+    from
+        example 
+        
+Hibernate: 
+    select
+        count(id) 
+    from
+        example
+                 
+ERROR --- 'GET /examples' - totalQueryCount: 2, totalSpendTime: 7ms
+```
+
+<br>
+
+## 🖥️ How to use?
+
+### 1. Add dependency
+
+> [!IMPORTANT]   
+> Spring Boot 3.x uses `jakarta.*` packages while Spring Boot 2.x uses `javax.*` packages. Make sure to select the compatible library version for your project.
+
+Choose the appropriate version based on your Spring Boot version:
+
+| Spring Boot Version | Library Version     |
+|---------------------|---------------------|
+| Spring Boot 2.x     | 2.x.x-spring-boot-2 |
+| Spring Boot 3.x     | 2.x.x-spring-boot-3 |
+
+### In Java Gradle(Groovy DSL)
+
+```groovy
+repositories {
+    mavenCentral()
+    maven { url 'https://jitpack.io' }
+}
+
+dependencies {
+    // For Spring Boot 2.x
+    implementation 'com.github.Hyeon9mak:multi-datasource-query-counter:2.0.2-spring-boot-2'
+
+    // For Spring Boot 3.x
+    // implementation 'com.github.Hyeon9mak:multi-datasource-query-counter:2.0.2-spring-boot-3'
+}
+```
+
+### In Kotlin Gradle(Kotlin DSL)
+
+```kotlin
+repositories {
+    mavenCentral()
+    maven { url = uri("https://jitpack.io") }
+}
+
+dependencies {
+    // For Spring Boot 2.x
+    implementation("com.github.Hyeon9mak:multi-datasource-query-counter:2.0.2-spring-boot-2")
+
+    // For Spring Boot 3.x
+    // implementation("com.github.Hyeon9mak:multi-datasource-query-counter:2.0.2-spring-boot-3")
+}
+```
+
+### 2. Add logging options
+
+The priority order is as follows: `error` > `warn` > `info`.  
+The default value for `enable` is `false`, and the default value for `count` is `1`.
+
+```yaml
+query-counter.logging.level:
+  error:
+    enable: true
+    count: 5
+  warn:
+    enable: true
+    count: 2
+  info:
+    enable: false
+```
+
+### 3. Specify the target API
+
+`@CountQueries` annotation is used to specify the API you want to measure.
+
+```java
+@CountQueries
+@GetMapping("/examples")
+public List<Example> getExamples() {
+    return repository.getExamples();
+}
+```
+
+### 4. Check the log
+
+Start the application and check the log.
+
+```
+ERROR --- 'GET /examples' - totalQueryCount: 2, totalSpendTime: 7ms
+```
+
+Enjoy it! 🎉
+
+<br>
+
+## 🖥️ In asynchronous environments
+
+- [Click here to read the guide for Java Asynchronous environments.](README-java-asynchronous-environments-EN.md)
+- [Click here to read the guide for Kotlin Coroutine environments.](README-kotlin-coroutine-environments-EN.md)
+
+<br>
+
+## 🖥️ Core concepts
+
+![image](core_concept.png)
+
+It's based on the JDBC API and Spring AOP, CGLib proxy.  
+... That's it!
+
+<br>
+
+## 🖥️ Recommended articles
+
+- [API 요청 당 쿼리 개수를 알고 싶어 라이브러리까지 만든 이야기 — 라이브러리 제작](https://medium.com/@hyeon9mak/api-%EC%9A%94%EC%B2%AD-%EB%8B%B9-%EC%BF%BC%EB%A6%AC-%EA%B0%9C%EC%88%98%EB%A5%BC-%EC%95%8C%EA%B3%A0-%EC%8B%B6%EC%96%B4-%EB%9D%BC%EC%9D%B4%EB%B8%8C%EB%9F%AC%EB%A6%AC%EA%B9%8C%EC%A7%80-%EB%A7%8C%EB%93%A0-%EC%9D%B4%EC%95%BC%EA%B8%B0-%EB%9D%BC%EC%9D%B4%EB%B8%8C%EB%9F%AC%EB%A6%AC-%EC%A0%9C%EC%9E%91-de39f0d27351)
+- [Hibernate 의 ‘불편한’ 편의 기능들](https://medium.com/monday-9-pm/hibernate-%EC%9D%98-%EB%B6%88%ED%8E%B8%ED%95%9C-%ED%8E%B8%EC%9D%98-%EA%B8%B0%EB%8A%A5%EB%93%A4-06a1fbc7492a)

README-java-asynchronous-environments-EN.md

@@ -0,0 +1,104 @@
+# 🖥️ Sharing QueryCountPerRequest Across Threads in Asynchronous Environments
+
+[한국어](README-java-asynchronous-environments.md) | **English**
+
+## 🖥️ Overview
+
+The Multi-Datasource-Query-Counter library counts database queries per API request. By default, it uses `@RequestScope` to ensure each request has its own counter.
+However, in asynchronous environments (`CompletableFuture`, `@Async`, WebFlux, etc.), execution switches to new threads, which cannot access the original request context, resulting in missed query counts.
+
+This guide explains how to properly share the `QueryCountPerRequest` object across threads in asynchronous environments.
+
+<br>
+
+## 🖥️ The Problem
+
+In a typical Spring application, a request is processed within a single thread.
+However, when using asynchronous code:
+
+1. Execution switches to a new thread.
+2. The new thread has a new context.
+
+So, the new thread cannot access the original request context.
+
+<br>
+
+## 🖥️ Solution: Using TaskDecorator
+
+Spring provides `TaskDecorator` which allows copying the request context to new threads before executing asynchronous tasks.
+
+### 1. Configure ThreadPoolTaskExecutor
+
+```java
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.scheduling.annotation.EnableAsync;
+import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
+import org.springframework.web.context.request.RequestAttributes;
+import org.springframework.web.context.request.RequestContextHolder;
+
+import java.util.concurrent.Executor;
+
+@EnableAsync
+@Configuration
+public class AsyncConfig {
+    
+    @Bean(name = "asyncExecutor")
+    public Executor asyncExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+        
+        // Configure thread pool settings according to your application needs... (skip)
+        
+        // Set TaskDecorator to copy the request context to the new thread!
+        executor.setTaskDecorator(task -> {
+            RequestAttributes requestAttributes = RequestContextHolder.currentRequestAttributes();
+            return () -> {
+                try {
+                    RequestContextHolder.setRequestAttributes(requestAttributes);
+                    task.run();
+                } finally {
+                    RequestContextHolder.resetRequestAttributes();
+                }
+            };
+        });
+        
+        executor.initialize();
+        return executor;
+    }
+}
+```
+
+### 2. Using CompletableFuture
+
+When using CompletableFuture directly, use the custom Executor:
+
+```java
+@Autowired
+@Qualifier("asyncExecutor")
+private Executor asyncExecutor;
+
+public CompletableFuture<List<User>> findAllUsersAsync() {
+    return CompletableFuture.supplyAsync(() -> {
+        return userRepository.findAll(); // Query count point.
+    }, asyncExecutor);                   // Specify the custom executor.
+}
+```
+
+### 3. Using @Async Annotation
+
+When using the @Async annotation, explicitly specify the configured Executor:
+
+```java
+@Async("asyncExecutor")  // Specify the bean name explicitly.
+public CompletableFuture<User> findUserByIdAsync(Long id) {
+    return CompletableFuture.completedFuture(
+        userRepository.findById(id).orElse(null) // Query count point.
+    );
+}
+```
+
+<br>
+
+## 🖥️ WebFlux/Reactor Environment
+
+(WIP)

README-java-asynchronous-environments.md

@@ -0,0 +1,105 @@
+# 🖥️ 비동기 환경에서 스레드 간 QueryCountPerRequest 공유하기
+
+**한국어** | [English](README-java-asynchronous-environments-EN.md)
+
+## 🖥️ 개요
+
+Multi-Datasource-Query-Counter 라이브러리는 API 요청별로 데이터베이스 쿼리 수를 계산합니다.
+라이브러리는 기본적으로 `@RequestScope`를 활용하여 각 API 요청마다 카운터를 갖도록 하고 있습니다.
+그러나 비동기 환경(`CompletableFuture`, `@Async`, WebFlux 등)에서 별다른 설정 없이 새 스레드로 전환이 진행되면 서로 다른 카운터를 갖게 되므로 올바른 쿼리 개수 측정이 불가능합니다.
+
+이 가이드는 비동기 환경에서 스레드 간 `QueryCountPerRequest` 객체를 올바르게 공유하는 방법을 설명합니다.
+
+<br>
+
+## 🖥️ 문제점
+
+일반적인 Spring 애플리케이션에서 API 요청은 단일 스레드 내에서 처리됩니다.
+그러나 비동기 코드를 사용할 때는 아래와 같은 순서를 가집니다.
+
+1. 새 스레드로 분기
+2. 새 스레드는 새로운 컨텍스트를 갖는다.
+
+때문에 이전 스레드의 컨텍스트에 접근할 수 없습니다.
+
+<br>
+
+## 🖥️ 해결책: TaskDecorator 사용하기
+
+Spring 은 비동기 작업을 실행하기 전에 새 스레드에 컨텍스트를 복사할 수 있는 `TaskDecorator` 를 제공합니다.
+
+### 1-1. ThreadPoolTaskExecutor 구성하기
+
+```java
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.scheduling.annotation.EnableAsync;
+import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
+import org.springframework.web.context.request.RequestAttributes;
+import org.springframework.web.context.request.RequestContextHolder;
+
+import java.util.concurrent.Executor;
+
+@EnableAsync
+@Configuration
+public class AsyncConfig {
+    
+    @Bean(name = "asyncExecutor")
+    public Executor asyncExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+        
+        // 애플리케이션 요구사항에 맞게 스레드 풀 구성... (생략)
+        
+        // 새 스레드에 요청 컨텍스트를 복사하기 위한 TaskDecorator 설정!
+        executor.setTaskDecorator(task -> {
+            RequestAttributes requestAttributes = RequestContextHolder.currentRequestAttributes();
+            return () -> {
+                try {
+                    RequestContextHolder.setRequestAttributes(requestAttributes);
+                    task.run();
+                } finally {
+                    RequestContextHolder.resetRequestAttributes();
+                }
+            };
+        });
+        
+        executor.initialize();
+        return executor;
+    }
+}
+```
+
+### 1-2. CompletableFuture 사용하기
+
+CompletableFuture 를 직접 사용할 때는 커스텀 Executor 를 활용합니다.
+
+```java
+@Autowired
+@Qualifier("asyncExecutor")
+private Executor asyncExecutor;
+
+public CompletableFuture<List<User>> findAllUsersAsync() {
+    return CompletableFuture.supplyAsync(() -> {
+        return userRepository.findAll(); // 쿼리 카운트 지점.
+    }, asyncExecutor);                   // 커스텀 Executor 지정.
+}
+```
+
+### 1-3. @Async 어노테이션 사용하기
+
+`@Async` 어노테이션을 사용할 때는 구성된 Executor 를 명시적으로 지정합니다.
+
+```java
+@Async("asyncExecutor")  // Bean 이름을 명시적으로 지정.
+public CompletableFuture<User> findUserByIdAsync(Long id) {
+    return CompletableFuture.completedFuture(
+        userRepository.findById(id).orElse(null) // 쿼리 카운트 지점.
+    );
+}
+```
+
+<br>
+
+## 🖥️ WebFlux/Reactor 환경
+
+(WIP)