---
url: /docs/specs/prefixed-ids.md
---
# 带前缀的数据库标识

## 格式

实体标识使用三位小写前缀、下划线和 16 位 CUID2，共 20 字符，例如 `usr_ght4k2jxm7pqbv01`。前缀帮助日志排查，客户端应将完整值作为不透明字符串，不用前缀判断权限。

| 认证模型                        | 前缀  |
| ------------------------------- | ----- |
| `user`                          | `usr` |
| `session`                       | `ses` |
| `account`，映射到 `identity` 表 | `idn` |
| `verification`                  | `vfy` |
| `organization`                  | `org` |
| `member`                        | `mem` |
| `invitation`                    | `inv` |
| `passkey`                       | `pky` |
| `apikey`                        | `key` |
| `subscription`                  | `sub` |

工具记录和积分流水分别使用 `run` 和 `crd`。映射和生成器位于 `db/schema/id.ts`。

私有文件使用 `fil`，任务使用 `tsk`，任务执行记录使用 `tat`；输入引用以任务 ID 为主键。用户密钥签发请求使用 `kis`，用户密钥使用 `key`；明文凭据的 `abk_` 前缀与数据库 ID 分开。前缀仍不能作为授权证据。

## 调用

```ts
import { generateAuthId, generateId } from "@repo/db";

const userId = generateAuthId("user");
const uploadId = generateId("upl");
```

认证模型必须出现在前缀映射；普通前缀必须是恰好三个小写字母，否则抛错。生成器惰性初始化，避免模块加载时不必要副作用。

Better Auth 的自定义生成器与 Drizzle 的 `.$defaultFn()` 使用同一约定。直接 SQL 不会执行应用层默认函数，插入时要显式提供标识。

## 新增模型

认证模型先增加映射及类型，再同步插件和数据库模型。普通业务模型选择未混淆的三位前缀并配置应用默认生成器。结构改变后生成并审查迁移；仅改变生成函数不会自动重写已有数据。