10 KiB
Agents.md
This file is for AI agents modifying or consuming this repository. Keep it concise, factual, and synchronized with source code.
Repository Identity
- Project:
KriCommon - Type: Java 17 Spring Boot starter/library
- Build: Gradle
java-library+maven-publish - Maven coordinates:
com.kri.common:starter:<commonVer> - Version source:
build.gradlevariablecommonVer - Main source root:
src/main/java - Auto-configuration registration:
src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
Package Contract
com.kri.common.autoconfigure: Spring Boot auto-configurations and configuration property classes.com.kri.common.feature: Public API intended for service code to import directly.com.kri.common.runtime: Runtime implementation assembled by auto-configuration. Treat as internal unless there is no public feature API.com.kri.common.endpoint: Optional common controllers exposed by configuration.
When adding features, prefer exposing stable service-facing types under feature and wiring implementation under autoconfigure/runtime.
Build Commands
./gradlew compileJava
./gradlew publishReleasePublicationToGiteaRepository
On Windows PowerShell, use:
.\gradlew.bat compileJava
.\gradlew.bat publishReleasePublicationToGiteaRepository
Publishing requires giteaUser/giteaToken Gradle properties or GITEA_USER/GITEA_TOKEN environment variables. The publish task depends on checkGiteaPackageVersionNotExists.
Dependency Model
The library intentionally uses many compileOnly Spring dependencies. Do not assume a class is present at runtime unless the consuming service has the matching starter.
Important dependency categories:
- Spring Boot BOM:
org.springframework.boot:spring-boot-dependencies:3.5.7 - Java: 17
- JWT: JJWT
0.12.6 - JSON: Jackson Databind
2.17.0 - Excel: Apache POI
5.5.1 - Spring Web/Security/JPA/Redis/AOP/Swagger dependencies are mostly
compileOnly
When adding auto-configuration, use @ConditionalOnClass, @ConditionalOnBean, @ConditionalOnMissingBean, and property conditions to avoid breaking consumers that do not include optional starters.
Configuration Prefixes
Only use kri.* prefixes.
Known prefixes:
kri.auth.jwtkri.auth.apikeykri.securitykri.swaggerkri.webkri.web.mdckri.http.bypasskri.rediskri.schedulingkri.error.expose
Auto-Configurations
Declared imports:
com.kri.common.autoconfigure.auth.jwt.JwtAutoConfigurationcom.kri.common.autoconfigure.auth.apikey.ApiKeyJpaAutoConfigurationcom.kri.common.autoconfigure.auth.apikey.ApiKeyPreloadAutoConfigurationcom.kri.common.autoconfigure.auth.apikey.ApiKeyAdminAutoConfigurationcom.kri.common.autoconfigure.security.KriSecurityAutoConfigurationcom.kri.common.autoconfigure.web.CommonWebAutoConfigurationcom.kri.common.autoconfigure.swagger.KriSwaggerAutoConfigurationcom.kri.common.autoconfigure.redis.CommonRedisAutoConfigurationcom.kri.common.autoconfigure.scheduling.CommonSchedulingAutoConfigurationcom.kri.common.autoconfigure.http.bypass.BypassAutoConfiguration
If a new auto-configuration must be active for consumers, add it to AutoConfiguration.imports.
Feature Map
JWT
- Public classes:
JwtService,JwtUserClaimsDto - Config:
kri.auth.jwt - Auto-config:
JwtAutoConfiguration - Main operations: generate access/refresh tokens, parse token, convert claims to
JwtUserClaimsDto, convert token/DTO to Spring SecurityAuthentication - Claims DTO fields:
userId,userCmpn,userTeam,userName,userRole
Security note: default secrets in source are not production-safe. Documentation and examples should instruct consumers to override secrets.
API Key Authentication
- Public extension point:
ApiKeyUserClaimsProvider - Runtime filter:
ApiKeyAuthFilter - Runtime preload provider:
PreloadedApiKeyUserClaimsProvider - Config:
kri.auth.apikey - Optional endpoint:
ApiKeyAdminController - Admin endpoints:
POST /internal/apikey/reloadGET /internal/apikey/cache
Behavior:
- API key is read from
kri.auth.apikey.header-name, defaultX-API-Key. - If authentication already exists in
SecurityContextHolder, API key filter does nothing. - If provider resolves a key, the result is converted to
AuthenticationusingJwtService.toAuthentication. - Preloaded provider returns empty cache when
service-codeis blank. - Admin endpoint is exposed only when
admin-api-enabled=trueand the preload provider exists. - Admin endpoint has IP allowlist enforcement.
Security
- Auto-config:
KriSecurityAutoConfiguration - Config:
kri.security - Default enabled:
true - Registers
JwtAuthenticationFilterand defaultSecurityFilterChainonly when consumer has noSecurityFilterChainbean. - Filter order inside the default chain: optional
ApiKeyAuthFilter, thenJwtAuthenticationFilter, both beforeUsernamePasswordAuthenticationFilter. - Default chain disables HTTP Basic and CSRF, uses stateless sessions, optionally enforces
allowed-ips, permitspublic-paths, authenticates all other requests. - When
kri.security.allowed-ipsis non-empty,public-pathsrequire an allowed client IP but no authentication; all other paths require both allowed IP and authentication. - Method security is enabled with JSR-250 and pre/post annotations.
Web
- Auto-config:
CommonWebAutoConfiguration - Config:
kri.web.enabled, defaulttrue - MDC config:
kri.web.mdc.enabled, defaulttrue - Registers:
ErrorAdviceTraceFilterServiceMdcAspectwhen AspectJ is present and MDC is enabled- MVC interceptor for handler MDC when MDC is enabled
RequestUserContextArgumentResolverwhenJwtServicebean existsCodeEnumConverter- global CORS mapping
Swagger/OpenAPI
- Auto-config:
KriSwaggerAutoConfiguration - Config:
kri.swagger - Default enabled:
true - Requires OpenAPI/springdoc classes on classpath.
- Defines security schemes
BearerAuthandApiKeyAuth. - Creates
GroupedOpenApinamedkriGroupedOpenApi, groupkri-api, paths/api/**and/internal/**. - Uses
kri.swagger.base-packagefor package scanning. - Adds API key admin package when
kri.auth.apikey.admin-api-enabled=true. - Registers
SwaggerIpFilterfor/swagger-ui/*,/v3/api-docs/*,/swagger-ui.html. - Adds CodeEnum model/property/parameter OpenAPI support.
Redis
- Auto-config:
CommonRedisAutoConfiguration - Config:
kri.redis.enabled - Default enabled:
false - Requires
RedisTemplateclass andRedisConnectionFactorybean. - Registers
RedisQueueHelper.
HTTP Bypass
- Public classes:
BypassClient,BypassRequest,BypassResponse,BypassContext,BypassForwardOptions,BypassRequestCustomizer,BypassResponseCustomizer - Runtime implementation:
DefaultBypassClient - Auto-config:
BypassAutoConfiguration - Config:
kri.http.bypass - Default enabled:
false - Requires servlet web classes.
- Consumer services define bypass controllers explicitly and call
BypassClient.forward(targetName, request, body). - Targets are configured under
kri.http.bypass.targets.<targetName>withbase-url, optionalstrip-prefix,allowed-paths,request-customizers,response-customizers, and timeout. - Target customizers are referenced by Spring bean name and run before per-request customizers from
BypassForwardOptions. - Response bodies are returned as
byte[]; preserve targetContent-Typeso frontends can parse JSON/text/blob correctly. - Do not allow frontends to pass arbitrary full target URLs. Keep target base URLs server-side and use
allowed-paths. - Do not forward hop-by-hop headers such as
Host,Content-Length,Transfer-Encoding,Connection,Keep-Alive,Upgrade,Proxy-Authenticate,Proxy-Authorization,TE, andTrailer.
Scheduling
- Auto-config:
CommonSchedulingAutoConfiguration - Config:
kri.scheduling.enabled - Default enabled:
false - Enables Spring scheduling.
Excel
- Public classes:
ExcelMapper,ExcelUtil,ExcelColumn,StreamingReadOptions - Supports DTO workbook read/write, map workbook read/write, SXSSF streaming write, SAX streaming read.
ExcelColumnfields:header,order,width.StreamingReadOptions.DEFAULT: sheet index0, header row index1, identity header normalizer.
JSON
- Public class:
JsonUtil - All methods require an explicit
ObjectMapper. - Do not introduce hidden global ObjectMapper state without a deliberate API decision.
Date/Time
- Public classes:
DateTimeUtil,LenientLocalDateTime,LenientLocalDateTimeDeserializer - KST zone constant:
Asia/Seoul - UTC constant:
ZoneOffset.UTC
Enum
- Public classes:
CodeEnum,CodeEnumUtils - Runtime MVC converter:
CodeEnumConverter - JPA base converter:
AbstractCodeEnumConverter - Swagger metadata support exists in
runtime.swagger.
JPA
- Public classes:
BaseUuidEntity,AbstractCodeEnumConverter,EntityColumnAccessor - API key JPA runtime entities/repository are internal to
runtime.auth.apikey.persistence.
Utilities
FileUtil: filename sanitizing, extension extraction, path-like filename extractionStringUtil: null/blank checks, normalization, basic validation, escapingNumericUtil: numeric checks and safe parsingCollectionUtil: empty checksCommonUtil: UUID helpers
Coding Rules For Agents
- Do not move public APIs out of
featurewithout a compatibility plan. - Do not make optional Spring integrations unconditional.
- Do not add new configuration prefixes outside
kri.*. - Do not hard-code service-specific secrets or credentials in new code or docs.
- Do not directly expose raw API keys in endpoints or logs.
- Prefer
@ConditionalOnMissingBeanfor beans consumers may override. - Prefer explicit examples in README that use placeholder secrets and local URLs.
- Keep README human-readable and keep this file agent-readable.
- If changing behavior, update README and this file in the same change.
- Run
.\gradlew.bat compileJavabefore finalizing when possible.
Verification Checklist
.\gradlew.bat compileJava- Confirm any new auto-config is listed in
AutoConfiguration.imports. - Confirm property names in docs match
@ConfigurationPropertiesfields. - Confirm optional integrations have classpath/bean/property conditions.
- Confirm public examples import from
com.kri.common.feature.*unless intentionally documenting internals.