从 @loopback/example-todo 变更日志看 LoopBack 4 核心技术实践

原创2026-10-14 17:45:381,964 阅读
文章标签:后端微服务

从 @loopback/example-todo 变更日志看 LoopBack 4 核心技术实践

导读

本文以 loopback-next 仓库中 examples/todo/CHANGELOG.md 这一版本演进记录为脉络,系统梳理 @loopback/example-todo(LoopBack 4 官方入门教程示例,即 todo 应用)从 2018 年至今的每一次实质性技术变革。读者将借此掌握 LoopBack 4 中 OpenAPI 查询参数编码规范、Node.js 运行时支持策略、中间件式请求处理链、数据源配置方式、数据库迁移与 OpenAPI 导出等关键实践,并能在真实源码中逐一找到对应实现。

一、示例项目与变更日志概览

@loopback/example-todo 是 LoopBack 4 的基础教程应用,目标是用 5 个核心步骤(创建应用脚手架、定义 Todo 模型、添加数据源、添加 Repository、添加 Controller)构建一个完整的待办事项 REST API。项目的完整说明见 examples/todo/README.md,其 package.json(examples/todo/package.json)目前版本为 9.0.16,主要依赖 @loopback/boot、@loopback/core、@loopback/repository、@loopback/rest、@loopback/rest-explorer、@loopback/service-proxy 以及 loopback-connector-rest、morgan、tslib 等。

该变更日志按时间倒序记录了近 40 个版本的演进,其中大量条目为 "Version bump only"(版本号同步升级),但也不乏若干值得深入研读的技术性变更:2.0.0 对 JSON 查询参数 OpenAPI 描述的彻底重构、多轮 Node.js 运行时支持范围调整、请求处理架构向中间件式 Sequence 迁移、数据源配置从 JSON 迁移到 TypeScript 文件、openapi-spec 导出脚本的引入等。这些条目共同勾勒出 LoopBack 4 在 REST 框架、类型系统与工程化三个维度的成熟路径。

二、核心变革一:2.0.0 中 JSON 查询参数的 OpenAPI 编码方式重构

2.1 变更背景

在 2.0.0(2020-02-06)之前,LoopBack 的 @param.query.object 装饰器生成的 OpenAPI 参数描述采用 exploded + deep-object 风格:

{
  "in": "query",
  "style": "deepObject",
  "explode": "true",
  "schema": {}
}

这种 exploded 编码对简单 JSON 对象可以正常工作,例如:

http://localhost:3000/todos?filter[limit]=2

但对于复杂对象(如带嵌套 include 关系的 filter)会产生问题,这在 swagger-js 与 OpenAPI 规范社区的相关讨论中已被反复验证。

2.2 变更内容与新版描述

2.0.0 将 JSON 查询参数的定义从 exploded / deep-object 风格切换为 OpenAPI 规范的 url-encoded 风格:移除 style 与 explode 字段,将 schema 移入 content['application/json'] 之下:

{
  "in": "query",
  "content": {
    "application/json": {
      "schema": {}
    }
  }
}

这一描述方式允许客户端(如 swagger-ui 与 LoopBack 的 API Explorer)以 URL 编码的 JSON 载荷发送复杂查询。例如在 todo-list 示例中,用 {"include":[{"relation":"todoList"}]} 关联查询 todo 时,可使用如下 url-encoded 查询参数:

http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D

2.3 源码级佐证

