Design and Implementation of Vivo's LuBan Distributed ID Service

This article introduces what a distributed ID is, its business scenarios, and nine common implementation methods. It then presents the design, architecture, and practice of Vivo's internally developed LuBan Distributed ID Service.

1. Business scenarios

Distributed IDs are needed in situations such as sharding databases, multi‑active deployments, and traceability in micro‑service architectures. They provide a globally unique identifier that enables parallel processing and easy data integration.

2. Core challenges

The service must guarantee uniqueness, high performance, high availability, ease of integration, and configurability of ID patterns.

3. Common ID generation schemes

Nine typical schemes are illustrated (Snowflake‑like, database‑auto‑increment, UUID, etc.). Images of the schemes are included in the original article.

4. LuBan Distributed ID Service architecture

The system serves multiple business domains (marketing, manufacturing, finance, etc.). It adopts a centralized ID generation component with stateless, high‑throughput design, and supports dynamic machine‑code allocation via heartbeat reporting for containerized deployments.

5. ID types and composition rules

LuBan provides three built‑in ID types:

Long type – 19 bits composed of a 4‑bit fixed part (zone, agent, project, app), a 4‑bit server part, a 13‑bit dynamic time part, and a 2‑bit self‑increase part.

String type – 25‑27 characters consisting of an operation part, a 7‑digit fixed part, a 1‑digit server part, a 9‑digit dynamic part (base‑32 time), a 3‑digit self‑increase part, and a 3‑digit secure random part.

MixId type – 17 characters combining an operation part, a 2‑digit fixed part, a 6‑digit date‑based dynamic part, and a 7‑digit self‑increase part.

Each type includes a downgrade mechanism for server‑side failures.

6. Custom ID rules

When built‑in types do not satisfy business needs, LuBan allows custom ID algorithms via an SPI mechanism. Clients implement the LuBanGlobalIDClient interface, register the implementation, and invoke it through HTTP or Dubbo.

7. SDK usage

The service provides a Spring‑Boot starter. After adding the dependency and annotating the main class with @EnableGlobalClient , developers can obtain IDs via GlobalIdLongClient , GlobalIdStringClient , or GlobalIdMixIDClient using a fluent RequestDTO builder.

8. Code example (Long 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 globalLongIDRequestDTO = GlobalLongIDRequestDTO.Builder()
                .setAgent("1") // agent, determined during application
                .setZone("0") // zone, determined during application
                .setApp("8") // app, determined during application
                .setProject("7") // project, determined during application
                .setIdNumber(2); // number of IDs to return
        long longId = globalIdLongClient.getGlobalID(globalLongIDRequestDTO);
        return String.valueOf(longId);
    }
}

9. Performance optimizations

Memory usage was optimized by increasing JVM initial and young generation memory, and reducing temporary object creation. Lock granularity was refined by using per‑configuration locks to avoid contention during high‑concurrency ID requests.

10. Deployment metrics

The service generates billions of IDs daily, with average response time of 0–1 ms and a single node supporting tens of thousands of QPS. It is used across order, payment, inventory, fulfillment, and asset‑code business lines.

11. Future plans

Plans include reducing reliance on external Redis/MySQL components, adding more robust degradation strategies, and supporting standard Snowflake‑style algorithms.

12. Conclusion

The article provides a comprehensive overview of distributed ID challenges, nine implementation patterns, and a detailed case study of Vivo's LuBan service, offering practical guidance for ID solution selection and in‑house development.