# snowflake-spring-boot-starter

**Repository Path**: xsxgit/snowflake-spring-boot-starter

## Basic Information

- **Project Name**: snowflake-spring-boot-starter
- **Description**: 基于注册中心的分布式雪花，已兼容nacos、consul、eureka及zookeeper等目前主流注册中心
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 29
- **Forks**: 15
- **Created**: 2019-11-22
- **Last Updated**: 2025-08-07

## Categories & Tags

**Categories**: spring-boot-ext

**Tags**: None

## README

# snowflake-spring-boot-starter

<p align="center">
    <img src="https://img.shields.io/badge/JDK-1.8+-green.svg" />
    <img src="https://img.shields.io/maven-central/v/wiki.xsx/snowflake-spring-boot-starter.svg?label=Maven%20Central" />
    <img src="https://img.shields.io/:license-apache-blue.svg" />
    <a href='https://gitee.com/xsxgit/snowflake-spring-boot-starter/stargazers'>
        <img src='https://gitee.com/xsxgit/snowflake-spring-boot-starter/badge/star.svg?theme=dark' alt='star'></img>
    </a>
</p>

#### 介绍
基于注册中心的分布式雪花，已兼容nacos、consul、eureka及zookeeper等目前主流注册中心

#### 软件架构
基于spring-boot 2.2.11.RELEASE

#### 安装教程

```cmd
mvn clean install
```

#### 使用说明

##### 一、准备工作
1. 添加依赖：
```xml
<dependency>
    <groupId>wiki.xsx</groupId>
    <artifactId>snowflake-spring-boot-starter</artifactId>
    <version>1.2.4</version>
</dependency>
```

2. 添加对应注册中心依赖及相应配置(极简配置)：
- consul:
```xml
<dependencyManagement>
    <dependencies>
       <dependency>
           <groupId>org.springframework.cloud</groupId>
           <artifactId>spring-cloud-dependencies</artifactId>
           <version>${spring-cloud.version}</version>
           <type>pom</type>
           <scope>import</scope>
       </dependency>
    </dependencies>
    <dependency>
       <groupId>org.springframework.cloud</groupId>
       <artifactId>spring-cloud-starter-consul-discovery</artifactId>
    </dependency>
</dependencyManagement>
```
```yaml
server:
  port: 8081
spring:
  application:
    name: snowflake-server
  profiles:
    active: dev
  cloud:
    consul:
      host: localhost
      port: 8500
      discovery:
        hostname: ${spring.cloud.client.ip-address}
        service-name: ${spring.application.name}
        healthCheckPath: /actuator/health
        instance-id: ${spring.application.name}:${spring.cloud.client.ip-address}:${server.port}
        health-check-interval: 10s
        health-check-critical-timeout: 60s
        register: true
        tags: snowflake-server
        
snowflake:
  config:
    mode: FAST|QUICK|NORMAL|MORE|MAX
    check: true|false
    checkIntervalTime: 5000
```
- - -
- eureka:
```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>
    </dependency>
</dependencyManagement>
```
```yaml
server:
  port: 8082
spring:
  application:
    name: snowflake-server
  profiles:
    active: dev

eureka:
  instance:
    hostname: 127.0.0.1
  client:
    register-with-eureka: true
    fetch-registry: true
    service-url:
      defaultZone: http://127.0.0.1:8001/eureka/
      
snowflake:
  config:
    mode: FAST|QUICK|NORMAL|MORE|MAX
    check: true|false
    checkIntervalTime: 5000
```
- - -
- nacos:
```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
        <version>${spring-cloud-alibaba.version}</version>
    </dependency>
</dependencyManagement>
```
```yaml
server:
  port: 8083
spring:
  application:
    name: snowflake-server
  profiles:
    active: dev
  cloud:
    nacos:
      discovery:
        server-addr: 192.168.60.111:8848

snowflake:
  config:
    mode: FAST|QUICK|NORMAL|MORE|MAX
    check: true|false
    checkIntervalTime: 5000
```
- - -
- zookeeper:
```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-zookeeper-discovery</artifactId>
    </dependency>
</dependencyManagement>
```
```yaml
server:
  port: 8084
spring:
  application:
    name: snowflake-server
  profiles:
    active: dev
  cloud:
    zookeeper:
      connect-string: 192.168.60.111:2181
      discovery:
        instance-host: 127.0.0.1
        instance-id: ${spring.application.name}:${spring.cloud.client.ip-address}:${server.port}
        instance-port: ${server.port}
        register: true

snowflake:
  config:
    mode: FAST|QUICK|NORMAL|MORE|MAX
    check: true|false
    checkIntervalTime: 5000
```
##### 二、开始使用
方式一： 

加上 @EnableDiscoveryClient 注解并导入 SnowflakeApi 类即可使用，默认提供两个api：“/snowflake/long”（长整型）与“/snowflake/string”（字符串）

```java
@SpringBootApplication
@EnableDiscoveryClient
@Import(SnowflakeApi.class)
public class SnowflakeExampleNacosApplication {

    public static void main(String[] args) {
        SpringApplication.run(SnowflakeExampleNacosApplication.class, args);
    }

}
```
方式二： 

自定义Controller，使用Snowflake获取
```java
@SpringBootApplication
@EnableDiscoveryClient
public class SnowflakeExampleNacosApplication {

    public static void main(String[] args) {
        SpringApplication.run(SnowflakeExampleNacosApplication.class, args);
    }

}

@RestController
@RequestMapping("/id")
public class SnowflakeController {

    @Autowired
    private Snowflake snowflake;

    @GetMapping("/long")
    public Map<String, Object> getLong() {
        return this.getResult(this.snowflake.nextId());
    }

    @GetMapping("/string")
    public Map<String, Object> getString() {
        return this.getResult(this.snowflake.nextIdStr());
    }

    private Map<String, Object> getResult(Object data) {
        Map<String, Object> result = new HashMap<>(3);
        result.put("code", 200);
        result.put("msg", "success");
        result.put("data", data);
        return result;
    }
}
```

##### 三、示例项目
[snowflake-example](https://gitee.com/xsxgit/snowflake-example)

##### 四、部署说明
本项目会自动获取可用机器码id及数据中心id，无需人为设定，根据模式选择，最多可部署4096台服务器，可作为id服务或订单号服务使用，最终可生成19位长度的唯一标识

##### 五、作者其他项目
1. [redis工具](https://gitee.com/xsxgit/redis-spring-boot-starter)
2. [日志组件](https://gitee.com/xsxgit/slf4j-spring-boot-starter)