「ID 标识生成」是数据鱼API平台提供的唯一标识批量生成接口,Base 路径 /api/id,共 3 个方法路由(健康检查、以及同一路径下的 GET 与 POST 两种提交方式)。它把常见的几种分布式 ID 方案收敛到一个 HTTP 调用里:调用方指定类型与数量,服务端一次返回一个字符串数组,省去在每种语言里重复引入与调试 ID 库的成本。
接口支持三种类型。snowflake 为默认值,按 64 位结构拼接时间戳、机器号与序列号,输出十进制字符串;ulid 输出 26 位 Crockford Base32 字符串,前 10 位编码毫秒时间,后 16 位随机;nanoid 输出指定长度的随机字符串,默认 21 位,字符表去掉了容易混淆的字符。三类方案都可直接用作数据库主键、消息去重键、短链参数或缓存键。
生成过程无状态,服务端不记录已发出的 ID,也不维护全局序列。这意味着唯一性依赖算法本身的位分配:Snowflake 依赖机器号不重复,ULID 与 NanoID 依赖随机位。数据鱼API在这一接口上只提供生成能力,不提供 ID 的登记、回收或冲突检测,调用方需要根据业务对唯一性的要求选择合适的类型与位数。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/id/ping | 健康检查,返回服务版本 | 文档标注免鉴权 |
GET | /api/id/generate | 通过查询参数生成一批 ID | 是 |
POST | /api/id/generate | 通过 JSON body 或表单生成一批 ID | 是 |
鉴权使用全站统一 Key,X-API-Key 请求头或 ?api_key= 查询参数任选其一,缺失返回 4011,无效返回 4013。响应统一为 code、msg、data 结构,code 为 0 表示成功。GET 与 POST 指向同一处理逻辑,参数名完全一致,POST 可提交 JSON body 也可提交表单,批量生成时更适合用 POST 以免查询串过长。
文档列出的错误码包含 4001、4002、4004、4011、4013 与 5032,但当前生成逻辑对参数采取宽松处理:类型不认识时回退到 Snowflake,数量越界时截断到合法区间,因此实际很少返回参数类错误。这种宽容策略降低了接入门槛,也意味着调用方不能依赖错误码来发现拼写错误的类型名。
按类型与数量生成 ID 数组。
参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
type | string | 否 | snowflake | 生成算法,支持 snowflake、ulid、nanoid;其他取值会回退为 Snowflake |
count | string | 否 | 1 | 生成数量,实现会截断到 1 至 100 之间 |
size | string | 否 | 21 | 仅对 nanoid 生效,指定输出字符长度 |
worker | string | 否 | 1 | 仅对 snowflake 生效,机器号,参与 10 位位段计算 |
返回的 data 有三个字段:type 原样回显请求中的类型字符串,ids 为字符串数组,count 为实际生成条数。需要注意 type 的回显值与实际算法可能不一致——传入 uuid 时,ids 是按 Snowflake 生成的,而 type 仍写作 uuid。判断实际类型应看 ID 的形态,而不是回显字段。
GET /api/id/generate?api_key=YOUR_KEY&type=ulid&count=3POST /api/id/generate?api_key=YOUR_KEY
Content-Type: application/json
{"type":"nanoid","count":2,"size":16}{
"code": 0,
"msg": "success",
"data": {
"type": "nanoid",
"ids": ["V1tRk9mQ2xLpA7Zs", "b4YhNc8Wq3JfD6Ke"],
"count": 2
}
}无请求参数,返回服务版本信息,用于探活与部署确认。文档标注该端点免鉴权,实际是否放行取决于网关配置;在统一鉴权的部署环境中,携带 Key 调用更稳妥。
count 被限制在 1 至 100,超出范围不会报错,而是静默截断到边界值。worker 与 1023 做按位与运算,超过 1023 的取值会回绕,多实例部署时必须保证各实例的 worker 互不相同。size 控制,默认 21;size 未做上限校验,传入过大会显著增加响应体积与计算时间。新业务建表时批量预生成主键,交给应用层按需取用,避免在数据库侧依赖自增列。消息队列的消费端用 ULID 作为消息去重键,兼顾时间有序与随机性。短链或邀请码场景用 NanoID 生成不易猜测的短标识,并按需要调整长度。压测或数据填充阶段一次申请上百个 ID,用于构造测试数据集。
type 的静默回退是最容易踩的坑:拼写错误不会报错,返回的仍是合法 ID,但算法与预期不符,type 字段还会原样回显错误值,给排查带来干扰。建议调用方在客户端维护一份白名单,先校验再请求。count 的静默截断同理,需要超过 100 个 ID 时应分批调用,并自行拼接结果。
Snowflake 的唯一性前提是机器号不冲突。多实例部署时若都使用默认值 1,同一毫秒内可能生成重复 ID;正确做法是为每个实例分配独立 worker,并确保不超过 1023。ULID 在同一毫秒内的多个值只靠随机位区分,排序应按字符串整体比较而不是按时间前缀。NanoID 的 size 没有边界保护,生产环境应限制在合理范围。
本接口生成的是技术层面的标识符,仅用于数据定位与引用,不构成实名认证,也不能作为自然人身份证明。数据鱼API不校验 ID 与任何真实主体的对应关系,涉及用户身份的环节仍需独立完成核验。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。