RedwoodRecord 实战指南：基于 Prisma 的 Redwood 原生 ORM 全解析

后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载RedwoodRecord 是 Redwood 框架内置的实验性 ORM对象关系映射层它构建在 Prisma 之上提供了一套类似 Ruby on Rails ActiveRecord 的自然数据访问接口。本文将带你从零开始掌握 RedwoodRecord 的模型定义、增删改查、校验与关联关系操作并深入到 packages/record 源码内部理解其底层实现原理让你能直接在实际的 Redwood 应用中运用这套数据访问层。说明RedwoodRecord 目前在 Redwood 中仍处于Experimental实验性状态。官方希望社区先行试用并反馈意见以帮助打磨其开发体验。在 v6 版本中它对应的文档为 docs/versioned_docs/version-6.x/redwoodrecord.md本文即以此为核心骨架展开。一、RedwoodRecord 是什么RedwoodRecord 是一个构建在 Prisma 之上的 ORM对象关系映射库未来可能会扩展为封装其他数据库访问包。它深受 Ruby on Rails 中 ActiveRecord 的启发旨在为数据库中的底层数据提供一种自然的访问接口让开发者不必关心 SQL 语法的细节。从源码结构看RedwoodRecord 由 5 个核心类组成见 packages/record/README.md 与 packages/record/src/index.js类名职责Core为单个模型提供核心数据库访问能力实现 CRUD 操作见 Core.jsReflection解析 Prisma 数据模型判断当前模型与哪些模型存在hasMany/belongsTo关系见 Reflection.jsRelationProxy提供对关联模型的访问代理自动合并关联条件见 RelationProxy.jsValidationMixin增加校验支持与错误消息收集能力见 ValidationMixin.jsRedwoodRecord组合以上四个类的功能是所有模型应继承的标准基类见 RedwoodRecord.js此外还有一个 errors.js 文件集中定义了 RedwoodRecord 可能抛出的所有错误类型。在 RedwoodRecord.js 中可以看到标准基类的继承关系是RedwoodRecord extends ValidationMixin(Core)即先以 Core 提供数据库能力再叠加校验能力最后挂上reflectReflection 实例与关系代理的挂载逻辑。二、背景与核心术语在使用 RedwoodRecord 之前你需要为计划访问的每张数据库表创建对应的类。假设我们有一个博客应用包含三张数据库表┌───────────┐ ┌────────────┐ ┌────────────┐ │ User │ │ Post │ │ Comment │ ├───────────┤ ├────────────┤ ├────────────┤ │ id │•──┐ │ id │•──┐ │ id │ │ name │ └──│ userId │ └─│ postId │ │ email │ │ title │ │ name │ └───────────┘ │ body │ │ message │ └────────────┘ └────────────┘用数据库术语来说从左到右看这些表之间是**一对多one-to-many**关系一个 User 可以拥有多个 Post一个 Post 可以拥有多个 Comment。图中箭头上的•表示一one表示多many。只说一对多其实已经涵盖了关系的两侧但有时从相反方向描述会更方便。从右往左读这张图一个 Comment **属于belongs to**一个 Post它拥有外键postId通过Comment.postId→Post.id指向 Post一个 Post 属于一个 UserPost.userId→User.id。此外还有**多对多many-to-many**关系例如 Product 和 Category——一个 Product 可以关联多个不同的 Category一个 Category 也会关联多个不同的 Product┌───────────┐ ┌────────────┐ │ Product │ │ Category │ ├───────────┤ ├────────────┤ │ id │─────│ id │ │ name │ │ name │ │ upc │ │ shelf │ └───────────┘ └────────────┘这两张表之间没有外键既没有productId也没有categoryId那么它们如何互相追踪呢通常你需要在两者之间创建一张连接表join table引用双方的外键┌───────────┐ ┌───────────────────┐ ┌────────────┐ │ Product │ │ ProductCategory │ │ Category │ ├───────────┤ ├───────────────────┤ ├────────────┤ │ id │•────│ productId │ ┌──•│ id │ │ name │ │ categoryId │──┘ │ name │ │ upc │ └───────────────────┘ │ shelf │ └───────────┘ └────────────┘这样我们又回到了一对多的模型。在 Prisma 中这种连接表可以由框架自动创建和维护它会被命名为_CategoryToPost这类形式外键统一命名为A和B分别指向两张表。Prisma 将这种形式称为**隐式多对多implicit many-to-many**关系。如果你想自己创建连接表并有可能在其中存储额外数据比如记录产品被归类的时间戳那么这其实就变成了两侧各自的一对多关系一个 Product 拥有多个 ProductCategory一个 Category 也拥有多个 ProductCategory。Prisma 将这种形式称为**显式多对多explicit many-to-many**关系。最后需要区分两个术语模型model与记录record。模型代表一张数据库表的类。上面的例子中有三个模型User、Post 和 Comment。Prisma 在其schema.prisma声明文件中把每张表也叫做model但本文中的模型特指继承了RedwoodRecord的类。记录模型的一个实例代表数据库中某一行的数据。所以我用 User 模型在数据库中找到某个用户假设找到了我就拥有了一条用户记录User 模型的一个实例。三、快速上手1. 安装依赖你需要将 RedwoodRecord 的包添加到 api 侧yarn workspace api add redwoodjs/record2. 定义模型类首先为你要访问的数据库表创建一个模型。在我们的博客示例中创建一个 User 模型import { RedwoodRecord } from redwoodjs/record export default class User extends RedwoodRecord { }3. 初始化解析 Prisma schema接下来需要解析 Prisma schema将其缓存为 JSON 文件并创建一个带若干配置项的index.jsyarn rw record init运行后你会发现它在api/src/models/下创建了datamodel.js和index.js两个文件。从 packages/record/README.md 的 Tasks 一节可知其原理RedwoodRecord 依赖读取 Prisma schema 文件来判断与其他表的关系。为了避免每次都用 Prisma 内置函数异步解析 schema 造成等待项目提供了一个任务脚本见 packages/record/src/tasks/parse.js它会解析 schema 文件并把 JSON 版本保存到.redwood缓存目录中同时它还会在api/src/models目录中生成一个index.js负责导入各模型本身并加入一些配置以支持在避免循环依赖的情况下解析关联关系最后将模型重新导出。需要特别留意的是每当你新建模型或者以增删关系的方式修改数据库 schema 时都需要重新运行yarn rw record init。官方计划未来让该任务自动运行、监听schema.prisma或 models 目录的变化但当前版本仍需手动执行。4. 在 Redwood 控制台或应用代码中试运行相信你已经发现了以上步骤就足以开始使用了可以尝试用 Redwood 控制台快速执行一些查询而无需启动任何服务器yarn rw c这会进入一个标准的 Node REPL但已经预加载了大量 Redwood 能力。首先引入我们的模型const { User } require(./api/src/models)然后就可以开始查询和修改数据了await User.all() const newUser await User.create({ name: Rob, email: robredwoodjs.com }) newUser.name Robert await newUser.save() await User.find(1) await User.findBy({ email: robredwoodjs.com }) await newUser.destroy()⚠️ 注意文档中的已知限制在 Redwood 控制台中模型还无法完全正常工作。上面的require和记录获取可以执行但真正读取任何属性会返回undefined。当前阶段你需要直接在应用代码中测试 RedwoodRecord。四、初始化与保存记录build()仅内存中构建build()用于在内存中创建一条新记录尚未保存到数据库const user User.build({ firstName: David, lastName: Price })注意build只是构建内存中的记录不是异步的而其他与 Prisma/数据库交互的模型方法则是异步的。从 Core.js 的源码可以看到build的实现是实例化一个记录并把属性对象赋给record.attributes。而在 RedwoodRecord.js 中build被覆写调用父类build之后还会通过RelationProxy.addRelations把基于 schema 解析出的关系属性挂到记录实例上——这正是记录能直接访问关联模型的关键一步。save()落库save()会自动判断应该创建还是更新如果记录已有主键primaryKey对应字段有值则执行update否则执行create。见 Core.js 中的实现。保存成功后会用数据库返回的最新属性回填记录以防其他并发操作修改过数据。对于build()出来的记录用save()即可存入数据库const user User.build({ name: Rob Cameron }) await user.save()create()一步创建create()等价于build()后立即save()见 Core.js。如果保存失败create会返回false而不是记录实例如果你在保存失败时仍需要拿到新的模型实例请使用build()版本await User.create({ name: Tom Preston-Werner }) await User.create({ firstName: Rob, email: robredwoodjs.com }, { select: [email] })第一个参数是交给 Prismacreate()的数据第二个可选参数是透传给 Prisma 的附加属性。五、错误处理与校验errors 与 hasError当一条记录无法保存无论是数据库错误还是下面的校验错误errors属性会被填充对应的错误消息const user User.build({ name: Rob Cameron }) await user.save() // false user.hasError() // true user.errors // { base: [], email: [must not be null] } user.errors.email // [must not be null]注意hasError在 ValidationMixin.js 中是一个getter属性而非方法文档示例中的user.hasError()加括号写法在真实 API 中会报错正确用法是user.hasError。它只反映当前错误对象的状态不会重新触发校验。base 特殊键base是errors对象中的一个特殊键用于存放不针对单个属性如email的错误。例如当你尝试删除一条已经不存在的记录可能在你读取与删除之间被其他人删掉了就会在base上得到错误user.errors.base // [User record to destroy not found]这条错误消息的生成逻辑见 Core.js当 Prisma 抛出 Record to delete does not exist 时RedwoodRecord 会把它转成{模型名} record to destroy not found并挂到base上。isValid预检你可以用isValid在真正修改记录前预先检查错误——但只能捕获能通过校验规则validation发现的错误const user User.build({ name: Rob Cameron }) user.isValid // false user.errors.email // [must be formatted like an email address]从源码看isValid会调用validate()然后返回!hasError见 ValidationMixin.js。注意它会重置你用addError()手动添加的自定义错误。定义校验规则static validates记录在保存前可以用与 Service Validations 相同的校验类型详见 services.md 中的 absence 等章节来检查数据合法性export default class User extends RedwoodRecord { static validates { email: { presence: true, email: true }, username: { length: { min: 2, max: 50 } } } } const user User.build({ username: r }) await user.save() // false user.errors.email [must be present] user.errors.username [must be at least 2 characters] user.email robredwoodjs.com user.username rob await user.save()从 ValidationMixin.js 的实现看validate()会先清空所有错误再遍历static validates中的每个字段调用redwoodjs/api的validate函数逐个检查任一字段失败就把错误消息通过addError()追加到对应属性名下。而 RedwoodRecord.js 覆写了save()数据不合法时根本不会触碰数据库直接返回false除非显式传入{ throw: true }。六、查询记录RedwoodRecord 为模型提供了多种查询方式有时你想找多条记录匹配某些条件的所有记录有时只想找一条比如某个邮箱地址对应的那一条。where()多条件查询多条where()用于查找多条记录返回模型记录数组。第一个参数是通常作为 PrismafindMany()的where值的属性第二个可选参数是任何附加属性如排序orderBy、限制条数等会作用于返回的结果集await User.where() // 返回所有记录 await User.where({ emailPreference: weekly }) await User.where({ theme: dark }, { orderBy: { createdAt: desc } })源码层面where()调用this.accessor.findMany({ where: attributes, ...options })并把每条数据库记录build()成模型实例后批量返回见 Core.js。这里的accessor是 Prisma Client 上的模型访问器默认取类名的 camelCase 形式如User对应db.user也可以显式覆盖详见下文。all()取全部all()只是where()的同义词但能更清晰地表达我就是要选出全部记录可选排序的意图。它的第一个也是唯一的参数直接就是附加属性如sort、orderByawait User.all() await User.all({ orderBy: { lastName: asc } })在 Core.js 中all()的实现正是where({}, args)。find()按主键查找单条find()按记录的主键查找单条记录。默认主键是id但你可以通过在类定义中声明来改变主键export default class User extends RedwoodRecord { static primaryKey ident }这个调用在找不到记录时会抛出错误如果你按 ID 选用户显然期望该用户存在所以不存在属于异常情况。其底层使用 Prisma 的findFirst()函数await User.find(123)从 Core.js 可以看到find()内部以{ [primaryKey]: id }为条件调用findBy()若返回null则抛出RedwoodRecordNotFoundError。该错误类定义在 errors.js。findBy()按条件查找单条findBy()按一定条件查找单条记录。与where()类似但只返回第一条匹配的记录。第一个参数是通常作为 PrismafindFirst()的where值第二个可选参数是在选取一条记录之前应用的附加属性如排序、限制await User.findBy({ email: robredwoodjs.com }) await User.findBy({ email: { endsWith: { redwoodjs.com } } }, { orderBy: { lastName: asc }, take: 10 })如果没有找到匹配的记录返回null见 Core.js。first()取第一条first()是findBy()的别名见 Core.js用于表达从可能匹配的多条记录里取第一条的意图const randomCoreMember await User.first({ email: { endsWith: { redwoodjs.com } } })七、更新记录更新记录有两种方式1) 用一次update()调用列出所有要修改的属性2) 手动设置属性后调用save()。update()在记录上调用update()把要修改的属性作为第一个参数传入。第二个可选参数是透传给 Prisma 的任何属性。若记录未保存成功返回false否则返回自身已带新保存的属性const user await User.find(123) await user.update({ email: rob.cameronredwoodjs.com }) // 或 await user.update({ email: rob.cameronredwoodjs.com }, { throw: true })update()的实现是先把新属性合并进#attributes再委托给save()见 Core.js。save()对记录保存修改。第一个可选参数包含要透传给 Prisma 的属性以及保存失败时是否抛错const user await User.find(123) user.email rob.cameronredwoodjs.com await user.save() // 或 await user.save({ throw: true })关于{ throw: true }默认保存失败时save()返回false传入该选项则会抛出异常。在 Core.js 的_saveErrorHandler中错误会被归类映射为不同错误类型——更新目标不存在时抛RedwoodRecordNotFoundErrormust not be null时抛RedwoodRecordNullAttributeErroris missing时抛RedwoodRecordMissingAttributeError其余情况抛RedwoodRecordUncaughtError全部定义于 errors.js。八、删除记录删除记录非常简单。注意不实例化模型即可删除一条或多条记录的类级删除函数即将推出当前版本需要先拿到记录实例。destroy()在记录上调用destroy()即可在数据库中删除它。第一个可选参数是透传给 Prisma 删除操作的任何属性以及删除失败时是否抛错的选项。删除失败返回false否则返回记录自身const user await User.find(123) await user.destroy() // 或 await user.destroy({ throw: true })九、关联关系Relationships如背景与核心术语所述RedwoodRecord 提供了一种获取关联模型数据的方式——通过所谓的关系代理relation proxy。例如获取某个用户的所有帖子const user await User.find(123) const posts await user.posts.all()在这个例子中posts就是代理。模型上所有常规的查找方法where()、all()、find()、findBy()都可以在关系代理上调用。还不止这些你还可以通过代理创建记录它会自动关联到父记录const user await User.find(123) const post await user.posts.create({ title: Related post! }) post.userId // 123从 RelationProxy.js 的源码可以看到create()会把关系的where条件即外键约束如{ userId: 123 }自动合并进新建记录的属性中因此新记录天然带上了正确的userId。在 RedwoodRecord.test.js 的测试中也验证了User.build({})之后user.posts是RelationProxy的实例。一对多one-to-many多侧的记录通过关系代理访问const user await User.find(123) const post await user.posts.first() const comments await post.comments.all()同样可以创建记录const user await User.find(123) const post await user.posts.create({ title: Related post! })属于belongs-tobelongs-to 关系意味着你持有的是子记录想要的是父记录。belongs-to 关系中永远只有一个父记录所以不需要关系代理属性——只会返回一条记录const post await Post.first() const user await post.user从 RelationProxy.js 看belongs-to 属性被定义为一个async get()内部以{ [父表主键]: record[外键] }为条件调用findBy()。因此post.user返回的是一个 Promise需要await。当前版本尚不支持通过父记录直接创建 belongs-to 记录官方表示正在研究相应的语法。多对多many-to-many如果你的关系是隐式多对多访问方式与一对多类似const product await Product.find(123) const categories await product.categories.all()在 RelationProxy.js 中可以看到隐式多对多的特殊处理因为连接表没有真实外键foreignKey为null代理会构造一个 Prisma 的多对多过滤条件{ categories: { some: { id: product.id } } }并通过connect语法实现关联创建。如果你的关系是显式多对多则需要把它当成两步请求来处理第一步先取连接表上的一对多第二步再取你真正想要数据的属于关系Product - one-to-many - ProductCategories - belongs-to - Category ------- ----------------- --------const product await Product.find(123) const productCategories await product.productCategories.all() const categories await Promise.all(productCategories.map(async (pc) await pc.category))如果要这样创建新记录你需要先在关系两侧创建/获取记录再创建连接表记录const product await Product.find(123) const category await Category.find(234) await ProductCategory.create({ productId: product.id, categoryId: category.id })官方正在改进该语法目标是让显式多对多的交互与隐式版本一样简单。文档中预告的改进方向是从手动遍历product.productCategories.all()再逐条取pc.categories.all()简化为直接product.categories.all()。requiredModels关联模型注册有一点容易被忽略为了让关系代理找到目标模型父模型的类上需要声明requiredModels。例如在测试代码中可以看到class User extends RedwoodRecord {} User.requiredModels [Post, Comment]如果在 schema 中声明了关系但未在requiredModels中列出对应的 Redwood 模型RelationProxy.js 会输出一条警告日志跳过该关系。这是避免循环依赖的关键设计index.js生成时加入的配置正是用于组织这些模型引用。十、生命周期回调即将推出以下功能正在开发中尚不包含在当前实验性版本中。即将到来的是围绕记录生命周期创建函数的能力。例如为新创建的用户设置默认偏好你可能想要一个afterCreate回调来调用某个函数语法尚未最终确定export default class User extends RedwoodRecord { static afterCreate async (user) { await user.preferences.create({ email: weekly }) } }或者确保用户在关闭账号前先转移数据的所有权export default class User extends RedwoodRecord { static beforeDestroy async (user) { if (await user.teams.count() ! 0) { throw new Error(Please transfer ownership of your teams first) } } }十一、进阶自定义数据库访问与主键在使用 RedwoodRecord 时有两个类属性值得了解均定义于 Core.jsaccessorName覆盖数据库访问器名称。默认取类名的 camelCase 形式如User类对应db.user如果模型类名与 Prisma 中的模型名不一致可以显式声明static accessorName users。primaryKey覆盖主键字段名默认id如前面find()一节中的static primaryKey ident。此外static db用于挂载 Prisma Client 实例static schema则保存解析后的 Prisma 数据模型由record init生成的datamodel.js提供static validates存放校验规则。结语RedwoodRecord 为 Redwood 应用提供了一套贴近 ActiveRecord 心智模型的数据访问层模型类 记录实例 关系代理 声明式校验。虽然目前仍处于实验阶段但通过yarn rw record init与几行模型类定义即可获得一套统一、自然的 CRUD 与关联操作体验。其底层实现Core、Reflection、RelationProxy、ValidationMixin 四类协作清晰地展示了解析 Prisma schema → 反射关系 → 代理合并条件 → 校验落库的完整链路。想要深入了解实现细节的读者可以继续阅读 packages/record/README.md 与 packages/record/src/redwoodrecord/tests/ 目录下的测试用例。赞分享后端前端Web框架开发工具【免费下载链接】redwoodRedwoodGraphQL项目地址https://gitcode.com/gh_mirrors/re/redwood点击查看免费下载相关推荐RedwoodRecord 使用指南基于 Prisma 构建的 Redwood 原生 ORMRedwoodRecord 使用指南基于 Prisma 构建的 Redwood 原生 ORM 本文基于 docs/versioned_docs/version后端前端Web框架开发工具RedwoodRecord 实战指南Redwood 框架中基于 Prisma 的 ActiveRecord 风格 ORMRedwoodRecord 实战指南Redwood 框架中基于 Prisma 的 ActiveRecord 风格 ORM RedwoodRecord 是 Re后端前端Web框架开发工具Redwood 3.x 中的 RedwoodRecord基于 Prisma 的声明式 ORM 完整实战指南Redwood 3.x 中的 RedwoodRecord基于 Prisma 的声明式 ORM 完整实战指南 RedwoodRecord 是 Redwood 框后端前端Web框架开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考