在 packages/openapi-v3/src/decorators/parameter.decorator.ts 中,param.query.object 的当前实现正是采用 content<a href="https://link.gitcode.com/i/d9fa1b34135484f157a5970e64b7addd" target="_blank">'application/json'] 结构:装饰器将 schema 强制为 type: 'object' 并放入 content['application/json'].schema,不再生成 style / explode 字段。param.filter 与 param.where 两个快捷装饰器也基于 param.query.object 实现,分别注入模型过滤与条件 schema(见 [filter-schema.ts)。

对应的单元测试 packages/openapi-v3/src/__tests__/unit/decorators/param/param-query.decorator.unit.ts 明确断言 @param.query.object 会生成 in: query 与 content<a href="https://link.gitcode.com/i/45be526ff070e4a6972847f6d6337416" target="_blank">"application/json"] 的参数定义,验证了这一行为。而 @loopback/rest 中的请求解析层(见 [packages/rest/src/body-parsers/body-parser.urlencoded.ts 与 packages/rest/src/__tests__/acceptance/coercion/coercion.acceptance.ts)为 JSON 查询参数同时支持 URL 编码载荷与 exploded 查询。

2.4 兼容性与升级影响

该变更只修改 LoopBack 生成的 OpenAPI 定义,运行时行为不变:

  • 为兼容既有 REST API 客户端,?filter[limit]=1 这类 exploded 查询继续有效,尽管其 OpenAPI 描述已经不同;
  • @param.query.object 装饰器签名未变,应用侧无需修改代码,方法签名与数据结构均不受影响;
  • API 消费者若其客户端库依赖 OpenAPI 描述来发送 url-encoded 载荷,可能需要重新生成 API 定义(如重新运行 openapi-spec 导出)。

三、核心变革二:Node.js 运行时支持的生命周期演进

变更日志完整记录了 example-todo 对 Node.js 版本支持范围的收紧过程,这是跟随上游 LTS 生命周期标准操作:

版本 时间 变更
1.0.1-alpha.6 2018-02 放弃低于 Node.js 8.0 的支持,要求 8.x LTS
3.0.0 2020-03 移除 Node.js v8.x 支持
5.0.0 2021-11 放弃 Node.js v10,支持 v17,升级 TypeScript 4.5.2
6.0.0 2022-05 移除 Node.js v12 支持,新增 v18 支持
7.0.0 2023-05 移除 Node.js v14 / v19 支持,新增 v20 支持
8.0.0 2024-03 放弃 Node.js 16 支持(BREAKING CHANGES)
9.0.0 2025-06 放弃 Node.js 18 支持(BREAKING CHANGES)

当前 examples/todo/package.json 的 engines 字段声明为 "node": "22 || 24 || 26",即项目现状只支持这三个活跃 LTS 主线版本。这类变更统一以 "chore" 类型提交并标注 BREAKING CHANGES,说明运行时版本约束属于用户升级时必须评估的重大事项。

四、核心变革三:请求处理架构向中间件式 Sequence 演进

4.1 演进路径

LoopBack 4 早期使用基于责任链的自定义 Sequence(DefaultSequence)按固定顺序执行请求处理步骤。3.7.0(2020-08-05)起,示例项目切换到基于中间件的 Sequence(middleware based sequence),提交 "switch to middleware based sequence for examples" 明确指向 example-todo 的对应改造;3.6.0 也提到更新 sequence.ts 以调用中间件。这一演进使请求处理更贴近 Express 生态,中间件可按需注册与组合。

4.2 当前实现

examples/todo/src/sequence.ts 的完整实现只有两行:自定义 MySequence 直接继承 @loopback/rest 导出的 MiddlewareSequence。在 examples/todo/src/application.ts 中通过 this.sequence(MySequence) 注册。这意味着示例已完全采用新的中间件式请求处理链,用户可在 MiddlewareSequence 基础上按需覆写 handle 方法定制处理逻辑(见 REST-middleware-sequence.md)。

4.3 配套能力:morgan 日志中间件与静态首页

3.3.0 引入"当环境变量 DEBUG 被设置时添加 morgan 中间件"的功能,examples/todo/src/application.ts 中的 setupLogging() 方法将其落地:通过 this.expressMiddleware(morganFactory, defaultConfig, {injectConfiguration: 'watch', key: 'middleware.morgan'}) 注册 morgan('combined'),并把日志流重定向到 debug 输出。应用启动时 this.static('/', path.join(__dirname, '../public')) 提供默认首页,对应变更日志 1.1.0 "use app.static for default home page" 的功能。

五、核心变革四:数据源配置与工程化实践

5.1 数据源配置从 JSON 迁移到 TypeScript

3.2.0(2020-04-29)将数据源配置从 JSON 文件迁移为 TS 文件。当前实现可见:

  • examples/todo/src/datasources/db.datasource.ts:内存连接器(connector: 'memory'),数据落盘到 ./data/db.json,类上标注 @lifeCycleObserver('datasource') 以在应用停止时优雅断开连接;
  • examples/todo/src/datasources/geocoder.datasource.ts:REST 连接器(loopback-connector-rest),通过 operations 模板调用美国人口普查局 geocoding 服务,geocode(address) 函数从 $.result.addressMatches[*].coordinates 提取经纬度,超时配置为 15000ms。

两个数据源类均通过 @inject('datasources.config.xxx', {optional: true}) 注入可覆盖配置,并暴露 static dataSourceName 供 Boot 机制按约定自动装载。历史条目还记录了 0.22.0 使用 resolveJsonModule 加载数据源 JSON、1.9.0 为数据源配置引入 .config.json 扩展名等细节,最终演进为今天的 TS 内联配置形态。

5.2 数据库迁移脚本与 OpenAPI 导出

  • 1.3.0 引入 migrateSchema API 并为新应用脚手架化数据库迁移脚本。落地于 examples/todo/src/migrate.ts:npm run migrate 先执行 app.boot() 再调用 app.migrateSchema({existingSchema}),其中 --rebuild 参数会将策略切换为 drop(重建),否则为 alter(变更),最后显式 process.exit(0) 避免连接池导致进程悬挂。脚本入口在 examples/todo/package.json 的 premigrate/migrate 中定义。
  • 3.5.0 新增 npm run openapi-spec 导出 OpenAPI 规范,落地于 examples/todo/src/openapi-spec.ts:启动应用、执行 app.boot() 后调用 app.exportOpenApiSpec(outFile) 把规范写入文件(默认端口 3000、主机 localhost,可用 PORT / HOST 环境变量覆盖)。

六、核心变革五:模型、Repository 与控制器 API 演进

6.1 模型定义

examples/todo/src/models/todo.model.ts 定义了 Todo 实体:id(number,generated: false)、必填的 title、可选的 desc、isComplete、remindAtAddress、remindAtGeo 与 tag(type: 'any')。tag 字段对应 3.1.0 "support any type" 的能力;remindAtGeo 注释中的 "Use LoopBack's GeoPoint type here" 呼应了 0.12.0 "add Geo to examples/todo" 与后续 8.1.0、7.1.4 中按人口普查局数据更新测试经纬度的修复记录。

6.2 控制器与 OpenAPI 描述工具的演进

examples/todo/src/controllers/todo.controller.ts 是 REST API 的核心:

  • @post('/todos') 的请求体使用 getModelSchemaRef(Todo, {title: 'NewTodo', exclude: ['id']}),对应 1.6.6 "exclude id from POST request body" 与 1.7.0 "use getModelSchemaRef" 两条记录;1.8.0 又为其补充了描述性标题 NewTodo;
  • @patch('/todos/{id}') 与 @patch('/todos') 使用 getModelSchemaRef(Todo, {partial: true}),对应 1.6.5 "allow partial updates via PATCH" 的修复;
  • find 方法使用 @param.filter(Todo)、count 与 updateAll 使用 @param.where(Todo),对应 3.0.0 "use @param.filter and @param.where decorators" 的迁移;
  • create 方法在提供 remindAtAddress 时调用 Geocoder 服务,若地址解析失败抛出 HttpErrors.BadRequest,对应 3.0.0 "throw if geocode address is not found" 的修复;
  • findById 方法使用 @param.filter(Todo, {exclude: 'where'}) 生成 FilterExcludingWhere 类型,反映 Repository 层 *ById 方法对不存在 id 抛错的行为(0.18.0 "rework *ById methods to throw if id not found")。

6.3 Repository 与返回码规范

0.18.0 同时记录 REST 层"模型未找到时返回 404",这由 findById 等 *ById 方法在 id 不存在时抛出的错误经错误处理映射为 HTTP 404 实现。此外 0.17.3 "add responses to controllers"、1.6.0 "add navigational properties to find* methods" 与 0.20.0 "add filter parameter to find endpoints" 共同塑造了今天控制器中完整的 responses 声明与 filter 查询能力。

七、工程链与依赖治理演进

  • 类型系统:5.0.0 升级 TypeScript 4.5.2,3.10.0 升级 4.2.x,3.4.0 升级 3.9.x;3.0.0 将 tslib 加入运行时依赖以减少编译产物体积(closes #4676)。当前项目使用 TypeScript ~5.2.2。
  • 代码规范:1.6.0 "replace tslint with eslint"、1.6.2 "remove forgotten references to tslint",当前 lint 脚本由 prettier:check 与 eslint 组成,使用 @loopback/eslint-config。
  • 构建发布:0.9.0 引入 dist-util 辅助包;0.8.0 与 1.0.1-alpha.6 分别涉及 dist8 输出与旧 dist6 目标的移除;0.15.0 起 CLI 为克隆的示例自动安装依赖,1.9.6 更新 clean 脚本兼容 lb4 example。
  • 验证与测试:0.19.0 的 testlab 新增 createRestAppClient() 并让 givenHttpServerConfig 使用端口 0(随机端口);0.21.0 增加 StubbedInstanceWithSinonAccessor;1.2.0 引入自托管 REST API Explorer(对应 packages/rest-explorer 包)。

这些条目表明:即使是一个教程示例,LoopBack 4 也将其纳入了与全部核心包一致的 monorepo 工程治理(lint、prettier、语义化版本与 Conventional Commits 约定)。

八、如何在仓库中查看并运行该示例

若需体验此示例的最终形态,可参照 examples/todo/README.md 的指引:

  1. 通过 LoopBack CLI 克隆示例:lb4 example todo(或直接查看本仓库 examples/todo 目录);
  2. 安装依赖并启动:npm install && npm start,服务默认运行于 http://127.0.0.1:3000,npm run migrate 可执行数据库迁移(支持 --rebuild),npm run openapi-spec 可导出 OpenAPI 规范;
  3. 相关测试位于 examples/todo/src/__tests__,包括 todo.acceptance.ts(REST 端点验收测试)、home-page.acceptance.ts、todo.controller.unit.ts 与 geocoder.service.integration.ts,可执行 npm test 验证。

结语

通过通读 examples/todo/CHANGELOG.md 并结合仓库源码,可以清晰看到 @loopback/example-todo 十余年的演进主线:查询参数从 exploded deep-object 走向标准化的 url-encoded JSON 描述、运行时支持随 Node.js LTS 节奏稳步收缩、请求处理全面迁移到中间件式 Sequence、数据源配置走向类型安全的 TS 内联形态,以及围绕 OpenAPI 导出、数据库迁移、lint 与测试的工程化沉淀。这份变更日志不仅是示例自身的成长史,更是理解 LoopBack 4 核心设计决策与升级路径的实用索引——读者在排查升级问题时,可按版本号在这些条目中找到对应的行为变化与源码落点。

登录后查看全文
loopback-next