test/COMMON_CODE_CACHE_REDIS.md

공통코드 Redis 캐시 시스템 - DanielLee

요구사항 검토

1. API를 통해 공통코드 제공

• 구현 완료: CommonCodeApiController에서 전체 공통코드 조회 API 제공

  GET /api/code
  → 모든 공통코드 조회
  

• 추가 구현: 캐시 갱신 및 상태 확인 API

  POST /api/code/cache/refresh     → 캐시 갱신
  GET  /api/code/cache/status      → 캐시 상태 확인
  

---

2. 애플리케이션 로딩시 Redis 캐시에 올리기

• 구현 완료: CommonCodeCacheManager 클래스 생성

초기화 메커니즘

@Component
@RequiredArgsConstructor
public class CommonCodeCacheManager {

  @EventListener(ApplicationReadyEvent.class)
  public void initializeCommonCodeCache() {
    // 애플리케이션 완전히 시작된 후 공통코드를 Redis에 미리 로드
    List<Basic> allCommonCodes = commonCodeService.getFindAll();
    // @Cacheable이 자동으로 Redis에 캐시함
  }
}

동작 흐름

1. 애플리케이션 시작
2. Spring이 모든 Bean 생성 완료 (ApplicationReadyEvent 발생)
3. CommonCodeCacheManager.initializeCommonCodeCache() 실행
4. commonCodeService.getFindAll() 호출 (DB에서 조회)
5. @Cacheable(value = "commonCodes") 에노테이션이 결과를 Redis에 저장

---

3. 공통코드 변경시 데이터 갱신

자동 갱신

• 등록 (CREATE): @CacheEvict → 캐시 전체 삭제
• 수정 (UPDATE): @CacheEvict → 캐시 전체 삭제
• 삭제 (DELETE): @CacheEvict → 캐시 전체 삭제
• 순서 변경: @CacheEvict → 캐시 전체 삭제

@CacheEvict(value = "commonCodes", allEntries = true)
public ResponseObj save(CommonCodeDto.AddReq req) {
  // 공통코드 저장
  // ↓
  // 캐시 전체 삭제 (다음 조회 시 DB에서 새로 로드)
}

수동 갱신 (관리자)

POST /api/code/cache/refresh

• 공통코드 설정이 변경된 후 API를 호출하여 캐시를 강제 갱신

캐시 상태 모니터링

GET /api/code/cache/status
→ 응답: { "data": 150 }  // 캐시된 공통코드 150개

---

전체 아키텍처

┌─────────────────────────────────────────────────────────┐
│   클라이언트 요청                                         │
└──────────────────┬──────────────────────────────────────┘
                   │
        ┌──────────▼──────────┐
        │ CommonCodeApiController
        └──────────┬──────────┘
                   │
         ┌─────────┴──────────┐
         │                    │
    ┌────▼─────┐      ┌──────▼────────────┐
    │ 조회 API │      │ 캐시 관리 API      │
    │ (GET)    │      │(POST, GET)         │
    └────┬─────┘      └──────┬────────────┘
         │                   │
         │          ┌────────▼──────────┐
         │          │CommonCodeCacheManager
         │          │(캐시 초기화/갱신)  │
         │          └────────┬──────────┘
         │                   │
    ┌────▼─────────────────┬─▼────┐
    │ CommonCodeService    │      │
    │ (@Cacheable)         │      │
    │ (@CacheEvict)        │      │
    └────┬──────────────────┴──────┘
         │
    ┌────▼──────────┐
    │ Redis 캐시    │
    │ (공통코드)    │
    └────┬──────────┘
         │
    ┌────▼──────────┐
    │ PostgreSQL DB │
    │ (공통코드)    │
    └───────────────┘

---

API 명세

1. 공통코드 조회 (캐시됨)

GET /api/code

응답:
{
  "data": [
    {
      "id": 1,
      "code": "STATUS",
      "name": "상태",
      "description": "상태 공통코드",
      "used": true,
      ...
    },
    ...
  ]
}

2. 공통코드 캐시 갱신

POST /api/code/cache/refresh

응답:
{
  "data": "공통코드 캐시가 갱신되었습니다."
}

3. 캐시 상태 확인

GET /api/code/cache/status

응답:
{
  "data": 150  // Redis에 캐시된 공통코드 개수
}

---

캐시 갱신 흐름

자동 갱신 (CRUD 작업)

관리자가 공통코드 등록/수정/삭제
        ↓
CommonCodeService.save() / update() / removeCode()
(@CacheEvict 실행)
        ↓
Redis 캐시 전체 삭제
        ↓
다음 조회 시 DB에서 새로 로드

수동 갱신 (API 호출)

관리자: POST /api/code/cache/refresh
        ↓
CommonCodeCacheManager.refreshCommonCodeCache()
        ↓
캐시 정리 + 새로운 데이터 로드
        ↓
Redis 캐시 업데이트 완료

---

성능 최적화 효과

항목	개선 전	개선 후
조회 속도	DB 직접 조회 (10-100ms)	Redis 캐시 (1-5ms)
DB 부하	매번 조회	캐시 미스시만 조회
네트워크 대역폭	높음 (DB 왕복)	낮음 (로컬 캐시)
응답 시간	변동적	일정 (캐시)

---

추가 기능

CommonCodeUtil - 전역 공통코드 조회

@Component
public class CommonCodeUtil {
  // 모든 공통코드 조회 (캐시 활용)
  public List<Basic> getAllCommonCodes()
  
  // 특정 코드로 조회
  public List<Basic> getCommonCodesByCode(String code)
  
  // ID로 단건 조회
  public Optional<Basic> getCommonCodeById(Long id)
  
  // 코드명 조회
  public Optional<String> getCodeName(String parentCode, String childCode)
  
  // 하위 코드 조회
  public List<Basic> getChildCodesByParentCode(String parentCode)
  
  // 코드 사용 가능 여부 확인
  public boolean isCodeAvailable(Long parentId, String code)
}

사용 예시

@RequiredArgsConstructor
@RestController
public class SomeController {
  
  private final CommonCodeUtil commonCodeUtil;
  
  @GetMapping("/example")
  public void example() {
    // 1. 모든 공통코드 조회 (캐시됨)
    List<Basic> allCodes = commonCodeUtil.getAllCommonCodes();
    
    // 2. 특정 코드 조회
    Optional<String> name = commonCodeUtil.getCodeName("PARENT", "CHILD");
    
    // 3. 코드 사용 가능 여부 확인
    boolean available = commonCodeUtil.isCodeAvailable(1L, "NEW_CODE");
  }
}

---

완료 체크리스트

• Redis 캐싱 어노테이션 적용 (@Cacheable, @CacheEvict)
• 애플리케이션 로딩시 캐시 초기화
• CRUD 작업시 자동 캐시 갱신
• 수동 캐시 갱신 API 제공
• 캐시 상태 모니터링 API
• 전역 공통코드 조회 유틸리티
• 포괄적인 유닛 테스트 (12개)

---

모니터링

캐시 상태를 주기적으로 모니터링:

# 캐시 상태 확인
curl http://localhost:8080/api/code/cache/status

# 캐시 갱신
curl -X POST http://localhost:8080/api/code/cache/refresh

로그 확인:

=== 공통코드 캐시 초기화 시작 ===
✓ 공통코드 150개가 Redis 캐시에 로드되었습니다.
  - [STATUS] 상태 (ID: 1)
  - [TYPE] 타입 (ID: 2)
  ...
=== 공통코드 캐시 초기화 완료 ===