Python 中如何生成 UUID

Python uuid 标准库简介

Python 自 2.5 版本起就内置了 uuid 模块，无需安装任何额外包。该模块实现了 RFC 4122 定义的 UUID 版本 1、3、4、5，提供了 UUID 类和几个便捷的生成函数。UUID 对象不仅可以转为字符串，还可以访问各个字段（time_low、time_mid、clock_seq 等），以及 bytes、int、hex 等多种表示形式。这使 Python 的 UUID 操作非常灵活，适合各种需要精确控制 UUID 格式的场景。

生成各版本 UUID 的代码示例

import uuid

# UUID v4（最常用，随机生成）
id_v4 = uuid.uuid4()
print(id_v4)                    # UUID 对象
print(str(id_v4))               # 字符串表示
print(id_v4.hex)                # 无连字符
print(id_v4.bytes)              # 16 字节
print(id_v4.int)                # 整数

# UUID v1（时间戳 + MAC 地址）
id_v1 = uuid.uuid1()
print(id_v1)
print(id_v1.time)               # 时间戳字段
print(id_v1.node)               # 节点（MAC）字段

# UUID v3（MD5 哈希，确定性）
id_v3 = uuid.uuid3(uuid.NAMESPACE_URL, 'https://example.com')
print(id_v3)

# UUID v5（SHA-1 哈希，确定性）
id_v5 = uuid.uuid5(uuid.NAMESPACE_DNS, 'example.com')
print(id_v5)

# 标准命名空间
print(uuid.NAMESPACE_DNS)   # 6ba7b810-9dad-11d1-80b4-00c04fd430c8
print(uuid.NAMESPACE_URL)   # 6ba7b811-9dad-11d1-80b4-00c04fd430c8
print(uuid.NAMESPACE_OID)   # 6ba7b812-9dad-11d1-80b4-00c04fd430c8
print(uuid.NAMESPACE_X500)  # 6ba7b814-9dad-11d1-80b4-00c04fd430c8

格式化 UUID 输出

import uuid

uid = uuid.uuid4()

# 不同格式输出
print(str(uid))               # 标准格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
print(uid.hex)                # 无连字符：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
print(str(uid).upper())       # 大写格式
print(str(uid).replace('-', ''))  # 移除连字符

# 解析 UUID 字符串
parsed = uuid.UUID('550e8400-e29b-41d4-a716-446655440000')
parsed_no_dash = uuid.UUID('550e8400e29b41d4a716446655440000')  # 无连字符也可以
parsed_braces = uuid.UUID('{550e8400-e29b-41d4-a716-446655440000}')  # 花括号

# 查看版本和变体
print(parsed.version)   # 4
print(parsed.variant)   # UUID 变体标识

# 批量生成
uuids = [str(uuid.uuid4()) for _ in range(10)]

在 Django 中使用 UUID 主键

Django 原生支持 UUID 作为模型主键，使用 models.UUIDField。这是在 Django 中避免自增主键、提高安全性的推荐做法。UUID 主键不会暴露数据库记录的总数和顺序，适合面向公开 API 的资源 ID。

# Django 模型示例
import uuid
from django.db import models

class Article(models.Model):
    id = models.UUIDField(
        primary_key=True,
        default=uuid.uuid4,  # 注意：传函数引用而非调用结果
        editable=False
    )
    title = models.CharField(max_length=200)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ['-created_at']

# 使用
article = Article(title='Hello World')
article.save()
print(article.id)       # UUID 对象
print(str(article.id))  # 字符串

在 SQLAlchemy 中使用 UUID

# SQLAlchemy 示例
import uuid
from sqlalchemy import Column, String
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = 'users'

    # PostgreSQL 原生 UUID 类型
    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)

    # 或使用 String 兼容所有数据库
    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))

FastAPI 中的 UUID 类型注解

# FastAPI + Pydantic 示例
from uuid import UUID, uuid4
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    id: UUID = None
    name: str

    def __init__(self, **data):
        if 'id' not in data:
            data['id'] = uuid4()
        super().__init__(**data)

@app.get('/items/{item_id}')
async def get_item(item_id: UUID):
    # FastAPI 自动验证 item_id 是否是合法 UUID
    return {'id': str(item_id)}

@app.post('/items')
async def create_item(item: Item):
    return item

验证 UUID 字符串

import uuid

def is_valid_uuid(uuid_string: str) -> bool:
    """验证字符串是否是合法的 UUID"""
    try:
        uuid.UUID(uuid_string)
        return True
    except ValueError:
        return False

def is_valid_uuid_v4(uuid_string: str) -> bool:
    """验证字符串是否是合法的 UUID v4"""
    try:
        u = uuid.UUID(uuid_string)
        return u.version == 4
    except ValueError:
        return False

# 测试
print(is_valid_uuid('550e8400-e29b-41d4-a716-446655440000'))  # True
print(is_valid_uuid('not-a-uuid'))  # False
print(is_valid_uuid_v4('550e8400-e29b-41d4-a716-446655440000'))  # False (v1)
print(is_valid_uuid_v4(str(uuid.uuid4())))  # True