dsh-sansheng-liubu/workbench/core/ids.mjs

82 lines
3.3 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

// 稳定随机 ID:所有业务主键都由这里生成,名称/路径只作属性,不复用为键。
// 随机源可注入,测试里给定字符表就能复现同一串 ID,避免断言依赖运气。
const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
/** 方案里出现的所有前缀;拼错前缀属于开发期错误,直接抛而不是静默接受。 */
export const ID_PREFIXES = Object.freeze({
project: 'proj',
binding: 'bind',
config: 'cfg',
task: 'task',
dispatch: 'dsp',
attempt: 'att',
contextPacket: 'ctx',
result: 'res',
artifact: 'art',
event: 'evt',
authorization: 'auth',
})
export const ID_ENTITIES = Object.freeze(Object.keys(ID_PREFIXES))
/** 默认随机源:crypto.getRandomValues,取 0..35 的字符。 */
export function cryptoRandom() {
const crypto = globalThis.crypto
if (!crypto || typeof crypto.getRandomValues !== 'function') {
throw new Error('缺少可用的随机源,请注入 random 参数')
}
const bytes = crypto.getRandomValues(new Uint8Array(8))
// 除 36 取余有轻微偏差,但只用于 ID 唯一性,不用于安全令牌。
return ALPHABET[bytes[0] % ALPHABET.length]
}
/**
* 注入的随机源可以返回数字(映射到字母表)或单个字符(必须来自字母表)。
* 两种都接受是为了测试能写 `() => 0` 这样最直白的桩。
*/
function pick(random, index) {
const value = random(index)
if (typeof value === 'number') {
if (!Number.isInteger(value)) throw new Error('随机源必须返回整数或字母表内字符')
// 随机源常被测试当作递增计数器使用,数值可能超过字母表长度甚至为负;
// 先取绝对整数再取模,保证任意整数都能映射到合法字符。
return ALPHABET[Math.abs(value) % 36]
}
const char = String(value)
if (char.length !== 1 || !ALPHABET.includes(char)) throw new Error(`随机源返回了字母表外字符: ${char}`)
return char
}
/**
* 生成 `<prefix>_<随机串>`。
* 前缀既可用实体名('task')也可用前缀本身('task'),两者一致时可省心。
*/
export function newId(prefix, options = {}) {
const { random = cryptoRandom, length = 12 } = options
const known = ID_PREFIXES[prefix]
const resolved = known ?? (Object.values(ID_PREFIXES).includes(prefix) ? prefix : undefined)
if (resolved === undefined) throw new Error(`未知 ID 前缀: ${prefix}`)
if (!Number.isInteger(length) || length < 4 || length > 64) throw new Error('ID 随机串长度须为 4..64')
let out = ''
for (let index = 0; index < length; index += 1) out += pick(random, index)
return `${resolved}_${out}`
}
/** 每个实体一个绑定好随机源的生成器,便于在服务层统一注入并保持测试确定性。 */
export function createIdFactory(options = {}) {
const { random = cryptoRandom, length = 12 } = options
const factory = {}
for (const entity of ID_ENTITIES) {
factory[entity] = () => newId(ID_PREFIXES[entity], { random, length })
}
return Object.freeze(factory)
}
/** 校验外部传入的 ID 形状(防伪 ID 进账;存在性仍由 store 查表)。 */
export function isIdOf(entity, value) {
const prefix = ID_PREFIXES[entity]
if (typeof value !== 'string' || typeof prefix !== 'string') return false
return value.startsWith(`${prefix}_`) && value.length > prefix.length + 1
}