LoopBack 4 Model API Builder 扩展点:用 Model 类自动生成 Repository 与 Controller 的插件契约
LoopBack 4 Model API Builder 扩展点:用 Model 类自动生成 Repository 与 Controller 的插件契约
@loopback/model-api-builder 是 LoopBack 4(loopback-next 仓库)中定义"模型 API 构建器"扩展点契约的基础包:它只提供类型与辅助工具,本身不含业务实现。读完本文,你将掌握 ModelApiBuilder 接口、ModelApiConfig 配置结构与 asModelApiBuilder 绑定模板的完整用法,能够基于此契约编写自己的 API 构建扩展(例如仿照 @loopback/rest-crud 实现"输入一个 Model 类、自动产出 Repository 与 Controller"的能力),并理解它与 ModelApiBooter 在应用启动阶段是如何协作的。
一、Overview:这个包解决什么问题
在常规的 LoopBack 4 开发中,为一个模型对外提供 REST API,你需要手写两样东西:Repository 类(负责数据访问)和 Controller 类(负责 HTTP 路由)。当模型数量很多时,这些类高度重复。
@loopback/model-api-builder 定义的思路是:用户只提供 Model 类 + 一段配置,扩展方负责"按模型构建出 Repository 和 Controller"。仓库中的 packages/model-api-builder/src/index.ts 包文档把契约概括为:
Provides a contract for extensions that contribute builders for repositories and controllers. Users provide both the model class and an extension. The extension is then used to build their repository and controller based on the model class.
也就是说,这个包扮演的是"插件插槽"(extension point)角色,真正的构建逻辑由其他包(最典型的是 @loopback/rest-crud)以扩展(extension)的身份贡献。它定义了三个关键导出:
ModelApiBuilder:扩展必须实现的接口;ModelApiConfig:描述单个模型配置文件的类型;asModelApiBuilder:把实现类注册到扩展点的绑定模板(binding template)。
三者均定义在 packages/model-api-builder/src 下:model-api-builder.ts、model-api-config.ts,并由 index.ts 统一导出。
二、安装
作为运行依赖安装到你的包中:
npm install --save @loopback/model-api-builder
需要说明的依赖关系(见 packages/model-api-builder/package.json):该包以 peerDependencies 声明了 @loopback/core(^7.0.0,提供 injectable、extensionFor 等扩展点基础设施)与 @loopback/repository(^8.0.1,提供 ApplicationWithRepositories 与 Model 类型),因此请确保宿主应用已安装这两个包。仓库中该包版本为 7.0.16,engines.node 声明支持 Node.js 22 / 24 / 26。
三、核心契约一:ModelApiConfig 配置类型
配置类型定义于 packages/model-api-builder/src/model-api-config.ts,它描述的是 public-models/{model-name}.config.json(在 boot 约定下实际是 model-endpoints/*.config.{js,ts})这类单模型配置文件的完整结构:
export type ModelApiConfig = {
/**
* The model class that the repository and controller are to be built from.
* e.g. Product (a Model class)
*/
model: typeof Model & {prototype: Model};
/**
* Name of data-access pattern describing the API builder. Users can
* customize and use a unique pattern name.
* e.g. 'RestCrud'
*/
pattern: string;
/**
* The dataSource the model uses under the hood.
* e.g. 'db'
*/
dataSource: string;
[patternSpecificSetting: string]: unknown;
};
三个必填字段的含义:
| 字段 | 类型 | 说明 | 示例值 |
|---|---|---|---|
model |
typeof Model & {prototype: Model} |
要据此构建 Repository 和 Controller 的模型类本身(不是字符串,是类引用) | Product |
pattern |
string |
数据访问模式的名称,用于让启动器挑选对应的 API 构建器;你可以自定义唯一名称 | 'CrudRest'、'stub' |
dataSource |
string |
模型底层使用的数据源绑定名 | 'db' |
最后一个索引签名 <a href="https://link.gitcode.com/i/091e4d2e1aa05a5c605a4acfd600c228" target="_blank">patternSpecificSetting: string]: unknown 是该契约的灵活性所在:它允许每个具体 pattern 在配置文件中携带自己的专属字段。例如 @loopback/rest-crud 的 ModelCrudRestApiConfig(见 [crud-rest.api-builder.ts)就在此基础上扩展了 basePath(控制器挂载的基路径,如 /products)和可选 readonly(为 true 时生成只读 API,即只暴露 find / count 端点)。
四、核心契约二:实现 ModelApiBuilder 接口
接口定义于 packages/model-api-builder/src/model-api-builder.ts:
export interface ModelApiBuilder {
readonly pattern: string; // e.g. CrudRest
build(
application: ApplicationWithRepositories,
modelClass: typeof Model & {prototype: Model},
config: ModelApiConfig,
): Promise<void>;
}
每个实现类必须提供:
pattern:一个只读字符串,标识该构建器支持的数据访问模式。ModelApiBooter会依据配置文件中的pattern字段精确匹配到唯一的构建器(匹配逻辑见下文第五节)。build():核心方法,接收三个参数——应用实例application(类型为ApplicationWithRepositories,即混入了 Repository 能力的 Application)、modelClass(要为其构建 API 的模型类)、config(上文ModelApiConfig)。方法返回Promise<void>,实现者在此方法内负责完成 Repository 与 Controller 的"搭建 + 注册"。
4.1 官方 README 的最小实现示例
@loopback/model-api-builder 的 README 给出了一个骨架级实现,展示如何声明一个可被扩展点拾取的构建器:
import {
asModelApiBuilder,
ModelApiBuilder,
ModelApiConfig,
} from '@loopback/model-api-builder';
@injectable(asModelApiBuilder)
export class SampleApiBuilder implements ModelApiBuilder {
readonly pattern: string = 'Sample';
build(
application: ApplicationWithRepositories,
modelClass: typeof Model & {prototype: Model},
config: ModelApiConfig,
): Promise<void> {
// define repository setup here
// ...
// define controller setup here
// ...
}
}
关键点是 @injectable(asModelApiBuilder):injectable 来自 @loopback/core,括号中的 asModelApiBuilder 是一个 binding template,它负责把类绑定到扩展点上,从而让 @loopback/core 的扩展点机制能够按需收集所有模型 API 构建器。真正的 Repository / Controller 定义逻辑写在 build() 的注释位置——README 用注释 // define repository setup here 与 // define controller setup here 明确划分了这两个职责区块。
五、核心契约三:asModelApiBuilder 绑定模板
asModelApiBuilder 的实现同样在 model-api-builder.ts:
export const MODEL_API_BUILDER_PLUGINS = 'model-api-builders';
export const asModelApiBuilder: BindingTemplate = binding => {
extensionFor(MODEL_API_BUILDER_PLUGINS)(binding);
binding.tag({namespace: 'model-api-builders'});
};
它做了两件事:
- 声明扩展点归属:通过
extensionFor(MODEL_API_BUILDER_PLUGINS)把绑定标记为名为model-api-builders的扩展点(extension point)下的扩展,常量MODEL_API_BUILDER_PLUGINS = 'model-api-builders'是扩展点名称的唯一定义处; - 打上命名空间标签:
binding.tag({namespace: 'model-api-builders'}),便于依赖注入与调试时按标签筛选。
在运行期,@loopback/core 的 @extensionPoint(MODEL_API_BUILDER_PLUGINS) 与 @extensions() 注入器(见下文 ModelApiBooter)会把所有经过 asModelApiBuilder 注册的构建器聚合成一个 Getter<ModelApiBuilder[]>,供消费方惰性获取。
六、与 ModelApiBooter 的协作:启动时如何自动装配
@loopback/model-api-builder 定义了契约,真正"消费"契约的是 @loopback/boot 包中的 ModelApiBooter(实现见 packages/boot/src/booters/model-api.booter.ts)。
ModelApiBooter 是 LoopBack 4 boot 体系中的一个 booter(通过 @booter('modelApi') 声明),默认约定如下:
- 扫描目录:
model-endpoints/ - 文件扩展名:
-config.js(实际以.rest-config.js、.rest-config.ts等形式出现) - 允许嵌套子目录:
nested: true
它通过 @extensionPoint(MODEL_API_BUILDER_PLUGINS) 注解与 @extensions() getModelApiBuilders: Getter<ModelApiBuilder<a href="https://link.gitcode.com/i/a61cfef24c5de358e664f240da76f8ff" target="_blank">]> 注入拿到全部构建器,然后对每个配置文件执行 setupModel(configFile)([model-api.booter.ts):
require(configFile)加载配置对象;- 校验
cfg.model必须是函数(即 Model 类),否则抛出Invalid "model" field. Expected a Model class, found ...; - 调用
getApiBuilderForPattern(cfg.pattern),在所有已注册构建器中用find(b => b.pattern === pattern)精确匹配; - 若无匹配构建器,抛出
Unsupported API pattern "<pattern>",并附带当前可用 patterns 列表; - 命中后调用
builder.build(this.app, modelClass, cfg)完成装配。
完整调用链为:配置文件 → ModelApiBooter → 按 pattern 匹配 ModelApiBuilder → build() 注册 Repository 与 Controller。packages/boot/src/__tests__/acceptance/model-api.booter.acceptance.ts 中的测试精确验证了这套行为:正确 pattern 会触发对应构建器、重复 pattern 使用先注册者、不存在的 pattern 抛出 Unsupported API pattern、非法 model 字段抛出 Invalid "model" field。测试夹具 stub-model-api-builder.ts 展示了最简构建器的组件封装方式——把构建器类通过 createBindingFromClass 放进 Component 的 bindings,再 app.component(...) 注册。
七、参考实现:@loopback/rest-crud 如何基于该契约落地
@loopback/rest-crud 是该契约最典型的官方实现(其 CrudRestApiBuilder 见 packages/rest-crud/src/crud-rest.api-builder.ts):
@injectable(asModelApiBuilder)
export class CrudRestApiBuilder implements ModelApiBuilder {
readonly pattern: string = 'CrudRest';
build(
application: ApplicationWithRepositories,
modelClass: typeof Model & {prototype: Model},
cfg: ModelApiConfig,
): Promise<void> {
const modelName = modelClass.name;
const config = cfg as ModelCrudRestApiConfig;
if (!config.basePath) {
throw new Error(
`Missing required field "basePath" in configuration for model ${modelName}.`,
);
}
// ...
const repositoryClass = setupCrudRepository(entityClass, config);
application.repository(repositoryClass);
// ...
const controllerClass = setupCrudRestController(entityClass, config);
application.controller(controllerClass);
// ...
}
}
它展示了 build() 的两个典型动作:调用 defineCrudRepositoryClass 生成 Repository 类并 application.repository(...) 注册;调用 defineCrudRestController 生成 Controller 类并 application.controller(...) 注册,同时通过 inject 装饰第一个构造参数注入数据源(datasources.${config.dataSource})与仓库绑定(repositories.${entityClass.name}Repository)。另外两点工程细节值得注意:
CrudRestComponent(packages/rest-crud/src/crud-rest.component.ts)把CrudRestApiBuilder包装成组件:bindings = [createBindingFromClass(CrudRestApiBuilder)],使用者只需this.component(CrudRestComponent)即可注册该构建器;ModelCrudRestApiConfig用basePath与readonly扩展了基础ModelApiConfig,正是第四节所述索引签名灵活性的实际体现。
defineCrudRestController 生成的控制器(packages/rest-crud/src/crud-rest.controller.ts)包含完整 CRUD 端点:GET /、GET /{id}、GET /count 属于只读控制器,非只读模式额外提供 POST /、PATCH /、PATCH /{id}、PUT /{id}、DELETE /{id};当 readonly: true 时仅暴露前三个查询类 API。其行为由 default-model-crud-rest.acceptance.ts 等验收测试覆盖(例如创建后返回 200、拒绝请求体携带 id 等)。
八、端到端示例:Todo 模型零手写 Repository / Controller
仓库中的 examples/rest-crud 是"单模型 + 单数据源、使用默认 CRUD REST 仓库与控制器"的最小可运行示例。在应用构造器中注册组件(examples/rest-crud/src/application.ts):
this.component(RestExplorerComponent);
this.component(CrudRestComponent);
然后在 model-endpoints/ 目录下放置模型端点配置文件(examples/rest-crud/src/model-endpoints/todo.rest-config.ts):
import {ModelCrudRestApiConfig} from '@loopback/rest-crud';
import {Todo} from '../models';
module.exports = <ModelCrudRestApiConfig>{
model: Todo,
pattern: 'CrudRest',
dataSource: 'db',
basePath: '/todos',
};
这段配置表达的是:为 Todo 模型使用 CrudRest 模式、底层数据源为 db、控制器挂载在 /todos 基路径下。启动应用(从示例根目录 npm start,服务默认运行于 http://127.0.0.1:3000)后,Todo 即拥有默认的 Repository 与 Controller,无需再编写任何 repository 或 controller 类文件——这比完整版 todo 示例 精简了整整两个手写类。
九、编写自己的 Model API 构建器:步骤清单
结合以上契约,从零实现一个自定义 API 构建器只需四步:
- 实现接口:定义类并实现
ModelApiBuilder,为pattern赋一个全局唯一字符串(如'MyPattern'); - 应用绑定模板:在类上使用
@injectable(asModelApiBuilder),使其成为model-api-builders扩展点的一员; - 实现 build():在方法体内根据
modelClass与config生成 Repository / Controller 类并注册到application(可复用@loopback/repository的defineCrudRepositoryClass与@loopback/rest-crud的defineCrudRestController等工厂函数,也可完全自定义); - 注册到应用:把类包进 Component(参考
CrudRestComponent的createBindingFromClass写法),或直接app.bind('...').toClass(...),随后在model-endpoints/下编写对应pattern的配置文件即可被ModelApiBooter自动拾取。
如果配置文件中写入了未注册的 pattern,启动时会得到明确的错误提示:Unsupported API pattern "<pattern>". Available patterns: <none>(可用列表来自所有已注册构建器的 pattern 字段)。
十、进一步阅读
- 契约源码:packages/model-api-builder/src/model-api-builder.ts、packages/model-api-builder/src/model-api-config.ts、packages/model-api-builder/src/index.ts
- 契约消费方:packages/boot/src/booters/model-api.booter.ts 与其验收测试 packages/boot/src/tests/acceptance/model-api.booter.acceptance.ts
- 官方参考实现:packages/rest-crud/src/crud-rest.api-builder.ts、packages/rest-crud/src/crud-rest.controller.ts
- 可运行示例:examples/rest-crud/README.md 与 examples/rest-crud/src/model-endpoints/todo.rest-config.ts