LoopBack 4 `@loopback/repository` 包演进全解:从数据访问层到关系模型的版本变迁与迁移指南

原创2026-10-15 10:26:201,335 阅读
文章标签:后端微服务

LoopBack 4 @loopback/repository 包演进全解:从数据访问层到关系模型的版本变迁与迁移指南

导读

本文以 @loopback/repository 包(当前版本 8.0.15)的 CHANGELOG.md 为骨架,系统梳理该数据访问层核心包自 2017 年以来的版本演进主线,涵盖 Repository 接口体系、关系模型(hasMany / hasOne / belongsTo / hasManyThrough / referencesMany / polymorphic)、Filter 查询、事务与迁移等关键能力的引入时间点与破坏性变更细节,并辅以 packages/repository/src 下的源码证据。读完本文,你将能读懂该包的版本号含义、掌握跨版本升级时需要注意的迁移要点,并了解其底层架构是如何一步步演变成今天的样子。

一、@loopback/repository 是什么:定位与包结构

@loopback/repository 是 LoopBack 4 官方 monorepo(lerna.json 管理)中负责"与数据库交互"的核心包。其官方描述为 "Define and implement a common set of interfaces for interacting with databases"(定义并实现一组与数据库交互的通用接口),见 packages/repository/package.json。

从源码目录结构(packages/repository/src)可以直观看出它的职责边界:

  • repositories/:Repository、CrudRepository、DefaultCrudRepository、LegacyJugglerBridge、KVRepository 等核心抽象与实现;
  • relations/:全部关系类型的定义与解析器(belongs-to、has-many、has-one、references-many 及 has-many-through);
  • decorators/:@model、@property、@repository、@hasMany 等装饰器;
  • connectors/:CrudConnector、KVConnector 等连接器接口;
  • errors/:EntityNotFoundError、InvalidRelationError 等框架级错误类型;
  • mixins/:RepositoryMixin,将 repository/datasource/model 能力挂载到 Application 上。

版本演进上,该包经历了 4.0.0-alpha.x → 0.x → 1.x → ... → 8.x 的阶段,其中 8.0.0 之前的每一次主版本号提升,几乎都伴随着 Node.js 最低版本要求的提升或接口的破坏性调整,这正是本文要展开的核心。

二、核心架构演进时间线(2017 — 2026)

将 CHANGELOG.md 中的关键条目按时间倒序梳理,可以得到一条清晰的演进主线:

2.1 萌芽期(4.0.0-alpha.11 ~ 0.9.0,2017-10 ~ 2018-05)

