Hutool
  • 指南
  • 核心(hutool-core)
  • 集合(collection)
Hutool
2026-01-14
目录

环形索引工具-RingIndexUtil

# 📚 介绍

RingIndexUtil 是 Hutool 核心模块中的环形索引工具类，它提供了丰富的环形索引操作方法，用于实现环形结构的索引管理，为 Java 开发者提供了便捷的环形结构操作解决方案。

# 设计理念

  • 环形结构支持：专门用于处理环形结构的索引管理
  • 边界自动处理：自动处理索引的边界问题，实现无缝循环
  • 简单易用：提供简洁的 API，一行代码即可完成环形索引操作
  • 高性能：底层实现经过优化，性能优异
  • 线程安全：所有工具类都是线程安全的，可以在多线程环境下安全使用

# 🔧 核心方法详解

# 1. 环形索引创建

# RingIndexUtil(int size)

功能：创建一个指定大小的环形索引

参数：

  • size：环形结构的大小

返回值：环形索引对象

示例：

// 创建大小为5的环形索引
RingIndexUtil ringIndex = new RingIndexUtil(5);
Console.log("初始索引：" + ringIndex.getIndex()); // 初始索引：0

# RingIndexUtil(int size, int initialIndex)

功能：创建一个指定大小和初始索引的环形索引

参数：

  • size：环形结构的大小
  • initialIndex：初始索引位置

返回值：环形索引对象

示例：

// 创建大小为5，初始索引为2的环形索引
RingIndexUtil ringIndex = new RingIndexUtil(5, 2);
Console.log("初始索引：" + ringIndex.getIndex()); // 初始索引：2

# 2. 索引操作

# next()

功能：获取下一个索引，并将索引前进一位

返回值：下一个索引

示例：

RingIndexUtil ringIndex = new RingIndexUtil(5);
// 获取下一个索引
int nextIndex = ringIndex.next();
Console.log("下一个索引：" + nextIndex); // 下一个索引：0
Console.log("当前索引：" + ringIndex.getIndex()); // 当前索引：1

# prev()

功能：获取上一个索引，并将索引后退一位

返回值：上一个索引

示例：

RingIndexUtil ringIndex = new RingIndexUtil(5, 1);
// 获取上一个索引
int prevIndex = ringIndex.prev();
Console.log("上一个索引：" + prevIndex); // 上一个索引：1
Console.log("当前索引：" + ringIndex.getIndex()); // 当前索引：0

# getNext()

功能：获取下一个索引，但不改变当前索引

返回值：下一个索引

示例：

RingIndexUtil ringIndex = new RingIndexUtil(5);
// 获取下一个索引，但不改变当前索引
int nextIndex = ringIndex.getNext();
Console.log("下一个索引：" + nextIndex); // 下一个索引：1
Console.log("当前索引：" + ringIndex.getIndex()); // 当前索引：0

# getPrev()

功能：获取上一个索引，但不改变当前索引

返回值：上一个索引

示例：

RingIndexUtil ringIndex = new RingIndexUtil(5);
// 获取上一个索引，但不改变当前索引
int prevIndex = ringIndex.getPrev();
Console.log("上一个索引：" + prevIndex); // 上一个索引：4
Console.log("当前索引：" + ringIndex.getIndex()); // 当前索引：0

# 3. 索引获取和设置

# getIndex()

功能：获取当前索引

返回值：当前索引

示例：

RingIndexUtil ringIndex = new RingIndexUtil(5, 2);
// 获取当前索引
int currentIndex = ringIndex.getIndex();
Console.log("当前索引：" + currentIndex); // 当前索引：2

# setIndex(int index)

功能：设置当前索引

参数：

  • index：要设置的索引

示例：

RingIndexUtil ringIndex = new RingIndexUtil(5);
// 设置当前索引
ringIndex.setIndex(3);
Console.log("当前索引：" + ringIndex.getIndex()); // 当前索引：3

# 4. 环形大小操作

# getSize()

功能：获取环形结构的大小

返回值：环形结构的大小

示例：

RingIndexUtil ringIndex = new RingIndexUtil(5);
// 获取环形结构的大小
int size = ringIndex.getSize();
Console.log("环形大小：" + size); // 环形大小：5

# setSize(int size)

功能：设置环形结构的大小

参数：

  • size：要设置的环形结构大小

示例：

RingIndexUtil ringIndex = new RingIndexUtil(5);
// 设置环形结构的大小
ringIndex.setSize(10);
Console.log("环形大小：" + ringIndex.getSize()); // 环形大小：10

# 🚀 综合示例

# 示例1：环形索引基本操作

