OpenFluxGate

만든 것

• fluxgate-coreBucket4j 기반 제한 엔진
• fluxgate-redis-ratelimiterLua 스크립트 기반 분산 제한
• fluxgate-mongo-adapterMongoDB 규칙 저장 · 동적 갱신
• spring-boot3 / boot2 starterJava 17+ jakarta / Java 11+ javax 자동 설정
• fluxgate-testkit통합 테스트 유틸리티와 샘플 앱
• FluxGate Studio규칙 관리 · 대시보드 · 시뮬레이션 어드민

왜 만들었나

회사 서비스에 공통 유량제어 수단이 없었습니다. 요청이 몰릴 때 공용 자원을 보호할 방법이 필요했는데, 서버마다 따로 요청 수를 세면 인스턴스 수에 따라 전체 허용량이 달라집니다. 여러 인스턴스가 같은 허용량을 공유하면서, 서비스마다 제한 로직을 새로 짜지 않아도 되는 도구를 만들고 싶었습니다.

판단은 Redis 안에서 한 번에

남은 토큰을 확인하는 것과 차감하는 것이 분리되어 있으면, 동시에 들어온 요청이 같은 잔여량을 보고 함께 통과합니다. 그래서 확인과 차감을 Lua 스크립트 하나로 Redis 안에서 실행합니다. 토큰 보충 계산에는 애플리케이션 서버 시간이 아니라 Redis 서버 시간을 쓰고 정수 연산만 사용해서, 인스턴스 간 시계 차이와 부동소수 오차가 허용량에 섞이지 않게 했습니다.

스크립트가 원자적으로 묶어주는 건 Redis 안의 명령까지입니다. Redis 자체가 느리거나 실패할 때 요청을 허용할지 거절할지는 보호하려는 대상에 따라 따로 정해야 합니다.

무엇을 같은 대상으로 볼 것인가

제한 알고리즘보다 먼저 정해야 했던 건 "누구를 같은 대상으로 셀 것인가"였습니다. IP, 사용자 ID, API 키 중 하나로 제한할 수도 있고, IP와 사용자를 합친 복합 키로 더 잘게 나눌 수도 있게 했습니다. 초 · 분 · 시간 단위 제한을 함께 거는 멀티 밴드 규칙과, 즉시 거절하는 대신 토큰 보충을 기다리는 정책도 넣었습니다.

라이브러리만으로는 쓸 수 없다

규칙을 코드에 박아 두면 바꿀 때마다 배포해야 합니다. 규칙은 MongoDB에 저장하고 재시작 없이 갱신되게 했고, 그 규칙을 만들고 시뮬레이션해 볼 수 있는 어드민 FluxGate Studio를 Next.js와 Spring Boot로 따로 만들었습니다. 인증은 Keycloak OIDC를 붙였습니다.

적용하는 쪽에서 설정만으로 붙일 수 있도록 Spring Boot 2.7과 3.x 각각의 자동 설정 스타터를 두고, 구조화 로깅과 Micrometer 메트릭으로 지금 무엇이 막히고 있는지 볼 수 있게 했습니다. Docusaurus 문서 포털과 벤치마크 페이지도 함께 관리합니다.

지금 상태

Maven Central에 io.github.openfluxgate로 배포되어 있고, v0.3.7까지 릴리스했습니다. 사내에서는 팀 코드 리뷰와 개념 검증(POC)을 거쳐 도입을 검증하는 중입니다. 운영에서 얼마나 효과가 있었는지는 도입 뒤에 측정할 예정이라, 지금은 코드와 검증한 동작 범위로 설명합니다.

돌아보면

제한 알고리즘은 시작일 뿐이었습니다. 무엇을 같은 대상으로 볼지, Redis가 실패하면 어떻게 할지, 지금 무엇이 막히는지 어떻게 볼지를 먼저 정해야 라이브러리를 실제로 쓸 수 있다는 걸 만들면서 배웠습니다.