这个阶段是 LoopBack 4 早期实验期,changelog 记录了一系列奠基性能力:

  • 4.0.0-alpha.19:引入 builders and execute()、metadata inspector、装饰器工厂(decorator factories);
  • 4.0.0-alpha.20:@property 参数变为可选、新增数组装饰器(array decorator);
  • 4.0.0-alpha.21:提供获取 Model metadata 的 helper 函数;
  • 4.0.0-alpha.24:在 legacy juggler bridge 中新增 findOne;
  • 4.0.0-alpha.27:repository-json-schema 增加顶层 metadata 支持;
  • 0.1.2:新增 repository booter 与 datasource() 方法(#1030);
  • 0.4.0:一处影响深远的 BREAKING CHANGE——"instances of user-defined classes are not cloned any more",根因是 DataSource 实例被错误克隆(issue #1182);
  • 0.8.0 ~ 0.9.0:引入 getRepository 到 mixin,@repository 装饰器开始接受构造函数作为参数,并新增 dist-util helper 包。

2.2 CRUD 与关系模型的成型(0.10.0 ~ 1.5.0,2018-05 ~ 2019-04)

这个阶段 repository 包真正"长出了骨架":

  • 0.10.0:修复"同一 repository 类的多个实例"问题;
  • 0.11.0:initial hasMany relation impl(hasMany 关系首次落地);
  • 0.12.0:新增 crud relation methods;
  • 0.13.0:make models strict by default(模型默认进入 strict 模式),引入 hasMany 关系装饰器推断;
  • 0.13.3:RelationType 从数字枚举改为字符串枚举;
  • 0.14.0:重构 HasManyRepositoryFactory 泛型参数顺序(见下文迁移小节);
  • 0.15.0:新增 KVRepository 实现(基于 legacy juggler);
  • 0.17.0:引入 EntityNotFoundError,并重构 *ById 系列方法:id 不存在时直接抛出异常;
  • 0.19.0:count 与 updateAll 改为返回对象;
  • 0.21.0:实现 belongsTo 关系;
  • 1.1.0:新增 hasOne 关系、belongsToUniquely 语法糖、migrateSchema API;
  • 1.3.0:新增 execute 实现(#2165);
  • 1.4.0 / 1.5.0:repository-json-schema 支持自定义 jsonSchema、更多 TypeScript strict 检查。

2.3 Inclusion 与导航属性(1.6.0 ~ 1.19.0,2019-06 ~ 2020-02)

  • 1.6.0:为 find* 方法增加导航属性(navigational properties),并用 eslint 全面替换 tslint;
  • 1.7.0:repository-json-schema 的 getJsonSchema 增强,可描述导航属性(#2630);
  • 1.8.0:在 JSON 输出中包含导航属性;
  • 1.12.0:新增 InclusionResolver 类型与 includeRelatedModels helper;
  • 1.13.0:DefaultCrudRepository 新增 inclusionResolvers;
  • 1.14.0:在已解析的关系元数据中增加 keyFrom;
  • 1.15.0:为 belongsTo、hasOne、hasMany 分别实现 inclusionResolver;
  • 1.16.0:新增 defineModelClass helper;rejects create/update 操作中出现的导航属性;inclusion 支持自定义 scope;
  • 1.17.0:belongsTo 访问器在外键未包含时返回 undefined;支持 hasMany/hasOne 自定义 keyFrom;hasManyThrough 接口雏形出现;
  • 1.18.0 ~ 1.19.0:hasManyThrough 接口进一步完善、事务利用 isactive 状态判断。

2.4 2.x:operation hooks、目标数量标记与 Inclusion 泛型移除(2020-03 ~ 2020-09)

2.0.0 是一次"小而关键"的破坏性主版本,changelog 明确给出三条迁移指引:

  1. 自定义关系定义接口必须包含 targetsMany 属性,用于标识关系目标是多个实例还是单个实例:
interface HasManyDefinition extends RelationDefinitionBase {
  type: RelationType.hasMany;
  targetsMany: true;   // 一对多:true
  // etc.
}

export interface BelongsToDefinition extends RelationDefinitionBase {
  type: RelationType.belongsTo;
  targetsMany: false;  // 单目标:false
  // etc.
}

创建关系定义实例时也必须显式传入该值:

new ModelDefinition('Order').addRelation({
  name: 'customer',
  type: RelationType.belongsTo,
  targetsMany: false,
  source: Order,
  target: () => Customer,
  keyFrom: 'customerId',
  keyTo: 'id',
});

这一设计在今天的源码中仍然保留:RelationDefinitionBase 接口强制要求 targetsMany: boolean,其 JSDoc 注释明确说明"OpenAPI/JSON Schema 生成器需要该属性"(见 relation.types.ts)。

  1. Inclusion 类型不再是泛型,升级时删除所有泛型参数:
- Inclusion<MyModel>
+ Inclusion
  1. 该版本同时移除 Node.js v8.x 支持,要求升级到 Node 10+。

此外 2.0.0 还引入了 operation hooks 支持、约束 findById 的 filter 排除 where、toJSON 跳过 undefined 属性值、保留自动生成 id 属性的自定义类型、新增 tslib 依赖等。

2.x 后续版本继续补充:2.1.0 移除对 DefaultKeyValueRepository 仅限 Entity 的限制;2.3.0 为 OpenAPI schema 填充 x-typescript-type;2.4.0 修复 updateById 在 id 为 undefined 时退化为 updateAll 的行为,并引入 null 类型、repository 类的通用工厂、toObject 保留原型等;2.5.0 为 RepositoryMixin 新增 model() 方法,定义 repository 绑定命名空间与标签常量(见 keys.ts),并抽取 rejectNavigationalPropertiesInData helper。

2.5 3.x:hasManyThrough 成熟、filter 独立成包(2020-09 ~ 2021-11)

  • 3.0.0:filter 相关类型重构为独立包(@loopback/filter,#5957);组件不再自带安装核心框架包,而改由目标应用提供——若升级后 npm install 报错,需要检查项目是否显式列出扩展所需依赖;同时为配置补充类型以支持自动补全。
  • 3.1.0:实现 hasManyThrough resolver;
  • 3.3.0:引入更简洁的 inclusion 语法;
  • 3.4.0:新增连接器接口枚举、统一 relations 的 debug scope;
  • 3.5.0:将 Entity 和 Model 标记为普通类(regular classes);
  • 3.6.0 / 3.7.0:支持 Node 16;为 RepositoryMixin 增加 allowMigration: false 选项,hasManyThrough 支持 unlinkAll。

2.6 4.x 与 5.x:ReferencesMany 与多态关系(2021-11 ~ 2023-05)

  • 4.0.0:移除 Node.js v10 支持,支持 Node 17,升级 TypeScript 4.5.2;
  • 5.0.0:这是一次功能大版本——移除 Node v12 支持、新增 Node v18 支持,同时一次性引入两个重量级关系能力:多态关系(polymorphic relations,#2487) 与 ReferencesMany 关系;
  • 5.1.0:新增**单条查询批量插入多行(insert multiple rows in single query)**能力(#3357),并修复 legacy-juggler-bridge 中 entityToData 的 async 处理(#9071)。

2.7 6.x ~ 8.x:Node 版本跟随与稳定性维护(2023-05 ~ 2026-08)

  • 6.0.0:支持 Node v20,移除 Node v14 / v19 支持;
  • 6.1.0:恢复 entityToData 方法的 async 特性(修复 5.1.0 引入的回退问题),更新 @types/node;
  • 7.0.0:移除 Node.js 16 支持;
  • 8.0.0:移除 Node.js 18 支持;当前版本要求见 package.json 的 engines 字段——node: "22 || 24 || 26";
  • 8.0.1 ~ 8.0.15:除版本号跟随 monorepo 整体发布外,主要是维护性修复(更新 @loopback/core 至最新主版本)。

三、关系模型:从 hasMany 到 ReferencesMany / 多态

关系系统是 @loopback/repository 演进最密集的领域。当前 RelationType 枚举(relation.types.ts)包含:

export enum RelationType {
  belongsTo = 'belongsTo',
  hasOne = 'hasOne',
  hasMany = 'hasMany',
  embedsOne = 'embedsOne',
  embedsMany = 'embedsMany',
  referencesOne = 'referencesOne',
  referencesMany = 'referencesMany',
}

changelog 中关系能力的落地顺序可以归纳为:

版本 关系能力
0.11.0 hasMany 初始实现
0.21.0 belongsTo
1.1.0 hasOne、belongsToUniquely
1.15.0 belongsTo / hasOne / hasMany 的 inclusionResolver
1.17.0 ~ 1.19.0 hasManyThrough 接口与访问器
2.7.0 ~ 2.11.0 hasManyThrough 工厂、link/unlink、非 SQL execute() 变体
5.0.0 referencesMany、多态关系

源码层面,关系实现散落在 relations 目录下,每种关系都遵循"decorator + helpers + repository/factory + inclusion-resolver"四件套模式。以 has-many-through 为例,其帮助文件(has-many-through.helpers.ts)、工厂(has-many-through.repository-factory.ts)与 inclusion resolver(has-many-through.inclusion-resolver.ts)共同工作。单元测试(如 has-many-through-repository-factory.unit.ts)对这些行为有完整覆盖。

3.1 通过 hasManyThrough 的批量能力:createAll

5.1.0 引入的"单条查询批量插入多行"能力在接口与实现层面均有直接对应。CrudRepository 接口定义了批量方法(repository.ts):

create(dataObject: DataObject<T>, options?: Options): Promise<T>;
createAll(dataObjects: DataObject<T>[], options?: Options): Promise<T[]>;

DefaultCrudRepository 将其委托给连接器的 createAll(repository.ts),而 legacy juggler bridge 则调用 model 类的 createAll(legacy-juggler-bridge.ts)。这意味着支持批量插入的数据库连接器可以在单次查询中完成多行写入,显著提升批量场景的写入效率。

四、RepositoryMixin:把数据访问挂载到应用

RepositoryMixin(repository.mixin.ts)是应用与 repository 包之间的"接线层"。changelog 中与其相关的里程碑包括:

  • 0.1.2:datasource() 方法;
  • 0.5.0 / 0.6.0:getRepository;
  • 0.13.0:模型默认 strict;
  • 1.1.0:migrateSchema API;
  • 2.5.0:model() 方法;
  • 2.6.0:允许组件(component)贡献模型用于依赖注入(对应源码中的 mountComponentModels,见 repository.mixin.ts);
  • 3.7.0:allowMigration: false 选项。

migrateSchema 在源码注释中有明确的数据安全警告:默认情况下它会尝试在更新 schema 时保留数据,但这一点并不保证在所有连接器上都安全,升级前务必查阅对应连接器对 automigrate 行为的说明(repository.mixin.ts)。

五、版本迁移指南:changelog 中的实操要点汇总

综合全文 changelog,跨版本升级时最值得关注的破坏性变更如下:

  1. Node.js 版本要求(engines):每一代主版本都会抬高最低 Node 要求——8.x 要求 22 || 24 || 26(当前)。升级主版本前先确认运行环境。
  2. targetsMany 必填(2.0.0):自定义关系定义接口与实例必须显式提供 targetsMany。
  3. Inclusion 泛型移除(2.0.0):Inclusion<MyModel> 改为 Inclusion。
  4. 组件依赖框架包(3.0.0):升级后若 npm install 失败,需在目标应用中显式声明扩展所需依赖。
  5. HasManyRepositoryFactory 泛型顺序(0.14.0):泛型从 <SourceID, Target> 调整为 <Target, ForeignKeyType>:
- public orders: HasManyRepository<typeof Customer.prototype.id, Order>
+ public orders: HasManyRepository<Order, typeof Customer.prototype.id>

对应的工厂函数同样调整:

- const orderFactoryFn = createHasManyRepositoryFactory<
-   typeof Customer.prototype.id, Order, typeof Order.prototype.id>(...);
+ const orderFactoryFn = createHasManyRepositoryFactory<
+   Order, typeof Order.prototype.id, typeof Customer.prototype.id>(...);
  1. findById 语义(4.0.0-alpha.14 / 0.17.0):从"无结果时 reject"到全面落地 EntityNotFoundError(实现见 entity-not-found.error.ts),*ById 方法在 id 不存在时统一抛错而非返回 null。
  2. 模型 strict 默认开启(0.13.0):未声明的属性默认会被拒绝。

六、测试与验证:如何亲自观察这些演进

repository 包的测试非常完备,是验证本文所述演进事实的最佳途径。测试目录按 acceptance / integration / unit 分层组织(见 packages/repository/src/tests):

  • 关系工厂单元测试:belongs-to-repository-factory.unit.ts、has-many-repository-factory.unit.ts、has-one-repository-factory.unit.ts、has-many-through-repository-factory.unit.ts;
  • 元数据解析测试:resolve-belongs-to-metadata.unit.ts、resolve-has-many-metadata.unit.ts、resolve-has-many-through-metadata.unit.ts、resolve-has-one-metadata.unit.ts;
  • 桥接层测试:legacy-juggler-bridge.unit.ts、kv.repository.bridge.unit.ts;
  • acceptance 测试:operation-hooks.acceptance.ts、repository.acceptance.ts 等。

在仓库根目录下,你可以通过以下命令运行这些测试(先执行包构建):

cd packages/repository
npm install   # 首次运行前安装依赖(如需)
npm run build # pretest 也会自动触发构建
npm test

结语

从 2017 年的 4.0.0-alpha.11 到今天 8.0.15,@loopback/repository 的 changelog 本身就是一部"关系型数据访问框架如何一步步走向成熟"的编年史:接口从 findById 的抛错语义、模型的 strict 默认值,到 targetsMany 的强制化、Inclusion 泛型的移除,再到 hasManyThrough、referencesMany 与多态关系的落地;运行时要求则始终跟随 Node.js 的 LTS 节奏。理解这些演进,不仅能帮你安全地完成跨版本升级,也能让你更清楚今天 @loopback/repository 中每一个设计决策背后的来龙去脉。如需深入某一版本细节,可直接查阅 CHANGELOG.md 原文与 packages/repository/src 源码。

登录后查看全文
loopback-next