public void ringIndexBasicTest() {
    // 创建大小为5的环形索引
    RingIndexUtil ringIndex = new RingIndexUtil(5);

    Console.log("初始索引：" + ringIndex.getIndex()); // 初始索引：0

    // 测试next()方法
    for (int i = 0; i < 6; i++) {
        int next = ringIndex.next();
        Console.log("第" + (i + 1) + "次next()：" + next + "，当前索引：" + ringIndex.getIndex());
    }

    // 重置索引
    ringIndex.setIndex(0);
    Console.log("\n重置索引后：" + ringIndex.getIndex()); // 重置索引后：0

    // 测试prev()方法
    for (int i = 0; i < 6; i++) {
        int prev = ringIndex.prev();
        Console.log("第" + (i + 1) + "次prev()：" + prev + "，当前索引：" + ringIndex.getIndex());
    }
}

# 示例2：环形索引在轮询中的应用

public void ringIndexPollingTest() {
    // 创建服务器列表
    List<String> servers = Arrays.asList(
        "server1:8080",
        "server2:8080",
        "server3:8080",
        "server4:8080",
        "server5:8080"
    );

    // 创建与服务器列表大小相同的环形索引
    RingIndexUtil ringIndex = new RingIndexUtil(servers.size());

    // 模拟10次请求，使用环形索引实现轮询负载均衡
    for (int i = 0; i < 10; i++) {
        // 获取当前要使用的服务器索引
        int serverIndex = ringIndex.getIndex();
        // 获取服务器地址
        String server = servers.get(serverIndex);
        Console.log("第" + (i + 1) + "次请求：" + server);
        // 索引前进一位，准备下一次请求
        ringIndex.next();
    }
}

# 示例3：环形索引在循环队列中的应用

public class RingQueue<T> {
    private final List<T> queue;
    private final RingIndexUtil ringIndex;

    public RingQueue(int capacity) {
        this.queue = new ArrayList<>(Collections.nCopies(capacity, null));
        this.ringIndex = new RingIndexUtil(capacity);
    }

    /**
     * 添加元素到环形队列
     * @param element 要添加的元素
     */
    public void add(T element) {
        // 获取当前索引
        int index = ringIndex.getIndex();
        // 添加元素
        queue.set(index, element);
        // 索引前进一位
        ringIndex.next();
    }

    /**
     * 获取环形队列中的所有元素
     * @return 环形队列中的所有元素
     */
    public List<T> getAll() {
        return new ArrayList<>(queue);
    }
}

// 使用示例
public void ringQueueTest() {
    // 创建容量为3的环形队列
    RingQueue<String> ringQueue = new RingQueue<>(3);

    // 添加元素
    ringQueue.add("元素1");
    ringQueue.add("元素2");
    ringQueue.add("元素3");
    Console.log("添加3个元素后：" + ringQueue.getAll()); // [元素1, 元素2, 元素3]

    // 添加第4个元素，会覆盖第一个元素
    ringQueue.add("元素4");
    Console.log("添加第4个元素后：" + ringQueue.getAll()); // [元素4, 元素2, 元素3]

    // 添加第5个元素，会覆盖第二个元素
    ringQueue.add("元素5");
    Console.log("添加第5个元素后：" + ringQueue.getAll()); // [元素4, 元素5, 元素3]
}

# 🎯 设计优势

  1. 环形结构支持：专门用于处理环形结构的索引管理，简化了环形结构的实现
  2. 边界自动处理：自动处理索引的边界问题，实现无缝循环，无需手动处理边界条件
  3. 简单易用：提供简洁的 API，一行代码即可完成环形索引操作，降低了开发难度
  4. 高性能：底层实现经过优化，性能优异，适合高并发场景
  5. 线程安全：所有方法都是线程安全的，可以在多线程环境下安全使用
  6. 灵活性强：支持动态调整环形结构的大小，适应不同的使用场景

# 📌 注意事项

  1. 初始索引范围：初始索引必须在 [0, size-1] 范围内，否则会抛出异常
  2. 大小调整：调整环形结构大小时，当前索引可能会被重置，使用时需要注意
  3. 线程安全：虽然工具类本身是线程安全的，但在某些复杂场景下，可能需要额外的同步机制
  4. 性能考虑：对于非常大的环形结构，某些操作可能会影响性能，建议根据实际情况选择合适的大小

# 🚀 总结

RingIndexUtil 是一个功能强大、使用便捷的环形索引工具类，为 Java 开发者提供了丰富的环形结构操作解决方案。它简化了环形结构的实现，自动处理索引的边界问题，提供了简洁的 API，使得环形结构的操作更加容易。

无论是简单的轮询负载均衡，还是复杂的循环队列实现，RingIndexUtil 都能轻松应对。通过合理使用 RingIndexUtil，可以简化环形结构的开发工作，提高开发效率，同时保证操作的准确性和性能。

RingIndexUtil 是 Hutool 集合模块中的重要组成部分，与其他集合工具类一起，构成了完整的集合操作解决方案，为 Java 开发者提供了丰富的集合操作工具。

列表工具-ListUtil
分割迭代器工具-SpliteratorUtil

← 分割迭代器工具-SpliteratorUtil→

Theme by Vdoing | Copyright © 2025-2026 Hutool | Apache-2.0