Better Auth MongoDB Adapter 完整实战指南配置、ID 映射、索引、Join 与事务实现解析【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth导读本文围绕 Better Auth 官方 MongoDB 适配器better-auth/mongo-adapter展开系统讲解如何在认证服务中接入 MongoDB、完整配置mongodbAdapter()的四个核心选项client、transaction、debugLogs、usePlural并深入源码层剖析其 ID 类型映射ObjectId/UUID、查询操作符转换、聚合管道 Join、索引自动创建与事务实现。读完本文你将能够正确配置 MongoDB 作为 Better Auth 的持久化存储理解各配置项在生产环境副本集、限流、插件复合索引中的真实影响并能依据仓库测试用例验证适配器行为。一、适配器概述better-auth/mongo-adapter是 Better Auth 的官方 MongoDB 适配器位于仓库的 packages/mongo-adapter 目录当前版本为1.7.3见 package.json。它通过 Better Auth 的「适配器工厂Adapter Factory」机制将框架统一的数据库访问接口翻译为 MongoDB 的原生操作——集合读写、聚合管道Aggregation Pipeline、$regex查询与索引管理从而让认证、会话、组织、限流等功能平滑运行在 MongoDB 之上。该适配器的入口非常精简src/index.ts 仅有一行export * from ./mongodb-adapter全部实现集中在 src/mongodb-adapter.ts。适配器以mongodbAdapter(db, config?)工厂函数形式导出接收一个mongodb.Db实例与可选配置返回一个符合 Better AuthDBAdapter接口的适配器函数。从 package.json 可以看到它的依赖约束以mongodb^6.0.0 || ^7.0.0为可选的 peer dependency这意味着 MongoDB Node.js 驱动由使用方自行安装适配器本身只依赖better-auth/core与better-auth/utils。二、安装与最小接入示例安装使用 npm 安装适配器包与 MongoDB 驱动npm install better-auth/mongo-adapter mongodb仓库使用 pnpm workspace 管理包名与导出结构见 package.jsonESM 格式产物dist/index.mjs与类型声明dist/index.d.mts通过exports字段对外暴露。最小接入在认证配置中创建MongoClient取得Db实例后传入适配器import { betterAuth } from better-auth; import { MongoClient } from mongodb; import { mongodbAdapter } from better-auth/mongo-adapter; const client new MongoClient(mongodb://localhost:27017/database); const db client.db(); export const auth betterAuth({ database: mongodbAdapter(db, { // 可选传入 client 后数据库事务才会启用 client, }), });要点说明mongodbAdapter的第一个参数是Db实例来自client.db()不是连接字符串第二个参数为MongoDBAdapterConfig配置对象定义见 src/mongodb-adapter.ts所有字段均可选传入client是启用事务的必要条件详见下文「事务」一节。三、配置项详解MongoDBAdapterConfig接口定义在 src/mongodb-adapter.ts共四个可选项配置项类型默认值说明clientMongoClientundefinedMongoDB 客户端实例。若不提供数据库事务不会启用debugLogsDBAdapterDebugLogOptionfalse是否开启适配器调试日志usePluralbooleanfalse是否使用复数集合名如users而非usertransactionboolean见下文是否将多个操作放入一个事务中执行client事务的开关client决定了事务能力。从源码可以看出事务分支的启用条件是config?.client (config?.transaction ?? true)src/mongodb-adapter.ts只有提供了客户端实例且未显式关闭事务适配器才会在回调中通过client.startSession()开启会话并包裹事务。transaction单机部署必须显式关闭transaction的默认行为需要特别注意提供client时默认值为true启用事务若 MongoDB 实例不支持事务例如未配置副本集的 standalone 单机部署必须显式设置transaction: false否则会因事务不可用而报错。这一约束在配置接口的 JSDoc 中有明确警告src/mongodb-adapter.ts同时 e2e/adapter/test/mongo-adapter/adapter.mongo-db.test.ts 的适配器测试套件正是以transaction: false运行用于覆盖无事务的常规场景。生产环境选择副本集或分片集群可开启事务保证多文档操作的原子性单机部署务必显式关闭。usePlural集合命名usePlural控制模型名到集合名的映射。源码中适配器工厂配置为usePlural: config?.usePlural ?? falsesrc/mongodb-adapter.ts默认关闭时模型user对应集合user开启后对应users。建议与团队既有数据库的集合命名风格保持一致。debugLogs开启后输出适配器层的调试日志用于排查 SQL/查询翻译问题。默认false生产环境建议关闭。四、Schema 生成与迁移MongoDB 无需迁移MongoDB 是文档型数据库天然无固定表结构因此不需要生成或迁移 Schema。官方文档docs/content/docs/adapters/mongo.mdx明确指出For MongoDB, we dont need to generate or migrate the schema。但这不意味着适配器完全不管结构它承担了两类「结构治理」职责ID 字段映射框架统一的id字段映射到 MongoDB 的_idmapKeysTransformInput: { id: _id }输出时反向映射见 src/mongodb-adapter.ts索引自动创建插件 Schema 中声明的索引会在首次写入前自动创建详见下文「索引」一节。五、ID 类型映射ObjectId 与 UUIDMongoDB 驱动支持多种 BSON 类型适配器根据 Better Auth 的 ID 生成策略自动选择_id的存储类型默认未配置generateId_id使用 BSONObjectId配置advanced.database.generateId: uuid_id及外键字段使用 BSONUUID配置自定义generateId函数跳过类型强制转换直接使用生成值。这一逻辑分布在 src/mongodb-adapter.ts读取生成器、src/mongodb-adapter.tscoerceToIdType/isIdInstance以及customTransformInput/customTransformOutputsrc/mongodb-adapter.ts中写入时id字段与引用id的外键字段会被序列化为对应 BSON 类型数组形式的外键逐个转换非法值抛出MongoAdapterError(INVALID_ID, ...)读取时_id/外键会从ObjectIdtoHexString()或UUIDtoString()还原为字符串保证业务层拿到的是普通字符串 IDconsumeOne/update等操作通过includeResultMetadata: true从驱动返回的元数据中取回文档再执行输出转换见测试 packages/mongo-adapter/src/mongodb-adapter.test.ts。单元测试 packages/mongo-adapter/src/mongodb-adapter.test.ts 专门覆盖了 UUID 支持generateId: uuid时_id与userId均存储为UUID实例且格式符合 UUID 正则默认时存储为ObjectId查询结果中的 BSON UUID 会被转换回字符串。六、查询操作符的翻译与大小写不敏感支持适配器的convertWhereClausesrc/mongodb-adapter.ts将 Better Auth 的统一Where子句翻译为 MongoDB 查询条件核心规则如下Better Auth 操作符MongoDB 查询说明eq{ field: value }相等in{ field: { $in: [...] } }包含于not_in{ field: { $nin: [...] } }不包含于gt/gte{ field: { $gt / $gte: v } }大于 / 大于等于lt/lte{ field: { $lt / $lte: v } }小于 / 小于等于ne{ field: { $ne: v } }不等于contains{ field: { $regex: .*v.* } }包含starts_with{ field: { $regex: ^v } }前缀ends_with{ field: { $regex: v$ } }后缀约束与边界多条件通过$and/$or组合AND连接的条件进入$andOR连接的条件进入$orsrc/mongodb-adapter.ts未知操作符抛出MongoAdapterError(UNSUPPORTED_OPERATOR, ...)src/mongodb-adapter.ts所有$regex均经过escapeForMongoRegex转义上限 256 字符避免正则注入与超长输入见 src/query-builders.ts查询中的id字段统一改写为_idsrc/mongodb-adapter.ts。大小写不敏感查询1.6.0 起自1.6.0起适配器支持mode: insensitive的大小写不敏感查询见 CHANGELOG.md。实现位于 src/query-builders.ts通过$regex$options: i实现insensitiveEq^value$锚定全等insensitiveIn/insensitiveNotIn分别用$or/$nor组合多个正则insensitiveNe$not 正则insensitiveContains/insensitiveStartsWith/insensitiveEndsWith对应.*v.*/^v/v$模式注意只有字符串值或全字符串数组且字段不是 ID/外键时才走 insensitive 分支src/mongodb-adapter.ts。e2e 测试套件中通过caseInsensitiveTestSuite()统一验证e2e/adapter/test/mongo-adapter/adapter.mongo-db.test.ts。七、Join基于聚合管道的关联查询Better Auth 需要在单次查询中跨表取关联数据如/get-session、/get-full-organizationMongoDB 适配器自1.4.0起原生支持 Join。在认证配置中开启export const auth betterAuth({ advanced: { database: { joins: true, }, }, });官方文档docs/content/docs/adapters/mongo.mdx提到这类端点从 Join 特性中受益明显。适配器用$lookup聚合阶段实现关联src/mongodb-adapter.ts其实现细节本地字段与外部字段的id均映射为_id一对一关系外键字段声明了unique: true$lookup后追加$unwind展开为单个对象preserveNullAndEmptyArrays: true保证无匹配时字段为null一对多关系保留数组形态不执行$unwind限制条数非唯一关系且指定了limit时使用$lookup的 pipeline 子句语法let$expr$limit支持子查询限流limit缺省时回退到options.advanced?.database?.defaultFindManyLimit ?? 100字段裁剪select会被转换为$project投影并自动保留被 Join 的集合字段。findOne与findMany都完整实现了该流程最终通过aggregate(pipeline)执行src/mongodb-adapter.ts。e2e 的joinsTestSuite()覆盖了该能力e2e/adapter/test/mongo-adapter/adapter.mongo-db.test.ts。八、索引首次写入前的自动创建从1.7.0起见 CHANGELOG.md插件数据库 Schema 中声明的跨字段表级索引含复合唯一索引会由 MongoDB 适配器在首次「索引约束写入」前自动创建与 SQL 方言的迁移能力对齐。核心实现为ensureModelIndexessrc/mongodb-adapter.ts通过resolveDatabaseTableIndexes解析 Schema 中的索引定义字段名、唯一性、自定义名称将框架字段名映射为物理字段名id→_id构造createIndex调用db.collection(model).createIndex(indexFields, { name, unique })去重与缓存索引定义序列化为 key 存入indexSetupByDefinitionMap相同定义的并发写入共享同一个创建 Promise避免重复建索引失败时清理缓存以便重试索引创建发生在create、update、updateMany、incrementOne等写操作之前而deleteMany、consumeOne等读删操作不会触发disableMigrations测试中写作disableMigration为true的模型跳过索引创建。单元测试对这三条行为均有断言复合索引在首次写入前创建、多次写入只创建一次packages/mongo-adapter/src/mongodb-adapter.test.ts每模型只解析一次索引定义packages/mongo-adapter/src/mongodb-adapter.test.ts禁用迁移的表不建索引packages/mongo-adapter/src/mongodb-adapter.test.ts。e2e 的compoundIndexTestSuite更进一步验证真实 MongoDB 中的索引键与名称如{ issuer_url: 1, provider_subject: 1 }、compound_identity_uidx并验证同名但结构不匹配的索引会被拒绝e2e/adapter/test/mongo-adapter/adapter.mongo-db.test.ts。九、事务与会话当client提供且transaction未关闭时适配器通过 MongoDB 会话实现多操作事务src/mongodb-adapter.tsconfig.client.startSession()创建会话并startTransaction()使用该会话重新构建一个关闭内部事务的适配器实例transaction: false所有读写经{ session }传递回调成功后commitTransaction()异常则abortTransaction()finally中endSession()。这意味着事务内的每个 CRUD 操作都携带会话参数如insertOne(values, { session })、aggregate(pipeline, { session })、findOneAndUpdate(clause, update, { session })等保证事务原子性。再次强调单机 standalone MongoDB 不支持事务必须transaction: false。十、原子计数incrementOne 与限流场景Better Auth 的数据库限流、API Key 用量等场景需要原子递增计数。自1.6.17起各适配器原生实现incrementOne为单条原子语句见 CHANGELOG.md。MongoDB 实现基于findOneAndUpdatesrc/mongodb-adapter.tsincrement编译为$incset编译为$set在同一个findOneAndUpdate中原子执行通过 where 条件如count 5充当守卫条件满足才更新空更新保护$inc: {}在 MongoDB 5.0 以下会报错因此increment为空时省略$incset为空时省略$set两者皆空则直接退化为findOne读取若increment与set同时为空则抛出「incrementOne requires a non-empty increment or set」错误这属于better-auth/core的上层校验返回returnDocument: after的更新后文档未命中守卫则返回null。测试逐一验证了这些分支packages/mongo-adapter/src/mongodb-adapter.test.ts$inc$set组合、仅$inc省略$set、仅$set省略$inc、空更新拒绝、守卫不命中返回null。十一、CRUD 全量操作速览适配器通过createAdapterFactory装配src/mongodb-adapter.ts对外暴露完整的DBAdapter方法集方法MongoDB 实现说明createinsertOne写入前确保索引返回含_id的完整文档findOne/findManyaggregate$match→$lookup→$project→$sort/$skip/$limit完整聚合管道查询countaggregate$match→$count无匹配返回 0updatefindOneAndUpdate$set返回更新后文档updateManyupdateMany$set返回修改条数delete/deleteManydeleteOne/deleteMany后者返回删除条数consumeOnefindOneAndDelete消费型读取如验证码一次性使用incrementOnefindOneAndUpdate$inc/$set原子计数限流/用量consumeOne的实现在 src/mongodb-adapter.ts通过findOneAndDeleteincludeResultMetadata: true取回被删除文档测试验证其返回结构packages/mongo-adapter/src/mongodb-adapter.test.ts。十二、测试与验证仓库为该适配器提供了两层测试单元测试packages/mongo-adapter/src/mongodb-adapter.test.ts使用 mock 的Db实例验证索引创建时序、UUID/ObjectId 映射、incrementOne各分支、consumeOne返回结构等无需真实数据库即可运行npm test/vitest脚本见 package.jsone2e 测试e2e/adapter/test/mongo-adapter/adapter.mongo-db.test.ts连接真实 MongoDB默认mongodb://127.0.0.1:27017、库名better-auth运行normalTestSuite、authFlowTestSuite、transactionsTestSuite、joinsTestSuite、caseInsensitiveTestSuite、uuidTestSuite、compoundIndexTestSuite以及「update 后 ID 仍为 ObjectId」的专项套件全面验证适配器与 Better Auth 核心的集成行为。十三、性能与生产建议官方文档docs/content/docs/adapters/mongo.mdx建议参考 docs/content/docs/guides/optimizing-for-performance.mdx 获取性能优化指引如索引规划、连接池等开启joins: true可减少会话/组织类端点的往返次数一对一关系利用unique字段触发$unwind扁平化避免应用层二次处理生产环境请结合自身数据访问模式为查询字段建立合适的普通索引适配器自动创建的仅限插件 Schema 中声明的索引单机部署务必transaction: false副本集/分片集群可按需开启事务使用generateId: uuid时确保所有外键写入同样经过适配器转换保持_id与引用字段类型一致。十四、许可与延伸阅读该适配器以 MIT 协议开源见 packages/mongo-adapter/README.md 与 package.json。想进一步深入可以从以下仓库文件开始适配器核心实现packages/mongo-adapter/src/mongodb-adapter.ts查询构造器大小写不敏感与正则转义packages/mongo-adapter/src/query-builders.ts官方使用文档docs/content/docs/adapters/mongo.mdx变更记录packages/mongo-adapter/CHANGELOG.mde2e 集成测试e2e/adapter/test/mongo-adapter/adapter.mongo-db.test.ts【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考