- 数据库
- 后端
【免费下载链接】objection.js
An SQL-friendly ORM for Node.js
本文是 objection.js（Node.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.md，objection.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 objection@next注意：以上安装命令需要在你的项目目录内执行。本文后续所有代码示例，都假定你已经完成了
npm install objection knex（以及目标数据库驱动）。
2.2 为什么必须安装 knex？
从源码看，objection.js 的查询能力完全构建在 Knex 之上。Model.knex(knex)保存的实例会被 QueryBuilder 在真正执行 SQL 时调用；查询构建器内部通过 Knex 的实例来拼接 SQL、绑定参数、执行查询。因此 knex 不是可选依赖，而是不可或缺的运行依赖。
三、第一步：初始化 Knex 并绑定到 Model
3.1 官方"最小可运行"样板
官方 Getting Started 文档给出了一个"复制即运行"的完整独立示例。核心逻辑可以拆成四段：
（1）初始化 Knex（SQLite 为例）：
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.js：
Model.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 builder）：
async 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)为特定模型绑定专用实例——这正是官方文档中多租户 recipe（recipes/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：查询时一次性预加载关联数据，避免经典的 N+1 查询问题。它支持嵌套语法（如'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 git@github.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.js：Knex 配置，development 环境使用 SQLite，并开启
PRAGMA foreign_keys = ON以强制外键约束；production 环境则配置为 PostgreSQL； - examples/minimal/migrations/20190330121219_initial_schema.js：persons 表迁移；
- 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 git@github.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 演示了完整的模型能力：
jsonSchema（JSON Schema 校验，注意这不是数据库 schema，不会自动生成表结构，仅用于模型实例校验）、modifiers（可复用的查询片段，例如searchByName用orWhereRaw('lower(??) like ?', ...)实现模糊姓名匹配）、以及四种关系映射（HasManyRelation 的pets/children、ManyToManyRelation 的movies、BelongsToOneRelation 的parent）； - examples/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-ts：TypeScript 版本
如果团队使用 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 中模型类的方法与静态属性；
- 配方手册（Recipes）：doc/recipes/README.md 汇集了各场景的最佳实践，其中与入门最相关的包括：
- recipes/raw-queries.md：如何在 objection.js 中安全地使用原始 SQL（
raw、ref、val等构建器，均由 lib/queryBuilder/RawBuilder.js 等模块导出）； - recipes/multitenancy-using-multiple-databases.md：多数据库场景下的模型绑定策略；
- recipes/error-handling.md：完整的错误处理模式，与 koa 示例中的简易 handler 相对照；
- recipes/default-values.md：默认值处理。
- recipes/raw-queries.md：如何在 objection.js 中安全地使用原始 SQL（
这些资源配合本指南，足以支撑你从"跑通示例"走向"在生产项目中熟练使用 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.js
An SQL-friendly ORM for Node.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示例工程
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
