5 min read
Exploring Spring Boot Through a Distributed URL Shortener
Building a distributed URL shortener in Spring Boot, exploring caching, sharding, service discovery, and practical lessons in scalable system design.
- System Design
- Personal Tech Projects
Disclaimer: This is a personal learning project. I’m new to Spring Boot, and this is not production-grade code — but I’m writing down my learning journey so others who are also starting out might find it useful.
Why this project? #
When learning a new framework, I find it easier to pick a project that’s small enough to complete and complex enough to explore real-world concepts. In this case, I found that a distributed URL shortener fits this well. It has only two main functions: “shorten a URL” and “redirect it”.
It is also a good playground for distributed system concepts such as caching, database sharding, and service discovery.
Above all, a distributed URL shortener is a popular topic in many system design interview books, and working on it helps me to deepen my understanding.
🛠 System Design Takeaways#
Although this project runs on a simple local setup, I designed it with scalability in mind. And here are some system design takeaways
1) Database Sharding & Reading Replica#
I have used MySQL as the database, sharded horizontally using a simple modulus-based strategy. Each shard also has a read replica for query load distribution where the Redirect-API reads from the replicas.
# Create replication user on master shardmysql -u root -p"$MYSQL_ROOT_PASSWORD" <<EOFCREATE USER IF NOT EXISTS 'repl_user'@'%' IDENTIFIED BY 'repl_password';GRANT REPLICATION SLAVE ON *.* TO 'repl_user'@'%';FLUSH PRIVILEGES;EOF# Stop any existing replica and start replica with replication usermysql -u root -p"$MYSQL_ROOT_PASSWORD" <<EOFSTOP REPLICA;CHANGE REPLICATION SOURCE TO SOURCE_HOST='url-db-shard-0-master', SOURCE_USER='$REPL_USER', SOURCE_PASSWORD='$REPL_PASSWORD', SOURCE_LOG_FILE='$FILE', SOURCE_LOG_POS=$POS;START REPLICA;EOFIn a real-world setup, shard scaling could be automated based on load and managed via container lifecycle orchestrator such as Kubernetes, but for now it’s manually defined via Docker Compose and Shell scripts to keep the project simple.
2) Service Discovery#
Eureka acts as the service registry. Even though this project only uses 1 instance for the shorten API and redirect API, Eureka makes it easier to scale horizontally if there’s a need. This allows the API gateway to dynamically discover service instances without hardcoding addresses.
In a production setting, there might be times when you are required to spin more instances to better support the workload and this would come in handy.
3) Caching with Redis#
Redis is configured with:
- 1-hour TTL
- LRU (Least Recently Used) eviction policy.
@ReadOnly public String resolveOriginalUrl(String shortId) { String cacheUrl = redisTemplate.opsForValue().get(shortId);
if(cacheUrl != null) { log.info("Taking from Cache" + cacheUrl); return cacheUrl; }
int shardId = hashBasedShardResolver.resolveShard(shortId); RoutingContext.setShardId(shardId);
ShortUrl shortUrl = repository.findById(shortId).orElseThrow(() -> new ResourceNotFoundException(ShortUrl.class.getName(), shortId));
log.info("Querying from repo" + shortUrl.getOriginalUrl()); redisTemplate.opsForValue().set(shortId, shortUrl.getOriginalUrl(), Duration.ofHours(1));
return shortUrl.getOriginalUrl(); } redis: image: redis ports: - "6379:6379" command: redis-server --maxmemory 16mb --maxmemory-policy allkeys-lru healthcheck: test: [ "CMD-SHELL", "redis-cli ping | grep PONG" ] timeout: 10s retries: 10 extends: file: common-config.yml service: network-deploy-serviceWhy LRU over LFU?
This is to avoid keeping the old “once-popular” entries in the cache forever. However, this might not be an issue in my case, given that we have set the TTL to one hour. To avoid prioritising old popular values, I prefer evicting them and keeping the currently popular URLs in cache.
4) Avoiding Hotspotting#
Using a timestamp-based ID can cause potential hotspotting if sequential IDs always route to the same shard. To avoid that, I pass the ID through Murmur3 hash before applying the modulus for sharding, which helps distribute data evenly across shards.
public class HashUtil { public static int hash(String key){ return Hashing.murmur3_32_fixed() .hashString(key, StandardCharsets.UTF_8) .asInt() & 0x7fffffff; // make it positive }}🌱 Spring Boot Features I Found Useful#
1) AOP for Dynamic Data Source Routing#
I used Spring AOP to route repository calls to the correct data source at runtime. A RouterContext (with thread-local) is created to store which data source should be used.
public class RoutingContext { private static final ThreadLocal<String> OPERATION_TYPE = new ThreadLocal<>(); private static final ThreadLocal<Integer> SHARD_ID = new ThreadLocal<>(); public static void setReadOnly() { setOperationType(OPERATION_READ); }
public static void setWriteOnly() { setOperationType(OPERATION_WRITE); } public static String getRoutingKey() { if(SHARD_ID.get() == null || OPERATION_TYPE.get() == null) { log.warn("RoutingContext: NULL values - using default datasource"); return null; }
String routingKey = generateLookUpKey(SHARD_ID.get(), OPERATION_TYPE.get()); log.info("RoutingContext: Using routing key = {}", routingKey);
return generateLookUpKey(SHARD_ID.get(), OPERATION_TYPE.get()); } // ....}
@Aspect@Component@Order(1)public class ReadWriteRoutingAspect { @Around("@annotation(readOnly)") public Object routeRead(ProceedingJoinPoint joinPoint, ReadOnly readOnly) throws Throwable { try { RoutingContext.setReadOnly(); return joinPoint.proceed(); } finally { RoutingContext.clear(); } }
@Around("@annotation(writeOnly)") public Object routeWrite(ProceedingJoinPoint joinPoint, WriteOnly writeOnly) throws Throwable { try { RoutingContext.setWriteOnly(); return joinPoint.proceed(); } finally { RoutingContext.clear(); } } // ...}I am using Thread-local storage to ensure no collision between requests from different services.
2) Redis Integration in SpringBoot#
Configuring Redis in Spring Boot is quite simple. I simply add “spring-boot-starter-data-redis” in Maven pom.xml
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis-reactive</artifactId> </dependency>3) Lombok for Less Boilerplate#
Lombok annotations like @Builder, @Data, and @RequiredArgsConstructor save a lot of time by generating getters, setters, constructor, etc. (there are some IDE helps to generate getter, setter code as well, but Lombok keeps the class shorter)
However, you might still need to manually define constructors or setters in special case. In most situations, Lombok keeps your classes clean and readable
🛑 Limitations & Future Work#
- No Authentication or Rate Limiting
- Manual shard configuration - no automatic scaling
- Minimal Monitoring/logging
- Testing Coverage
- Load Testing
📌 Key Takeaways for Beginners#
- Pick a project that forces you to learn both framework features and system design
- Don’t aim for production-grade right away - focus on learning the concepts first
- In distributed systems, cache strategically and spread load evenly - but only add complexity when you actually need it
- Spring Boot's auto-configuration and starter dependencies make prototyping much faster
- Use annotations and AOP to keep your business logic clean while handling cross-cutting concerns like data source routing
This post shares the main takeaways, but if you want to see the complete design decisions and implementation, check out system-design.md or browse the full codebase on GitHub.
📂 GitHub Repo: distributed-url-shortener/
💬 Have suggestions? Open an issue or comment — I'm still learning and happy to discuss improvements!