Kotlin 언어로 JVM 환경에서 개발할 때 사용할 공용 라이브러리
KDoc 작성 지침: doc/Kdoc_Instruction.md
Kotlin 언어를 배우고, 사용하면서, Backend 개발에 자주 사용하는 기술, Coroutines 등 기존 라이브러리가 제공하지 않는 기능 들을 개발해 왔습니다.
-
Kotlin 의 장점을 최대화 할 수 있는 추천할 만한 코딩 스타일을 제공할 수 있는 기능을 제공합니다.
bluetape4k-core의 assertions, required 같은 기능bluetape4k-measured의 조합 가능한 단위 타입(Units)과 측정값(Measure) 제공
-
기존 Java 라이브러리를 무지성으로 사용하지 않고, 좀 더 효과적으로 사용할 수 있도록 개선한 기능을 제공합니다.
bluetape4k-core의 LZ4, Zstd 등 압축 기능 개선bluetape4k-redis의 lettuce, redisson 용 Codec 제공 (공식 Codec 보다 성능이 월등함)
-
테스트를 좀 더 완성도 있게 하기 위한 기능을 제공합니다.
bluetape4k-junit5다양한 테스트 기법을 Junit5 기반으로 제공합니다.bluetape4k-testcontainers다양한 서비스들을 테스트 환경에서 사용할 수 있도록 합니다.
-
Kotlin Coroutines 등 Async/Non-Blocking 방식의 개발을 지원하는 기능을 제공합니다.
bluetape4k-coroutinesCoroutine 을 사용할 때 유용한 기능을 제공합니다.bluetape4k-feigh,bluetape4k-retrofit2등은 HTTP 통신 시 async/non-blocking을 위해 Coroutines 을 사용하도록 합니다
-
AWS SDK 사용 시 성능을 위해 개선한 기능을 제공합니다.
bluetape4k-awsAWS Java SDK v2 기반으로 DynamoDB, S3, SES, SNS, SQS, KMS, CloudWatch, Kinesis, STS 등을 Async/Non-Blocking 방식으로 사용할 수 있도록 합니다.- S3 TransferManager를 활용한 대용량 파일 전송 성능 최적화를 제공합니다.
-
AWS Kotlin SDK 를 사용을 편리하게 하기 위한 기능을 제공합니다.
bluetape4k-aws-kotlinAWS Kotlin SDK 기반으로 nativesuspend함수를 기본 제공하여 Coroutines 환경에서 편리하게 사용할 수 있습니다.
-
MSA의 필수인 Resilience4j 에 대한 Kotlin Coroutines 지원을 강화했습니다.
bluetape4k-resilience4jResilience4j 를 사용할 때 Kotlin Coroutines 를 사용할 수 있도록 지원합니다.- 또한 Coroutines 용 Cache를 추가하여, Coroutines 환경에서도 API 호출 결과를 캐싱할 수 있도록 지원합니다.
-
Redis 를 댜양한 방식에서 사용할 수 있도록 지원합니다.
bluetape4k-redis는 Lettuce, Redisson 용 고성능 Codec 을 제공합니다.- Redisson의 다양한 Lock 기능을 Coroutines 환경에서도 사용할 수 있도록 지원합니다.
- Redis를 분산 캐시로만 사용하는 것이 아니라, Near Cache로 사용할 수 있도록 하여 더욱 성능을 높힐 수 있도록 합니다.
그 외 현업에서 마주쳤던 많은 문제를 해결하는 과정에서 필요로 하는 기능 들을 제공합니다.
앞으로도 필요한 기능들이 있다면 Issue 에 제안 주시기 바랍니다.
- Java: 21 (JVM Toolchain)
- Kotlin: 2.3 (Language & API Version)
- Spring Boot: 3.4.0+ / 4.0.0+
- Kotlin Exposed: 1.0.0+
- 데이터베이스: H2, PostgreSQL, MySQL
Bluetape4k는 기능별로 분리된 멀티 모듈 Gradle 프로젝트입니다.
- core: 핵심 유틸리티 (assertions, required, 컬렉션(BoundedStack, RingBuffer, PaginatedList, Permutation), Wildcard 패턴 매칭, XXHasher 등)
- coroutines: Kotlin Coroutines 확장 (DeferredValue, Flow extensions, AsyncFlow)
- logging: 로깅 관련 기능
- bom: Bill of Materials (의존성 관리)
- io: 파일 I/O, 압축(LZ4, Zstd, Snappy, Zip), 직렬화(Kryo, Fory), ZIP 빌더/유틸리티, Okio 통합 (Tink 기반 암호화 Sink/Source 포함)
- okio: Okio 기반 I/O 확장 — Buffer/Sink/Source 유틸리티, Base64, Channel, Cipher, Compress, Coroutines, Jasypt/Tink 암호화 Sink/Source
- **jackson2/jackson3
**: Jackson 2.x/3.x 통합 — 바이너리(CBOR, Ion, Smile) 및 텍스트(CSV, YAML, TOML) 포맷 포함 (구
jackson-binary/text,jackson3-binary/text통합됨) - json: JSON 처리
- csv: CSV 처리
- feign: Feign HTTP 클라이언트 (Coroutines 지원)
- retrofit2: Retrofit2 HTTP 클라이언트 (Coroutines 지원)
- protobuf: Protobuf 유틸리티 (Timestamp/Duration/Money 변환, ProtobufSerializer)
- grpc: gRPC 서버/클라이언트 추상화 (
bluetape4k-protobuf포함) crypto: 암호화 기능 (Jasypt 기반 PBE, BouncyCastle) — Deprecated (bluetape4k-tink로 대체)- tink: Google Tink 기반 현대적 암호화 — AEAD, Deterministic AEAD, MAC, Digest, 통합 Encryptor (
TinkEncryptor), OkioTinkEncryptSink/TinkDecryptSource - http: HTTP 유틸리티
- netty: Netty 통합
- avro: Apache Avro
- fastjson2: FastJSON2
- vertx: Vert.x 단일 통합 모듈 — 핵심 기능, SQL 클라이언트, Resilience4j 통합 포함 (구
vertx/core,vertx/sqlclient,vertx/resilience4j통합됨)
각 서비스마다 3단계 API 패턴 제공: sync → async (CompletableFuture) → coroutines (suspend)
- bluetape4k-aws: AWS Java SDK v2 기반 단일 통합 모듈 — DynamoDB, S3(TransferManager), SES, SNS, SQS, KMS, CloudWatch/Logs, Kinesis, STS 포함. 각 서비스의 coroutines 확장 (
XxxAsyncClientCoroutinesExtensions.kt) 제공 - bluetape4k-aws-kotlin: AWS Kotlin SDK 기반 단일 통합 모듈 — native
suspend함수 기본 제공 (.await()변환 불필요). DynamoDB, S3, SES/SESv2, SNS, SQS, KMS, CloudWatch/Logs, Kinesis, STS 포함. DSL 지원 (metricDatum {},inputLogEvent {},stsClientOf {}등)
- exposed: umbrella 모듈 —
exposed-core+exposed-dao+exposed-jdbc묶음 (하위 호환) - exposed-core: JDBC 없이 사용 가능한 핵심 기능 — 압축/암호화/직렬화 컬럼 타입, ID 생성 확장,
HasIdentifier,ExposedPage - exposed-dao: DAO 엔티티 확장 —
EntityExtensions,StringEntity, 커스텀 IdTable (KsuidTable,SnowflakeIdTable,SoftDeletedIdTable등) - exposed-jdbc: JDBC 전용 —
ExposedRepository,SoftDeletedRepository,SuspendedQuery,VirtualThreadTransaction - exposed-r2dbc: Exposed + R2DBC (reactive,
ExposedR2dbcRepository) - exposed-jdbc-redisson: Exposed JDBC + Redisson (분산 락)
- exposed-r2dbc-redisson: Exposed R2DBC + Redisson (분산 락)
- exposed-jackson2/jackson3: Exposed JSON 컬럼 지원 (Jackson 2.x/3.x)
- exposed-fastjson2: Exposed FastJSON2 JSON 컬럼 지원
- exposed-jasypt: Exposed Jasypt 암호화 컬럼
- exposed-tink: Exposed 암호화 컬럼 (Google Tink AEAD/Deterministic AEAD)
- exposed-measured: Exposed 쿼리 실행 시간 측정 (Micrometer 통합)
- exposed-jdbc-tests: JDBC 기반 테스트 공통 인프라
- exposed-r2dbc-tests: R2DBC 기반 테스트 공통 인프라
- exposed-postgresql: PostgreSQL 전용 Exposed 확장 — PostGIS 공간 데이터(
POINT/POLYGON), pgvector 벡터 검색(VECTOR(n)), TSTZRANGE 시간 범위 컬럼 타입; H2 fallback 지원 - exposed-mysql8: MySQL 8.0 전용 Exposed 확장 — GIS 공간 데이터(8종), JTS 기반 Geometry 컬럼,
ST_Contains/ST_Distance등 공간 함수; MySQL Internal Format WKB 변환 - exposed-duckdb: DuckDB JDBC 통합 —
DuckDBDialect(PostgreSQL 상속),DuckDBDatabase팩토리(인메모리/파일/읽기전용),suspendTransaction,queryFlow - exposed-bigquery: Google BigQuery REST API 통합 — H2(PostgreSQL 모드)로 SQL 생성 후 BigQuery REST 실행,
BigQueryContext(SELECT/INSERT/UPDATE/DELETE/DDL),BigQueryResultRow(Column 참조 타입 안전 접근), suspend/Flow API - exposed-jdbc-lettuce: Exposed JDBC + Lettuce Redis 캐시 — Read-through/Write-through/Write-behind,
AbstractJdbcLettuceRepository, 코루틴 네이티브AbstractSuspendedJdbcLettuceRepository - exposed-r2dbc-lettuce: Exposed R2DBC + Lettuce Redis 캐시 — 코루틴 네이티브 Read-through/Write-through/Write-behind,
AbstractR2dbcLettuceRepository - hibernate/hibernate-reactive: Hibernate ORM 통합
- hibernate-cache-lettuce: Hibernate 2nd Level Cache + Lettuce NearCache (Caffeine L1 + Redis L2) —
LettuceNearCacheRegionFactory,LettuceNearCacheStorageAccess, region별 TTL 오버라이드, 15가지 코덱 지원 - mongodb: MongoDB Kotlin Coroutine Driver 확장 —
mongoClient {}DSL,findFirst,exists,upsert,findAsFlow,documentOf {}, Aggregation Pipeline DSL - r2dbc: R2DBC 지원
- cassandra: Cassandra 드라이버
- jdbc: JDBC 유틸리티
- redis: Lettuce/Redisson umbrella 모듈 (하위 호환)
- lettuce: Lettuce 클라이언트, 고성능 Codec (Jdk/Kryo/Fory × GZip/LZ4/Snappy/Zstd),
RedisFuture→ Coroutines 어댑터, 분산 Primitive (Lock, Semaphore, AtomicLong, Leader Election),MapLoader/MapWriter/LettuceLoadedMap(Read-through/Write-through/Write-behind), BloomFilter/CuckooFilter (Lua 스크립트 기반, RedisBloom 불필요), HyperLogLog (PFADD/PFCOUNT/PFMERGE) - redisson: Redisson 클라이언트, Codec, Memorizer, NearCache (
RLocalCachedMap), Leader Election (Coroutines 지원)
- lettuce: Lettuce 클라이언트, 고성능 Codec (Jdk/Kryo/Fory × GZip/LZ4/Snappy/Zstd),
- kafka: Kafka 클라이언트
- resilience4j: Resilience4j + Coroutines, Coroutines Cache
- bucket4j: Rate limiting
- micrometer: 메트릭
- opentelemetry: 분산 추적
플러그인 방식으로 백엔드를 교체할 수 있는 캐시 추상화 레이어입니다.
- cache: umbrella 모듈 (cache-core + hazelcast + redisson + lettuce)
- cache-core: JCache 추상화 + Caffeine/Cache2k/Ehcache 로컬 캐시 (구
cache-local병합) —AsyncCache,SuspendCache,NearCache,SuspendNearCache, Memorizer 구현체, testFixtures 6종 추상 테스트 - cache-hazelcast: Hazelcast 분산 캐시 + Caffeine 2-Tier Near Cache (구
cache-hazelcast-near병합) - cache-redisson: Redisson 분산 캐시 + Caffeine 2-Tier Near Cache (구
cache-redisson-near병합) - cache-lettuce: Lettuce(Redis) 기반 분산 캐시 —
LettuceNearCacheConfig, RESP3 CLIENT TRACKING 기반 자동 invalidation
- bluetape4k-spring-boot3 (
spring-boot3/core): Spring Boot 3 기반 공통 기능 통합 모듈 — Spring core 유틸리티, WebFlux + Coroutines, Retrofit2 통합, 테스트 유틸리티 포함 (구spring/core,spring/webflux,spring/retrofit2,spring/tests통합됨) - data-redis: Spring Data Redis 고성능 직렬화 —
RedisBinarySerializer,RedisCompressSerializer,redisSerializationContext {}DSL - cassandra: Spring Data Cassandra
- mongodb: Spring Data MongoDB Reactive —
ReactiveMongoOperations코루틴 확장, Criteria/Query/Update infix DSL - r2dbc: Spring Data R2DBC
- exposed-jdbc (
bluetape4k-spring-boot3-exposed-jdbc): Exposed DAO 엔티티 기반 Spring Data JDBC Repository — PartTree 쿼리, QBE, Page/Sort 지원 - exposed-r2dbc (
bluetape4k-spring-boot3-exposed-r2dbc): Exposed R2DBC DSL 기반 코루틴 Spring Data Repository — suspend CRUD, Flow 지원 - exposed-jdbc-demo (
bluetape4k-spring-boot3-exposed-jdbc-demo): Exposed DAO + Spring Data JDBC + Spring MVC 통합 데모 - exposed-r2dbc-demo (
bluetape4k-spring-boot3-exposed-r2dbc-demo): Exposed R2DBC + suspend Repository + Spring WebFlux 통합 데모 - hibernate-lettuce (
bluetape4k-spring-boot3-hibernate-lettuce): Hibernate 2nd Level Cache + Lettuce NearCache Spring Boot Auto-Configuration — Properties 바인딩, Micrometer Metrics, Actuator Endpoint - hibernate-lettuce-demo (
bluetape4k-spring-boot3-hibernate-lettuce-demo): Hibernate Lettuce NearCache + Spring MVC 통합 데모
Spring Data JPA는
data/hibernate모듈로 이동했습니다.
Spring Boot 4.x 전용 모듈. Spring Boot 3 모듈과 독립적으로 사용 가능합니다.
BOM 적용 주의:
dependencyManagement { imports }대신implementation(platform(...))방식으로 적용해야 KGP 2.3.x와 충돌 없이 빌드됩니다.
- core (
bluetape4k-spring-boot4-core): Spring Boot 4 기반 공통 기능 — WebFlux + Coroutines, RestClient DSL (suspendGet,suspendPost등), Jackson 2 커스터마이저, Retrofit2 통합, WebTestClient 테스트 유틸리티 - data-redis: Spring Data Redis 고성능 직렬화 —
RedisBinarySerializer,RedisCompressSerializer,redisSerializationContext {}DSL - cassandra: Spring Data Cassandra 코루틴 확장
- mongodb: Spring Data MongoDB Reactive 코루틴 확장, Criteria/Query/Update infix DSL
- r2dbc: Spring Data R2DBC 코루틴 확장
- cassandra-demo: Cassandra 사용 예제
- exposed-jdbc (
bluetape4k-spring-boot4-exposed-jdbc): Exposed DAO 엔티티 기반 Spring Data JDBC Repository — PartTree 쿼리, QBE, Page/Sort 지원 (Spring Boot 4 BOM) - exposed-r2dbc (
bluetape4k-spring-boot4-exposed-r2dbc): Exposed R2DBC DSL 기반 코루틴 Spring Data Repository — suspend CRUD, Flow 지원 (Spring Boot 4 BOM) - exposed-jdbc-demo (
bluetape4k-spring-boot4-exposed-jdbc-demo): Exposed DAO + Spring Data JDBC + Spring MVC 통합 데모 (Spring Boot 4 BOM) - exposed-r2dbc-demo (
bluetape4k-spring-boot4-exposed-r2dbc-demo): Exposed R2DBC + suspend Repository + Spring WebFlux 통합 데모 (Spring Boot 4 BOM) - hibernate-lettuce (
bluetape4k-spring-boot4-hibernate-lettuce): Hibernate 2nd Level Cache + Lettuce NearCache Spring Boot Auto-Configuration (Spring Boot 4 BOM) - hibernate-lettuce-demo (
bluetape4k-spring-boot4-hibernate-lettuce-demo): Hibernate Lettuce NearCache + Spring MVC 통합 데모 (Spring Boot 4 BOM)
- bluetape4k-geo (
utils/geo): 지리 정보 처리 단일 통합 모듈 — geocode(Bing/Google), geohash, geoip2(MaxMind) 포함 (구utils/geocode,utils/geohash,utils/geoip2통합됨) - idgenerators: ID 생성기 —
Uuid(V1~V7 통일 API),ULID,Ksuid(Seconds/Millis),Snowflakers통일 팩토리,Flake,Hashids등 다양한 ID 생성 알고리즘 제공 - images: 이미지 처리
- javatimes: 날짜/시간 유틸리티
- jwt: JWT 처리
- leader: Leader 선출
- math: 수학 유틸리티
- measured: 조합 가능한 단위 타입(
Units)과 측정값(Measure) 기반으로, 복합 단위(m/s,kg*m/s^2)를 타입 안전하게 표현 - money: Money API
- mutiny: Mutiny reactive 통합
units: 단위 표현 value class — Deprecated (bluetape4k-measured의 기능으로 통합)
- junit5: JUnit 5 확장 및 유틸리티
- testcontainers: Testcontainers 지원 (Redis, Kafka, DB 등)
- virtualthread: Java 21/25 Virtual Thread 지원
- timefold: Timefold Solver + Exposed 통합
라이브러리 사용 방법을 보여주는 예제 모듈입니다. 배포되지 않습니다.
- coroutines-demo: Kotlin Coroutines 사용 예제
- jpa-querydsl-demo: JPA + QueryDSL 사용 예제
- redisson-demo: Redisson 사용 예제
- virtualthreads-demo: Java Virtual Thread 사용 예제
더 이상 유지보수되지 않는 모듈입니다. 빌드에서 제외되었으며 삭제될 예정입니다.
vertx-coroutines: Vert.x + Coroutines —bluetape4k-vertx로 통합됨vertx-sqlclient: Vert.x SQL Client —bluetape4k-vertx로 통합됨vertx-webclient: Vert.x Web Client —bluetape4k-vertx로 통합됨mapstruct: MapStruct 통합 — 미사용으로 폐기bloomfilter: Bloom Filter — 사용 빈도 낮아 폐기captcha: CAPTCHA 생성 — 사용 빈도 낮아 폐기logback-kafka: Logback Kafka Appender — 사용 빈도 낮아 폐기nats: NATS 메시징 — 사용 빈도 낮아 폐기javers: JaVers 감사 로그 — 사용 빈도 낮아 폐기tokenizer: 한국어/일본어 형태소 분석기 — 사용 빈도 낮아 폐기ahocorasick: 문자열 검색 (Aho-Corasick) — 사용 빈도 낮아 폐기lingua: 언어 감지 — 사용 빈도 낮아 폐기naivebayes: Naive Bayes 분류기 — 사용 빈도 낮아 폐기mutiny-examples: Mutiny 사용 예제 — 폐기
# 전체 프로젝트 빌드
./gradlew clean build
# 특정 모듈만 빌드
./gradlew :bluetape4k-coroutines:build
# 테스트 제외하고 빌드
./gradlew build -x test# 전체 테스트 실행
./gradlew test
# 특정 모듈 테스트
./gradlew :bluetape4k-io:test
# 특정 테스트 클래스 실행
./gradlew test --tests "io.bluetape4k.io.CompressorTest"
# 상세 로그와 함께 테스트
./gradlew test --info# Detekt 정적 분석 실행
./gradlew detekt버전 확인은 gradle.properties 파일에서 확인
projectGroup=io.github.bluetape4k
baseVersion=1.5.0
snapshotVersion=-SNAPSHOT./gradlew publishAggregationToCentralSnapshots --no-daemon --no-configuration-cache# 기본 병렬도(centralSnapshotsParallelism=8)로 SNAPSHOT 배포
./gradlew publishAggregationToCentralSnapshots
# 병렬도를 낮춰 서버 부담을 줄이고 싶을 때
./gradlew -PcentralSnapshotsParallelism=4 publishAggregationToCentralSnapshots- 루트 집계 task는
publishAggregationToCentralSnapshots입니다. - SNAPSHOT 배포는 release 와 달리 ZIP 1회 업로드가 아니라 file-by-file 업로드를 수행합니다.
- 따라서 모듈 수가 많을수록
PUT요청이 많이 발생하는 것이 정상입니다. - 업로드 대상은
workshop/**,examples/**,-demo모듈을 제외한 publishable modules 입니다. - Snapshot 저장소는
https://central.sonatype.com/repository/maven-snapshots/입니다. - 병렬도는
centralSnapshotsParallelismproperty 로 조절할 수 있습니다. 기본값은8입니다.
# snapshotVersion을 제거하고 RELEASE 배포
./gradlew publishAggregationToCentralPortal -PsnapshotVersion= --no-daemon --no-configuration-cache- 루트 집계 task는
publishAggregationToCentralPortal입니다. - RELEASE 배포는 NMCP aggregation ZIP 을 만들어 Central Portal Publisher API 로 업로드합니다.
- SNAPSHOT과 달리 artifact 파일들을 개별
PUT하지 않으므로 요청 수가 훨씬 적습니다. - 업로드 대상은
workshop/**,examples/**,-demo모듈을 제외한 publishable modules 입니다. - 동일 RELEASE 버전은 재배포할 수 없으므로 실패 시
baseVersion을 올려야 합니다.
# Sonatype Central Portal 계정
central.user=your-central-portal-username
central.password=your-central-portal-password
# 권장: In-memory PGP signing
signingUseGpgCmd=false
signingKeyId=YOUR_KEY_ID
signingKey=-----BEGIN PGP PRIVATE KEY BLOCK-----\n...\n-----END PGP PRIVATE KEY BLOCK-----
signingPassword=YOUR_KEY_PASSPHRASE
# Maven Central Snapshots 업로드 병렬도 (기본값: 8)
centralSnapshotsParallelism=8- 기존
publishAggregationToCentralPortalSnapshots는 deprecated alias 이며,publishAggregationToCentralSnapshots사용을 권장합니다. publishAllPublicationsToCentralPortalSnapshots/publishAllPublicationsToCentralSnapshots같은 개별 task 직접 실행 대신 루트 집계 task 사용을 권장합니다.- SNAPSHOT이 느리거나 요청이 과도해 보이면
centralSnapshotsParallelism값을4,8,12정도 범위에서 조절해 보세요. - RELEASE는 aggregation ZIP 업로드 경로를 사용하므로 SNAPSHOT과 동작 방식이 다릅니다.
AI 에이전트나 긴 터미널 세션에서 원시 git/Gradle 출력을 바로 열기 전에, 아래 요약 명령을 먼저 사용하는 것을 권장합니다.
# 저장소 상태 요약
./bin/repo-status
# 파일별 diff 변경량 요약
./bin/repo-diff
# Gradle 테스트/빌드 로그 요약
./bin/repo-test-summary -- ./gradlew :05-exposed-dml:01-dml:test기본 흐름은 "요약 먼저, 필요한 파일이나 태스크만 원본 출력 확인"입니다.
