数据库后端【免费下载链接】objection.jsAn SQL-friendly ORM for Node.js项目地址https://gitcode.com/gh_mirrors/ob/objection.js点击查看免费下载本文是 objection.jsNode.js 生态中一款 SQL 友好的 ORM官方 Getting Started 指南的深度展开版。你将学会如何初始化并绑定 Knex 实例、用最小代码跑通建表 → 插入 → 关联查询的完整链路并了解如何通过仓库内置的 minimal / koa / koa-ts 示例工程快速搭建一个可直接运行的 REST API 项目。读完本文你可以在 5 分钟内让 objection.js 在你的数据库上工作起来并理解模型定义、关系映射relationMappings与图插入insertGraph背后的源码实现。一、核心心智模型objection.js 不是另一套 ORM而是Knex 上的查询构建器在开始任何编码之前先理解 objection.js 的设计哲学这对后续所有用法都至关重要。从 lib/objection.js 的入口文件可以看到objection.js 的核心导出是Model、QueryBuilder以及一系列关系类和错误类型。它并没有试图接管数据库访问层而是把数据库访问完全交给 knex——一个广为流行的 SQL 查询构建器。这意味着你不需要学习 objection.js 专属的连接池、驱动、迁移体系这些全部沿用 Knex 的既有能力你的模型Model本质上是对某张数据库表 表间关系 校验规则的面向对象封装而查询能力则通过Model.query()返回的 QueryBuilder 暴露底层 SQL 的生成、参数的绑定、事务、连接池管理全部由 Knex 完成objection.js 在 Knex 之上叠加了模型映射、关系预加载、图插入等能力。因此objection.js 的官方文档反复强调第一步永远是初始化 Knex 实例并通过Model.knex(knex)把实例交给 objection.js。二、安装objection knex 数据库驱动2.1 依赖安装命令参照仓库的 doc/guide/installation.mdobjection.js 支持 npm 与 yarn 两种包管理器npm install objection knex yarn add objection knex除了核心依赖之外还需要根据你使用的数据库安装对应的驱动之一npm install pg # PostgreSQL npm install sqlite3 # SQLite npm install mysql # MySQL npm install mysql2 # MySQL推荐替代驱动如果你想尝鲜 alpha / beta / RC 版本可以使用next标签npm install objectionnext注意以上安装命令需要在你的项目目录内执行。本文后续所有代码示例都假定你已经完成了npm install objection knex以及目标数据库驱动。2.2 为什么必须安装 knex从源码看objection.js 的查询能力完全构建在 Knex 之上。Model.knex(knex)保存的实例会被 QueryBuilder 在真正执行 SQL 时调用查询构建器内部通过 Knex 的实例来拼接 SQL、绑定参数、执行查询。因此 knex 不是可选依赖而是不可或缺的运行依赖。三、第一步初始化 Knex 并绑定到 Model3.1 官方最小可运行样板官方 Getting Started 文档给出了一个复制即运行的完整独立示例。核心逻辑可以拆成四段1初始化 KnexSQLite 为例const { Model } require(objection); const Knex require(knex); const knex Knex({ client: sqlite3, useNullAsDefault: true, connection: { filename: example.db } });其中useNullAsDefault: true是 SQLite 驱动在插入/更新未显式指定列时的必要配置SQLite 不支持defaultTo(null)的语法Knex 官方同样要求该选项。2把 Knex 实例全局绑定给 objection.jsModel.knex(knex);这一步是整个上手的灵魂。执行之后该 Knex 实例会被全局安装到所有模型类上——包括那些尚未创建、未来才定义的新模型。也就是说你只需要在应用启动阶段调用一次之后所有SomeModel.query()都会自动使用这个 Knex 实例。3定义一个 Person 模型class Person extends Model { static get tableName() { return persons; } static get relationMappings() { return { children: { relation: Model.HasManyRelation, modelClass: Person, join: { from: persons.id, to: persons.parentId } } }; } }这里有两个必须理解的核心概念tableName模型唯一必需的静态属性指明模型映射到哪张数据库表。注意 objection.js 默认不修改列名大小写persons表需要你在数据库中真实存在。relationMappings定义模型与其他模型包括自身的关系。上面的children是一个自引用的一对多关系——Person通过persons.parentId外键关联回persons.id形成一个人有多个孩子的树形结构。join.from/join.to描述外键列与目标主键列的映射关系。4建表示例中为简化直接使用 schema builderasync function createSchema() { if (await knex.schema.hasTable(persons)) { return; } await knex.schema.createTable(persons, table { table.increments(id).primary(); table.integer(parentId).references(persons.id); table.string(firstName); }); }文档在这里特别强调正式项目中应当使用 Knex 的 migration 文件来管理表结构这里仅为演示而内联创建。仓库的 minimal 示例正是这样做的——它的迁移文件 examples/minimal/migrations/20190330121219_initial_schema.js 用标准的exports.up/exports.down结构定义persons表exports.up (knex) { return knex.schema.createTable(persons, (table) { table.increments(id).primary(); table.string(firstName); table.string(lastName); }); }; exports.down (knex) { return knex.schema.dropTableIfExists(persons); };3.2 绑定背后的源码机制Model.knex与模型绑定缓存深入了解Model.knex的行为能帮你规避多数据库场景下 90% 的坑。查看 lib/model/Model.js 中的静态方法实现static knex(...args) { if (args.length) { defineNonEnumerableProperty(this, $$knex, args[0]); } else { ... } }可以看到Model.knex(knex)实际上是在模型类上以不可枚举属性$$knex保存传入的 Knex 实例不带参数调用Model.knex()时则作为 getter 返回当前绑定的实例。而 lib/model/modelBindKnex.js 揭示了更底层的机制当Model.knex(knex)被调用时每个模型类会通过inheritModel派生出一个绑定模型类BoundModelClass并把它按模型唯一标识缓存到knex.$$objection.boundModels这个Map中同时还会把该模型的所有关系relationMappings逐一bindKnex绑定到同一个 Knex 实例上。这套缓存机制带来两个实用结论全局绑定一次即可同一个 Knex 实例重复绑定模型不会产生重复派生类性能开销可控多数据库场景需要bindKnex如果你的服务要连接多个数据库不应继续用全局Model.knex()而应使用模型实例上的Model.bindKnex(knex)为特定模型绑定专用实例——这正是官方文档中多租户 reciperecipes/multitenancy-using-multiple-databases.md所讨论的主题。四、实战插入、查询与关系预加载官方 Getting Started 示例的main()函数完整演示了 objection.js 最核心的两个能力图插入graph insert与关系预加载eager loading。async function main() { // 插入一棵人的关系树Sylvester 两个孩子 Sage、Sophia const sylvester await Person.query().insertGraph({ firstName: Sylvester, children: [ { firstName: Sage }, { firstName: Sophia } ] }); console.log(created:, sylvester); // 查询所有名叫 Sylvester 的人并按 id 排序同时把 children 关系一并加载 const sylvesters await Person.query() .where(firstName, Sylvester) .withGraphFetched(children) .orderBy(id); console.log(sylvesters:, sylvesters); }这段代码揭示了 objection.js 与普通 ORM 的关键差异insertGraph一次调用即可插入一个包含嵌套关联对象的完整对象图。insertGraph会自动处理主外键关系——先插入父记录拿到自增id再把parentId回填到子记录中插入整个过程在事务语义下完成。这正是对象关系映射的图视角你操作的是一棵对象树而不是多条离散的 INSERT 语句。withGraphFetched查询时一次性预加载关联数据避免经典的 N1 查询问题。它支持嵌套语法如children.children、过滤withGraphFetched(children(orderByAge)以及参数化关系查询细节可参考 doc/api/query-builder/eager-methods.md。链式 API.where(...)、.orderBy(...)与 Knex 的查询构建 API 风格一致因为 objection.js 的 QueryBuilder 本身就构建在 Knex 之上。示例最后用 Promise 链驱动整个流程createSchema() .then(() main()) .then(() knex.destroy()) .catch(err { console.error(err); return knex.destroy(); });注意knex.destroy()的作用是关闭连接池让 Node 进程可以正常退出这在脚本型应用中是必不可少的一步。4.1 从源码看insertGraph与关系图处理insertGraph并非黑魔法。在仓库中图插入由 lib/queryBuilder/graph/insert/GraphInsert.js 及配套的 GraphData.js负责把嵌套对象解析为节点/边结构的模型图协同完成。整个流程大致是将传入的嵌套对象解析为ModelGraph节点 边依据关系类型HasMany、BelongsToOne、ManyToMany 等确定插入顺序逐层执行 INSERT并用生成的主键回填外键列这正是自引用children能一次插入两层数据的原因对于 ManyToMany 等带through连接表的场景还会自动向连接表插入关联行见 JoinRowGraphInsertAction.js。也就是说只要你的relationMappings声明正确、表结构外键完整insertGraph就能替你完成手工 SQL 中繁琐的先插父、取 id、再插子三步曲。五、官方示例工程从最小脚本到 Koa REST API官方 Getting Started 文档强烈建议新手直接使用仓库中三个示例工程之一。它们都位于仓库的 examples 目录下。5.1 minimal最小的可运行起点这是bare minimum级别的示例对应目录 examples/minimal。运行方式git clone gitgithub.com:Vincit/objection.js.git objection cd objection/examples/minimal npm install npm start若你克隆的是本仓库镜像可直接在本仓库根目录执行cd examples/minimal npm install npm start。示例结构非常清晰examples/minimal/models/Person.js只有tableName一个必需属性的极简模型examples/minimal/knexfile.jsKnex 配置development 环境使用 SQLite并开启PRAGMA foreign_keys ON以强制外键约束production 环境则配置为 PostgreSQLexamples/minimal/migrations/20190330121219_initial_schema.jspersons 表迁移examples/minimal/app.js入口脚本演示了完整的删除旧数据 → 插入一行 → 查询全部三步曲并在主流程结束后调用knex.destroy()。其中 app.js 的写法值得照抄const Knex require(knex); const knexConfig require(./knexfile); const { Model } require(objection); const { Person } require(./models/Person); // Initialize knex. const knex Knex(knexConfig.development); // Bind all Models to the knex instance. You only // need to do this once before you use any of // your model classes. Model.knex(knex);这段代码再次印证了第三部分的结论绑定动作只需在应用入口执行一次之后所有模型自动共享该实例。5.2 koa一个完整的 REST API 服务examples/koa 是一个基于 koa 的简单服务器。它的价值不在于展示如何写 Web 服务而在于展示如何在真实 Web 服务中组织 objection.js 代码——正如其 README 所说这不是一个教你如何构建 Web 服务器的例子而是一个教你如何在 Web 服务器中使用 objection 的例子其他一切都被刻意保持最简单。运行方式git clone gitgithub.com:Vincit/objection.js.git objection cd objection/examples/koa npm install npm start node client.jsclient.js中预置了一批 HTTP 请求脚本让你开箱即可通过 REST API 体验增删改查、关系加载、图插入等能力。这个示例的看点在于它的模型组织方式examples/koa/models/Person.js 演示了完整的模型能力jsonSchemaJSON Schema 校验注意这不是数据库 schema不会自动生成表结构仅用于模型实例校验、modifiers可复用的查询片段例如searchByName用orWhereRaw(lower(??) like ?, ...)实现模糊姓名匹配、以及四种关系映射HasManyRelation 的pets/children、ManyToManyRelation 的movies、BelongsToOneRelation 的parentexamples/koa/app.js 演示了启动流程初始化 Knex →Model.knex(knex)→ 注册路由 → 启动 Koa并附带一个简易错误处理中间件将ValidationError映射为 400、ForeignKeyViolationError映射为 409、其余错误映射为 500。ManyToMany 关系的through语法是这个示例最值得学习的地方当两个表通过中间表关联时join对象需要描述三段路径movies: { relation: Model.ManyToManyRelation, modelClass: Movie, join: { from: persons.id, through: { from: persons_movies.personId, to: persons_movies.movieId, }, to: movies.id, }, },即from当前表主键→through.from中间表中指向当前表的列→through.to中间表中指向目标表的列→to目标表主键。5.3 koa-tsTypeScript 版本如果团队使用 TypeScript官方还提供了 koa 示例的 TS 版本examples/koa-ts。它与 koa 示例结构一一对应models/Person.ts、api.ts、app.ts等并配有 examples/koa-ts/tsconfig.json 与完整的类型声明。objection.js 的完整类型定义位于 typings/objection/index.d.ts涵盖了 Model、QueryBuilder、各类关系与错误类型保证你在 TS 下也能获得良好的类型提示与编译期检查。六、继续深入API 参考与配方手册Getting Started 文档的结尾把读者引向两份重要资料API 参考doc/api/query-builder/README.md 系统介绍了 QueryBuilder 的全部方法族查询、插入更新删除、关系加载、join、其他辅助方法以及 doc/api/model/README.md 中模型类的方法与静态属性配方手册Recipesdoc/recipes/README.md 汇集了各场景的最佳实践其中与入门最相关的包括recipes/raw-queries.md如何在 objection.js 中安全地使用原始 SQLraw、ref、val等构建器均由 lib/queryBuilder/RawBuilder.js 等模块导出recipes/multitenancy-using-multiple-databases.md多数据库场景下的模型绑定策略recipes/error-handling.md完整的错误处理模式与 koa 示例中的简易 handler 相对照recipes/default-values.md默认值处理。这些资源配合本指南足以支撑你从跑通示例走向在生产项目中熟练使用 objection.js。七、小结objection.js 上手的四个关键动作安装依赖npm install objection knex 数据库驱动pg / sqlite3 / mysql / mysql2初始化并绑定创建 Knex 实例后调用Model.knex(knex)一次绑定全局生效多数据库场景改用bindKnex定义模型用tableName指向真实存在的表用relationMappings声明关系用jsonSchema可选做数据校验用图思维读写insertGraph一次插入整棵对象树withGraphFetched一次加载全部关联数据配合 Knex 风格的链式查询 API 完成业务逻辑。最后把官方文档的原话作为收尾提醒To use objection.js all you need to do is initialize knex and give the created knex instance to objection.js usingModel.knex(knex)。——其余的一切都建立在这条简洁的绑定之上。赞分享数据库后端【免费下载链接】objection.jsAn SQL-friendly ORM for Node.js项目地址https://gitcode.com/gh_mirrors/ob/objection.js点击查看免费下载相关推荐SQLAlchemy ORM 完全指南从快速上手到关系映射、查询与会话管理的体系化解读SQLAlchemy ORM 完全指南从快速上手到关系映射、查询与会话管理的体系化解读 SQLAlchemy 是 Python 生态中最具代表性的数据库工具包数据库后端ORMObjection.js 关系映射五种关系类型的完整指南Objection.js 关系映射五种关系类型的完整指南 本文详细介绍了 Objection.js 中的五种核心关系类型BelongsToOneRelati数据库后端Rustlings 快速上手指南从 cargo install rustlings 到 watch 模式的完整初始化实战Rustlings 快速上手指南从 cargo install rustlings 到 watch 模式的完整初始化实战 本文以 Rustlings 官网首页教程CLI示例工程上一篇Mediator主题性能优化提升Jekyll博客加载速度的5个技巧下一篇Tyk Gateway WebAssembly插件使用Rust开发高性能扩展创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考