Python UUID v4 生成指南

import uuid

# 生成一个 UUID v4
request_id = uuid.uuid4()

print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(type(request_id))     # <class 'uuid.UUID'>
print(request_id.version)   # 4

# 转换为字符串用于 JSON / HTTP 头
print(str(request_id))      # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
print(request_id.hex)       # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e"（无连字符）
print(request_id.bytes)     # b';...'（16 个原始字节）

import uuid
import requests

def call_api(endpoint: str, payload: dict) -> dict:
    trace_id = str(uuid.uuid4())
    headers = {
        "X-Request-ID": trace_id,
        "Content-Type": "application/json",
    }
    response = requests.post(endpoint, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return {"trace_id": trace_id, "data": response.json()}

# result["trace_id"] 可用于在所有服务日志中精确检索该请求
result = call_api("https://api.example.com/v1/orders", {"product_id": "prod_7x2k", "qty": 3})
print(result["trace_id"])  # 例如 "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"

import uuid

# 为 1000 条遥测事件预生成 ID
event_ids = [str(uuid.uuid4()) for _ in range(1000)]
print(f"Generated {len(event_ids)} unique IDs")
print(event_ids[0])   # 例如 "a1c2e3f4-..."
print(event_ids[-1])  # 每次运行值都不同

import uuid

u = uuid.uuid4()

print(str(u))         # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"  （36 字符）
print(u.hex)          # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e"      （32 字符，无连字符）
print(u.bytes)        # b';Š...'                       （16 字节，大端序）
print(u.bytes_le)     # b'Š...'                       （16 字节，小端序）
print(u.int)          # 78823...（128 位整数）
print(u.version)      # 4
print(u.variant)      # 'specified in RFC 4122'

# 往返：从字符串重建
reconstructed = uuid.UUID("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e")
print(reconstructed == u)  # True（如果 u 就是该值）

import uuid

def parse_uuid4(raw: str) -> uuid.UUID:
    """
    解析并验证 UUID v4 字符串。
    格式无效或版本不符时抛出 ValueError。
    """
    try:
        u = uuid.UUID(raw)
    except ValueError as exc:
        raise ValueError(f"Invalid UUID format: {raw!r}") from exc

    if u.version != 4:
        raise ValueError(f"Expected UUID v4, got v{u.version}: {raw!r}")

    return u

# 在 FastAPI / Flask 路由处理器中使用
def get_order(order_id: str):
    try:
        uid = parse_uuid4(order_id)
    except ValueError as exc:
        return {"error": str(exc)}, 400

    # 现在可以安全地在 DB 查询中使用 uid
    return {"order_id": str(uid), "status": "processing"}

import json
import uuid
from datetime import datetime

class ApiEncoder(json.JSONEncoder):
    """在 JSON 响应中序列化 UUID 和 datetime 对象。"""
    def default(self, obj):
        if isinstance(obj, uuid.UUID):
            return str(obj)
        if isinstance(obj, datetime):
            return obj.isoformat()
        return super().default(obj)

# 包含嵌套 UUID 的真实 API 响应
api_response = {
    "request_id": uuid.uuid4(),
    "created_at": datetime(2026, 3, 14, 9, 41, 0),
    "order": {
        "id": uuid.uuid4(),
        "customer_id": uuid.uuid4(),
        "items": [
            {"product_id": uuid.uuid4(), "sku": "NVX-9000", "qty": 2},
        ],
    },
}

print(json.dumps(api_response, indent=2, cls=ApiEncoder))
# {
#   "request_id": "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e",
#   "created_at": "2026-03-14T09:41:00",
#   "order": {
#     "id": "a1c2e3f4-...",
#     ...
#   }
# }

import json, uuid

event_id = uuid.uuid4()
payload = {"event_id": event_id, "action": "checkout"}

# 传入可调用对象；仅在 json 无法处理的类型时调用
json_str = json.dumps(payload, default=str)
print(json_str)  # {"event_id": "3b1f8a9d-...", "action": "checkout"}

import json
import uuid
import requests

def fetch_shipment(shipment_id: str) -> dict:
    """获取货运信息并返回带类型化 UUID 字段的结果。"""
    response = requests.get(
        f"https://api.logistics.example.com/v2/shipments/{shipment_id}",
        headers={"Accept": "application/json"},
        timeout=10,
    )
    response.raise_for_status()
    data = response.json()

    # 将 UUID 字段解析回 uuid.UUID 对象
    try:
        data["id"] = uuid.UUID(data["id"])
        data["carrier_id"] = uuid.UUID(data["carrier_id"])
    except (KeyError, ValueError) as exc:
        raise RuntimeError(f"Malformed shipment response: {exc}") from exc

    return data

import json, uuid

def rotate_correlation_id(path: str) -> str:
    """替换或添加 JSON 文件中的 'correlation_id'，返回新的 UUID。"""
    try:
        with open(path) as f:
            data = json.load(f)
    except FileNotFoundError:
        data = {}
    except json.JSONDecodeError as exc:
        raise ValueError(f"Invalid JSON in {path!r}: {exc}") from exc

    new_id = str(uuid.uuid4())
    data["correlation_id"] = new_id

    with open(path, "w") as f:
        json.dump(data, f, indent=2)

    return new_id

# 单个 UUID v4
python3 -c "import uuid; print(uuid.uuid4())"
# 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e

# 无连字符的十六进制格式——适合文件名和环境变量
python3 -c "import uuid; print(uuid.uuid4().hex)"
# 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e

# 为批量 seed 脚本生成 5 个 UUID
python3 -c "import uuid; [print(uuid.uuid4()) for _ in range(5)]"

# 赋值给 shell 变量
DEPLOY_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
echo "Deploying with ID: $DEPLOY_ID"

pip install uuid-utils

# uuid_utils 是标准库 uuid 模块的直接替代
import uuid_utils as uuid

# 与标准库相同的 API
request_id = uuid.uuid4()
print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(request_id))      # 标准字符串
print(request_id.hex)       # 无连字符的十六进制
print(request_id.version)   # 4

# 同时支持 v7（时间有序，非常适合数据库主键）
time_ordered_id = uuid.uuid7()
print(time_ordered_id)      # 以当前时间戳前缀开头

from dataclasses import dataclass, field
import uuid

@dataclass
class WorkerJob:
    job_id: uuid.UUID = field(default_factory=uuid.uuid4)
    worker_id: str = "worker-01"
    payload: dict = field(default_factory=dict)

job1 = WorkerJob(payload={"task": "resize_image", "src": "uploads/img_4932.png"})
job2 = WorkerJob(payload={"task": "send_email",   "to":  "ops@example.com"})

print(job1.job_id)  # 每个实例唯一
print(job2.job_id)  # 与 job1.job_id 不同
print(job1.job_id == job2.job_id)  # False

from pydantic import BaseModel, Field
import uuid

class OrderEvent(BaseModel):
    event_id: uuid.UUID = Field(default_factory=uuid.uuid4)
    order_id: uuid.UUID
    status: str
    amount_cents: int

event = OrderEvent(
    order_id=uuid.UUID("a1c2e3f4-5b6d-4e7f-8c9d-0a1b2c3d4e5f"),
    status="payment_confirmed",
    amount_cents=4995,
)

print(event.model_dump_json(indent=2))
# {
#   "event_id": "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e",
#   "order_id": "a1c2e3f4-5b6d-4e7f-8c9d-0a1b2c3d4e5f",
#   "status": "payment_confirmed",
#   "amount_cents": 4995
# }
# Pydantic v2 自动将 uuid.UUID 序列化为字符串