选择标识符生成和公开暴露规则，以避免通过 URL、日志和 API 泄露不应有的创建时间、租户顺序或数量信号，同时保持可排序 ID。
包状态： AI 辅助参考包。静态包验证已通过；实现场景尚未运行，且在稳定采用前需要人工领域审查。
决策
主键和公共资源标识符必须作为一个策略选择，而非分别采用默认值。当数据存储受益于时间顺序聚类时，团队可以在持久化边界采用可排序的标识符格式，同时为任何客户可见的 URL 或共享链接保留单独的不透明代理。随机标识符在排序无操作优势且暴露风险已低的情况下仍然有效。该决策将三个关注点绑定在一起：标识符如何生成、其字节顺序是否暗示创建顺序，以及哪些界面可能暴露原始值与经过编辑或哈希的形式。
范围
- 标识符生成策略、冲突处理及从遗留格式的迁移。
- 列表 API 中暴露的排序和分页字段。
- 公开 URL、API 响应字段、结构化日志和分析导出。
- 针对可猜测或顺序公共令牌的枚举抵抗。
不包含在此范围内
- 行星级分布式 ID 分配（雪花算法风格的工作节点）。
- 认证令牌格式和会话标识符。
- 超出标识符排序影响的数据库分片键选择。
合约
- 每个持久化实体声明一个规范标识符字段，必要时声明单独的公共代理；代理是浏览器可见 URL 中唯一允许的值。
- 可排序标识符格式可用于存储索引，但列表 API 应基于显式时间戳或游标字段排序，而非让客户端从原始标识符字节推断顺序。
- 插入时发生冲突会消耗 profile 中 collision_retry_limit 的一次尝试，该限制计入包括初始生成在内的所有插入尝试；超出限制后写入失败，返回冲突错误且不进行静默覆盖。
- 结构化日志和支持导出最多存储配置的原始标识符哈希前缀，除非消费系统处于经审计的批准紧急路径。
- 启用枚举保护时，跨租户通过标识符或代理的资源查找对超出范围租户的存在提示以未找到相同错误形态拒绝。
- 迁移期间，遗留标识符格式在声明的双读窗口内保持可读；响应同时暴露规范和遗留别名字段，且不将任一视为所有权证明。
实现指导
- 在应用层或专用 ID 服务中生成标识符，使策略可独立于 ORM 默认值进行测试。
- 若选择时间排序格式，需记录嵌入标识符中的时间戳精度，并验证公共代理无法反向推断。
- 分页游标绑定为排序字段和标识符的签名元组，而非向客户端暴露原始单调序列。
失败处理与保障措施
- 时钟回退或生成器版本不匹配不得生成重复值或默默破坏声明的 UUIDv7/可排序合约。使用带随机尾部的单调 UUIDv7 回退方案，保持版本和排序策略；若无此实现，则写入失败并报警，而非在 UUIDv7 专用列中发出 UUIDv4。
- 当配置要求编辑时，绝不在 Web 服务器访问日志中记录完整标识符；若下游工具无法过滤，则在摄取时进行哈希处理。
- 对代理和标识符前缀的未认证查找进行速率限制，以减少共享链接扫描。
验证与运维
- 监测迁移期间的冲突重试率、枚举限流命中和双读解析失败。
- 测试公共 URL、API 负载和日志行均遵循
uuid-policy.yaml中的暴露矩阵。 - 证明列表端点在启用枚举保护时不发出单调公共序列号。
- 模拟时钟回退，验证每次成功回退仍为有效 UUIDv7，且在生成器声明范围内非递减。
本包中的可执行示例为固定装置和验收合约。先对包结构和元数据运行静态验证，再在目标仓库实现并执行场景。
采用假设
example.yaml中的名称和数值为采用配置文件，不是通用默认值。- 采用团队必须映射参与者、数据类别、错误词汇和所有权到其系统。
- RFC 9562 术语用于描述性，团队选择适合其技术栈的具体生成库。