How Vivo’s LuBan Service Generates Billions of Unique IDs with Sub‑millisecond Latency

Why Distributed IDs

Global unique identifiers are required for sharding tables, multi‑active deployments across regions, and trace‑ID propagation in micro‑service architectures. For example, a marketing order table is split by distribution channel and region, and a TraceID enables end‑to‑end request tracing.

Core Challenges of Distributed ID Generation

Uniqueness : IDs must never collide, even under clock rollback.

High Performance : Near‑zero‑millisecond response under massive concurrency.

High Availability : The generator must be 100 % available.

Ease of Integration : Plug‑and‑play for developers.

Regularity : Configurable prefixes, suffixes, and fixed lengths per business line.

Common ID Schemes

Nine typical schemes (e.g., Snowflake, UUID, database auto‑increment, etc.) are surveyed. Open‑source options did not satisfy Vivo’s heterogeneous requirements, leading to a custom service.

LuBan Distributed ID Service Architecture

The service spans multiple domains (public, manufacturing, marketing, supply‑chain, finance) and supports three built‑in types: Long, String, and MixId, each with distinct length and composition rules.

Long‑type ID

19‑bit numeric ID composed of:

FixPart (4 bits) : zone 1 bit + agent 1 bit + project 1 bit + app 1 bit.

ServerPart (4 bits) : dynamically assigned server identifier.

DynPart (13 bits) : System.currentTimeMillis() - baseTime, supporting 100 years.

SelfIncreasePart (2 bits) : client‑side auto‑increment refreshed after reaching 99 to reduce server calls.

String‑type ID

25‑27 character alphanumeric ID composed of:

Operation part (2‑4 chars) : business‑type marker supplied by the caller.

FixPart (7 chars) : zone 1 char + agent 2 chars + project 2 chars + app 2 chars.

ServerPart (1 char) : A‑Z server code.

DynPart (9 chars) : (System.currentTimeMillis() - baseTime) converted to base‑32.

SelfIncreasePart (3 chars) : client‑side counter.

SecureRandomPart (3 chars) : random alphanumeric string to prevent guessability.

MixId‑type ID

17‑character ID combining numeric and alphanumeric parts:

FixPart (4‑6 chars) : operation code + 2‑digit agent.

DynPart (6 chars) : date formatted as YYMMDD.

SelfIncreasePart (7 chars) : client‑side counter.

Custom ID Rules via SPI

Implement LuBanGlobalIDClient defining FixPart, DynPart, and SelfIncreasePart.

Package the implementation as an SPI module and expose it via HTTP or Dubbo.

Configure the service’s management console with the custom type name and endpoint.

Clients call LuBanGlobalIDClient.getGlobalID(...) with a RequestDTO that specifies the custom algorithm.

Guaranteeing No Duplicate IDs

The service validates uniqueness across nodes; server‑side failures raise exceptions that callers must handle.

Stateless, Zero‑Loss Service Deployment

In containerized environments IPs change frequently. A heartbeat mechanism allocates machine codes dynamically, eliminating static IP‑to‑machine‑code tables. A distributed timer cleans up stale bindings after a configurable five‑minute window.

SDK Integration

A Spring‑Boot starter is provided. Add the starter to pom.xml, annotate the main class with @EnableGlobalClient, and configure AK/SK. The SDK offers three client beans— GlobalIdLongClient, GlobalIdStringClient, and GlobalIdMixIDClient —each accepting a fluent RequestDTO and returning the generated ID.

package com.vivo.it.demo.controller;
import com.vivo.it.platform.luban.id.client.GlobalIdLongClient;
import com.vivo.it.platform.luban.id.dto.GlobalLongIDRequestDTO;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;

@RequestMapping("/globalId")
public class GlobalIdDemoController {
    @Autowired
    private GlobalIdLongClient globalIdLongClient;

    @RequestMapping("/getLongId")
    public String getLongId() {
        GlobalLongIDRequestDTO dto = GlobalLongIDRequestDTO.Builder()
                .setAgent("1")   // agent assigned during onboarding
                .setZone("0")    // zone assigned during onboarding
                .setApp("8")     // app identifier
                .setProject("7") // project identifier
                .setIdNumber(2)   // number of IDs to fetch (effective for queue API only)
                .build();
        long id = globalIdLongClient.getGlobalID(dto);
        return String.valueOf(id);
    }
}

Performance Optimizations

Memory Usage

Initial deployments suffered Full GC pauses. Analysis showed the young generation was too small, causing objects to be promoted to the old generation. The fix increased -Xms (or -XX:InitialRAMPercentage in containers), enlarged the young generation ( -Xmn), and reduced temporary object creation.

Lock Granularity

When a client exhausts its local counter, it requests a new block. A lock per configuration key (zone‑agent‑app‑project) allows concurrent requests for different keys without contention.

Production Metrics

LuBan generates billions of IDs per day, with average response times of 0–1 ms. A single node sustains tens of thousands of QPS and is used for order processing, payment records, inventory, fulfillment, and asset‑code management.

Future Roadmap

Current dependencies on Redis and MySQL for configuration and MixId counters will be mitigated with fallback strategies for extreme outage scenarios. Additional standard algorithms such as Snowflake will be supported to broaden compatibility.