Files
mingli-utils/src/main/kotlin/com/mingliqiye/utils/uuid/UUID.kt
T
2026-03-11 08:47:22 +08:00

786 lines
25 KiB
Kotlin

/*
* Copyright 2026 mingliqiye
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* ProjectName mingli-utils
* ModuleName mingli-utils.main
* CurrentFile UUID.kt
* LastUpdate 2026-03-07 11:02:29
* UpdateUser MingLiPro
*/
package com.mingliqiye.utils.uuid
import com.mingliqiye.utils.array.copyTo
import com.mingliqiye.utils.base.BaseCodec
import com.mingliqiye.utils.base.BaseType
import com.mingliqiye.utils.base.code.Base256
import com.mingliqiye.utils.base.code.Base64
import com.mingliqiye.utils.base.code.Base91
import com.mingliqiye.utils.random.randomByte
import com.mingliqiye.utils.random.secureRandom
import com.mingliqiye.utils.system.macAddressBytes
import com.mingliqiye.utils.time.DateTime
import com.mingliqiye.utils.time.DateTimeOffset
import com.mingliqiye.utils.time.DateTimeOffset.Companion.toDateTimeOffset
import io.swagger.v3.oas.annotations.media.Schema
import java.io.Serializable
import java.math.BigInteger
import java.nio.ByteBuffer
import java.security.MessageDigest
import java.time.temporal.ChronoUnit
import java.util.concurrent.atomic.AtomicLong
import java.util.UUID as JUUID
/**
* UUID 类用于生成和操作不同版本的 UUID(通用唯一标识符)。
* 支持 UUID 的序列化、转换、解析和时间/版本信息提取。
* V8 请开发者自己实现
*/
@Schema(
name = "UUID",
description = "UUID",
type = "string",
format = "uuid"
)
class UUID : Serializable {
private val data: ByteArray
private val mostSigBits: Long
private val leastSigBits: Long
private val version: Int
companion object {
private var lastTimestamp = 0L
private var clockSequence = secureRandom.nextInt(0x3FFF + 1)
private val clockSeqHolder = AtomicLong(0)
/**
* 预期 UUID 字符串中连字符的位置数组。
*/
@JvmStatic
val expectedHyphenPositions = intArrayOf(8, 13, 18, 23)
/**
* UUID 纪元偏移量(以天为单位)。
*/
@JvmStatic
val UUID_EPOCH_OFFSET = 141427L
@JvmStatic
fun ofBase64ShortString(baseShortString: String): UUID {
return UUID(Base64.decode(baseShortString))
}
@JvmStatic
fun ofBase256ShortString(baseShortString: String): UUID {
return UUID(Base256.decode(baseShortString))
}
@JvmStatic
fun ofBase91ShortString(baseShortString: String): UUID {
return UUID(Base91.decode(baseShortString))
}
@JvmStatic
fun getV8(
customA: ByteArray, // 6字节
customB: ByteArray, // 2字节 前4位被替换位版本号
customC: ByteArray, // 8字节, 前2位被替换位变体
): UUID {
require(customA.size == 6) { "customA 必须是6字节" }
require(customB.size == 2) { "customB 必须是2字节" }
require(customC.size == 8) { "customC 必须是8字节" }
val rbyte = ByteArray(16)
customA.copyTo(rbyte, 0, 0, 6)
customB.copyTo(rbyte, 0, 6, 2)
customC.copyTo(rbyte, 0, 8, 8)
rbyte[6] = (rbyte[6].toInt() and 0x0F or 0x80).toByte()
rbyte[8] = (rbyte[8].toInt() and 0x3F or 0x80).toByte()
return UUID(rbyte)
}
/**
* 生成一个 UUID V1 版本,使用系统时钟、随机数和 MAC 地址。
* 如果 MAC 地址为空,则使用随机生成的 MAC 地址。
*
* @return UUID V1 实例
*/
@JvmStatic
fun getV1(): UUID {
val time = DateTime.now().add(DateTimeOffset.of(UUID_EPOCH_OFFSET, ChronoUnit.DAYS)).to100NanoTime()
val timeLow = (time and 0xFFFFFFFFL).toInt()
val timeMid = ((time shr 32) and 0xFFFFL).toShort()
val timeHighAndVersion = (((time shr 48) and 0x0FFFL) or 0x1000L).toShort()
val clockSeq: Long = if (time == lastTimestamp) {
clockSeqHolder.addAndGet(1)
} else {
clockSeqHolder.set(0)
lastTimestamp = time
0
}
val byteBuffer = ByteBuffer.wrap(ByteArray(16))
byteBuffer.putInt(timeLow)
byteBuffer.putShort(timeMid)
byteBuffer.putShort(timeHighAndVersion)
byteBuffer.putShort((clockSeq and 0x3FFF).toShort())
byteBuffer.put(macAddressBytes)
return UUID(byteBuffer.array())
}
@JvmStatic
fun getV1RandomMac(): UUID {
val time = DateTime.now().add(DateTimeOffset.of(UUID_EPOCH_OFFSET, ChronoUnit.DAYS)).to100NanoTime()
val timeLow = (time and 0xFFFFFFFFL).toInt()
val timeMid = ((time shr 32) and 0xFFFFL).toShort()
val timeHighAndVersion = (((time shr 48) and 0x0FFFL) or 0x1000L).toShort()
val clockSeq: Long = if (time == lastTimestamp) {
clockSeqHolder.addAndGet(1)
} else {
clockSeqHolder.set(0)
lastTimestamp = time
0
}
lastTimestamp = time
val byteBuffer = ByteBuffer.wrap(ByteArray(16))
byteBuffer.putInt(timeLow)
byteBuffer.putShort(timeMid)
byteBuffer.putShort(timeHighAndVersion)
byteBuffer.putShort((clockSeq and 0x3FFF).toShort())
byteBuffer.put(randomByte(6))
return UUID(byteBuffer.array())
}
/**
* 生成一个 UUID V4 版本,使用加密安全的随机数。
*
* @return UUID V4 实例
*/
@JvmStatic
fun getV4(): UUID {
val randomBytes = randomByte(16)
randomBytes[6] = (randomBytes[6].toInt() and 0x0F or 0x40).toByte()
randomBytes[8] = (randomBytes[8].toInt() and 0x3F or 0x80).toByte()
return UUID(randomBytes)
}
/**
* 生成一个 UUID V3 版本,基于命名空间和名称的 MD5 哈希值。
*
* @param namepath 命名空间 UUID
* @param user 用户提供的字符串
* @return UUID V3 实例
*/
@JvmStatic
fun getV3(namepath: UUID, user: String): UUID {
val md = MessageDigest.getInstance("MD5")
val userB = user.toByteArray()
val array = md.digest(
ByteBuffer.wrap(ByteArray(16 + userB.size)).put(namepath.data).put(userB).array()
)
array[6] = (array[6].toInt() and 0x0F or 0x30).toByte()
array[8] = (array[8].toInt() and 0x3F or 0x80).toByte()
return UUID(array)
}
/**
* 生成一个 UUID V5 版本,基于命名空间和名称的 SHA-1 哈希值。
*
* @param namepath 命名空间 UUID
* @param user 用户提供的字符串
* @return UUID V5 实例
*/
@JvmStatic
fun getV5(namepath: UUID, user: String): UUID {
val sha1 = MessageDigest.getInstance("SHA-1")
val userB = user.toByteArray()
val array = sha1.digest(
ByteBuffer.wrap(ByteArray(namepath.data.size + userB.size)).put(namepath.data).put(userB).array()
)
array[6] = (array[6].toInt() and 0x0F or 0x50).toByte()
array[8] = (array[8].toInt() and 0x3F or 0x80).toByte()
return UUID(ByteBuffer.wrap(ByteArray(16)).put(array, 0, 16).array())
}
/**
* 生成一个 UUID V6 版本,使用时间戳和随机节点信息。
*
* @return UUID V6 实例
*/
@JvmStatic
fun getV6(): UUID {
val timestamp = DateTime.now().add(DateTimeOffset.of(UUID_EPOCH_OFFSET, ChronoUnit.DAYS))
.to100NanoTime() and 0x0FFFFFFFFFFFFFFFL
val timeHigh = (timestamp ushr 12) and 0xFFFFFFFFFFFFL
val timeMid = timestamp and 0x0FFFL
val clockSeq = secureRandom.nextInt(16384) and 0x3FFF
val node = secureRandom.nextLong() and 0x0000FFFFFFFFFFFFL
val buffer = ByteBuffer.allocate(16)
buffer.putLong((timeHigh shl 16) or (0x6000L) or (timeMid and 0x0FFF))
buffer.putShort((0x8000 or (clockSeq and 0x3FFF)).toShort())
buffer.put((node shr 40).toByte())
buffer.put((node shr 32).toByte())
buffer.put((node shr 24).toByte())
buffer.put((node shr 16).toByte())
buffer.put((node shr 8).toByte())
buffer.put(node.toByte())
return UUID(buffer.array())
}
/**
* 生成一个 UUID V7 版本,使用毫秒级时间戳和随机数。
*
* @return UUID V7 实例
*/
@JvmStatic
fun getV7(): UUID {
val instant = DateTime.now().toMillisecondTime()
val buffer = ByteBuffer.allocate(16)
buffer.putInt((instant shr 16).toInt())
buffer.putShort((instant).toShort())
buffer.put(randomByte(2))
buffer.putLong(secureRandom.nextLong())
val bytes = buffer.array()
bytes[6] = (bytes[6].toInt() and 0x0F or 0x70).toByte()
bytes[8] = (bytes[8].toInt() and 0x3F or 0x80).toByte()
return UUID(bytes)
}
/**
* 根据字符串创建 UUID 实例。
*
* @param uuid UUID 字符串
* @return UUID 实例
*/
@JvmStatic
fun of(uuid: String): UUID {
return UUID(uuid)
}
/**
* 根据字节数组创建 UUID 实例。
*
* @param uuid UUID 字节数组
* @return UUID 实例
*/
@JvmStatic
fun of(uuid: ByteArray): UUID {
return UUID(uuid)
}
/**
* 根据高位和低位长整型创建 UUID 实例。
*
* @param msb 高位长整型
* @param lsb 低位长整型
* @return UUID 实例
*/
@JvmStatic
fun of(msb: Long, lsb: Long): UUID {
return UUID(msb, lsb)
}
/**
* 从ByteBuffer创建UUID对象
*
* @param byteBuffer 包含UUID字节数据的ByteBuffer对象,必须包含至少16个字节的数据
* @return 从ByteBuffer中读取的16个字节创建的UUID对象
*/
@JvmStatic
fun of(byteBuffer: ByteBuffer): UUID {
val byte = ByteArray(16)
byteBuffer.get(byte)
return UUID(byte)
}
/**
* 根据 MySQL UUID 字节数组创建 UUID 实例。
*
* @param byteArray MySQL UUID 字节数组
* @return UUID 实例
*/
@JvmStatic
fun ofMysqlUUID(byteArray: ByteArray): UUID {
return UUID(mysqlToUuid(byteArray))
}
/**
* 根据 MySQL UUID 实例创建 UUID 实例。
*
* @param uuid MySQL UUID 实例
* @return UUID 实例
*/
@JvmStatic
fun ofMysqlUUID(uuid: UUID): UUID {
return UUID(mysqlToUuid(uuid.data))
}
/**
* 获取最大 UUID(所有字节为 0xFF)。
*
* @return 最大 UUID 实例
*/
@JvmStatic
fun getMaxUUID(): UUID {
return UUID(
ByteArray(
16
) { 0xFF.toByte() })
}
/**
* 获取最小 UUID(所有字节为 0x00)。
*
* @return 最小 UUID 实例
*/
@JvmStatic
fun getMinUUID(): UUID {
return UUID(
ByteArray(
16
) { 0x00.toByte() })
}
/**
* 将 Java UUID 转换为自定义 UUID 实例。
*
* @receiver Java UUID 实例
* @return 自定义 UUID 实例
*/
@JvmStatic
@JvmName("ofJUUID")
fun JUUID.toMLUUID(): UUID {
return UUID(this)
}
/**
* 从字符串解析 UUID 字节数组。
*
* @param uuidString UUID 字符串
* @return UUID 字节数组
*/
private fun fromString(uuidString: String): ByteArray {
val cleanStr = when (uuidString.length) {
36 -> {
for (i in expectedHyphenPositions) {
if (uuidString[i] != '-') {
throw IllegalArgumentException("Invalid UUID string: $uuidString at index $i")
}
}
uuidString.replace("-", "")
}
32 -> uuidString
else -> throw IllegalArgumentException("Invalid UUID string: $uuidString")
}
// 直接按索引提取各段并校验
val segments = arrayOf(
cleanStr.take(8),
cleanStr.substring(8, 12),
cleanStr.substring(12, 16),
cleanStr.substring(16, 20),
cleanStr.substring(20, 32)
)
for (segment in segments) {
if (!segment.matches(Regex("^[0-9A-Fa-f]+$"))) {
throw IllegalArgumentException("Invalid UUID segment: $segment")
}
}
return cleanStr.chunked(2).map { it.toInt(16).toByte() }.toByteArray()
}
/**
* 将 MAC 地址字节数组转换为长整型。
*
* @param mac MAC 地址字节数组(必须为 6 字节)
* @return MAC 地址对应的长整型值
*/
private fun macBytesToLong(mac: ByteArray): Long {
require(mac.size == 6) { "MAC地址必须是6字节" }
var result = 0L
for (i in 0 until 6) {
result = (result shl 8) or (mac[i].toLong() and 0xFF)
}
return result
}
fun of(str: String, base: BaseType): UUID {
return UUID(base.baseCodec.decode(str))
}
}
/**
* 构造函数,根据字节数组初始化 UUID。
*
* @param data UUID 字节数组(必须为 16 字节)
*/
constructor(data: ByteArray) {
require(data.size == 16) { "UUID byte array length must be 16" }
this.data = data
val bb: ByteBuffer = ByteBuffer.wrap(data)
mostSigBits = bb.long
leastSigBits = bb.long
version = (mostSigBits shr 12 and 0xF).toInt()
}
/**
* 构造函数,根据高位和低位长整型初始化 UUID。
*
* @param msb 高位长整型
* @param lsb 低位长整型
*/
constructor(msb: Long, lsb: Long) {
mostSigBits = msb
leastSigBits = lsb
val bb: ByteBuffer = ByteBuffer.wrap(ByteArray(16))
bb.putLong(msb)
bb.putLong(lsb)
this.data = bb.array()
version = (mostSigBits shr 12 and 0xF).toInt()
}
/**
* 构造函数,根据 Java UUID 初始化自定义 UUID。
*
* @param juuid Java UUID 实例
*/
constructor(juuid: JUUID) {
mostSigBits = juuid.mostSignificantBits
leastSigBits = juuid.leastSignificantBits
val bb: ByteBuffer = ByteBuffer.wrap(ByteArray(16))
bb.putLong(mostSigBits)
bb.putLong(leastSigBits)
this.data = bb.array()
version = (mostSigBits shr 12 and 0xF).toInt()
}
/**
* 构造函数,根据字符串初始化 UUID。
*
* @param uuid UUID 字符串
*/
constructor(uuid: String) {
fromString(uuid).let {
val bb: ByteBuffer = ByteBuffer.wrap(it)
mostSigBits = bb.long
leastSigBits = bb.long
this.data = it
version = (mostSigBits shr 12 and 0xF).toInt()
}
}
/**
* 返回 UUID 的字节数组表示。
*
* @return UUID 字节数组
*/
fun toBytes(): ByteArray {
return data
}
fun writeToByteBuffer(byteBuffer: ByteBuffer): ByteBuffer {
return byteBuffer.put(data)
}
/**
* 返回 UUID 的高位长整型部分。
*
* @return 高位长整型
*/
fun getMostSignificantBits(): Long {
return mostSigBits
}
/**
* 返回 UUID 的低位长整型部分。
*
* @return 低位长整型
*/
fun getLeastSignificantBits(): Long {
return leastSigBits
}
/**
* 返回 UUID 的字符串表示。
*
* @param isUpper 是否使用大写字母(默认为 false)
* @return UUID 字符串
*/
fun getString(isUpper: Boolean = false): String {
return getString().let {
if (isUpper) {
it.uppercase()
} else it
}
}
/**
* 返回 UUID 的字符串表示。
*
* @param isUpper 是否使用大写字母(默认为 false)
* @param isnotSpace 是否移除连字符(默认为 false)
* @return UUID 字符串
*/
fun getString(isUpper: Boolean = false, isnotSpace: Boolean = false): String {
return getString(isUpper).let {
if (isnotSpace) {
it.replace("-", "")
} else it
}
}
fun getString(uuidFormatType: UUIDFormatType): String {
return getString(isUpper = uuidFormatType.isUpper, isnotSpace = uuidFormatType.isnotSpace)
}
fun getString(baseType: BaseType): String {
return getString(baseType.baseCodec)
}
fun getString(baseCodec: BaseCodec): String {
return baseCodec.encode(data)
}
/**
* 返回标准格式的 UUID 字符串(带连字符)。
*
* @return 标准格式的 UUID 字符串
*/
// 优化后的 toString 方法
fun getString(): String {
return buildString(36) {
val msbHigh = (mostSigBits ushr 32).toInt()
val msbMid = ((mostSigBits ushr 16) and 0xFFFF).toInt()
val msbLow = (mostSigBits and 0xFFFF).toInt()
val lsbHigh = ((leastSigBits ushr 48) and 0xFFFF).toInt()
val lsbLow = (leastSigBits and 0xFFFFFFFFFFFFL)
append(msbHigh.toHexString())
append('-')
append(msbMid.toShort().toHexString(4))
append('-')
append(msbLow.toShort().toHexString(4))
append('-')
append(lsbHigh.toShort().toHexString(4))
append('-')
append(lsbLow.toHexString(12))
}
}
/**
* 将长整型转换为指定长度的十六进制字符串。
*
* @param length 字符串长度
* @return 十六进制字符串
*/
private fun Long.toHexString(length: Int): String {
return this.toString(16).padStart(length, '0')
}
/**
* 将短整型转换为指定长度的十六进制字符串。
*
* @param length 字符串长度
* @return 十六进制字符串
*/
private fun Short.toHexString(length: Int): String {
return this.toLong().and(0xFFFF).toString(16).padStart(length, '0')
}
/**
* 返回 MySQL 格式的 UUID 字节数组。
*
* @return MySQL 格式的 UUID 字节数组
*/
fun toMysql(): ByteArray {
return uuidToMysql(this.data)
}
/**
* 返回 MySQL 格式的 UUID 实例。
*
* @return MySQL 格式的 UUID 实例
*/
fun toMysqlUUID(): UUID {
return of(uuidToMysql(this.data))
}
/**
* 比较两个 UUID 是否相等。
*
* @param other 另一个对象
* @return 如果相等则返回 true,否则返回 false
*/
override fun equals(other: Any?): Boolean {
if (this === other) return true
return when (other) {
is UUID -> {
this.data.contentEquals(other.data)
}
is JUUID -> {
other.mostSignificantBits == this.getMostSignificantBits() && other.leastSignificantBits == this.getLeastSignificantBits()
}
else -> {
false
}
}
}
/**
* 返回对应的 Java UUID 实例。
*
* @return Java UUID 实例
*/
fun getUuid(): JUUID {
return JUUID(mostSigBits, leastSigBits)
}
/**
* 返回 UUID 的版本号。
*
* @return 版本号
*/
fun getVersion(): Int {
return version
}
/**
* 计算 UUID 的哈希码。
*
* @return 哈希码
*/
override fun hashCode(): Int {
return data.contentHashCode()
}
/**
* 返回 UUID 的字符串表示。
*
* @return 包含 UUID 和版本号的字符串
*/
override fun toString(): String {
when (version) {
1 -> {
return "UUID(uuid=${getString()},version=${version},datetime=${getDateTime()},mac=${getMac()})"
}
6, 7 -> {
return "UUID(uuid=${getString()},version=${version},datetime=${getDateTime()})"
}
}
return "UUID(uuid=${getString()},version=${version})"
}
/**
* 根据 UUID 版本提取对应的时间信息。
*
* @return 对应的时间信息
*/
fun getDateTime(): DateTime {
when (version) {
1 -> {
val timestamp =
((mostSigBits and 0x0FFFL) shl 48 or (((mostSigBits shr 16) and 0x0FFFFL) shl 32) or (mostSigBits ushr 32))
val timestampBigInt = BigInteger.valueOf(timestamp)
val nanosecondsBigInt = timestampBigInt.multiply(BigInteger.valueOf(100L))
val divisor = BigInteger.valueOf(1_000_000_000L)
val seconds = nanosecondsBigInt.divide(divisor)
val nanos = nanosecondsBigInt.remainder(divisor)
return DateTime.of(seconds.toLong(), nanos.toLong())
.sub(ChronoUnit.DAYS.toDateTimeOffset(UUID_EPOCH_OFFSET))
}
6 -> {
val timeHigh =
(((data[0].toLong() and 0xFF) shl 40) or ((data[1].toLong() and 0xFF) shl 32) or ((data[2].toLong() and 0xFF) shl 24) or ((data[3].toLong() and 0xFF) shl 16) or ((data[4].toLong() and 0xFF) shl 8) or (data[5].toLong() and 0xFF))
val timeMidAndVersion = ((data[6].toInt() and 0xFF) shl 8) or (data[7].toInt() and 0xFF)
val timeMid = timeMidAndVersion and 0x0FFF
val hundredNanosSinceUuidEpoch = (timeHigh shl 12) or timeMid.toLong()
val seconds = hundredNanosSinceUuidEpoch / 10_000_000
val nanos = (hundredNanosSinceUuidEpoch % 10_000_000) * 100
return DateTime.of(seconds, nanos).sub(ChronoUnit.DAYS.toDateTimeOffset(UUID_EPOCH_OFFSET))
}
7 -> {
val times =
(data[0].toLong() and 0xFF shl 40) or (data[1].toLong() and 0xFF shl 32) or (data[2].toLong() and 0xFF shl 24) or (data[3].toLong() and 0xFF shl 16) or (data[4].toLong() and 0xFF shl 8) or (data[5].toLong() and 0xFF)
return DateTime.of(times)
}
else -> {
throw IllegalArgumentException("UUID version is $version not v1 or v6 or v7 : not supported ")
}
}
}
/**
* 提取 UUID V1 中的 MAC 地址,默认使用冒号分隔符。
*
* @return MAC 地址字符串
*/
fun getMac(): String {
return getMac(":")
}
fun getBase64ShortString(): String {
return Base64.encode(data).substring(0, 22)
}
fun getBase91ShortString(): String {
return Base91.encode(data)
}
fun getBase256ShortString(): String {
return Base256.encode(data)
}
/**
* 提取 UUID V1 中的 MAC 地址。
*
* @param spec 分隔符(默认为冒号)
* @return MAC 地址字符串
*/
fun getMac(spec: String = ":"): String {
if (version != 1) {
throw IllegalArgumentException("UUID version is $version not v1 : not supported ")
}
val macLong = leastSigBits and 0xFFFFFFFFFFFFL
val macBytes = ByteArray(6)
for (i in 0..5) {
macBytes[5 - i] = (macLong shr (8 * i)).toByte()
}
val mac = StringBuilder()
for (i in 0..5) {
mac.append(String.format("%02X", macBytes[i]))
if (i < 5) {
mac.append(spec)
}
}
return mac.toString()
}
}