# @adonisjs/route-model-binding 中文文档

规范地址：https://npmcn.com/package/%40adonisjs/route-model-binding/

版本：2\.0\.0-0
npm 元数据更新时间：2024-05-09T22:45:40.202Z
中文译文更新时间：2026-11-06T05:21:41.621Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adonisjs/route-model-binding
原文对照：https://npmcn.com/package/%40adonisjs/route-model-binding/?lang=original
项目主页：https://github.com/adonisjs/route-model-binding#readme
源码仓库：https://github.com/adonisjs/route-model-binding

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：57.8 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.11\.1
- 运行依赖：2 个
- peer 依赖：@adonisjs/core ^6\.9\.0，@adonisjs/lucid ^20\.5\.1
- 首次发布：2022-05-29T09:40:26.833Z
- 最新版本发布：2024-05-09T22:45:39.867Z
- 近 30 天下载量：4842（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

AdonisJS 的路由模型

## 安装

```sh
npm install @adonisjs/route-model-binding
```

也可以使用：`pnpm add @adonisjs/route-model-binding`、`yarn add @adonisjs/route-model-binding`、`bun add @adonisjs/route-model-binding`

## README

# @adonisjs/ route- model- 绑定

  

[![gh-workflow-image](https://img.shields.io/github/actions/workflow/status/adonisjs/route-model-binding/checks.yml?style=for-the-badge)](https://github.com/adonisjs/route-model-binding/actions/workflows/checks.yml "Github action") [![npm-image](https://img.shields.io/npm/v/@adonisjs/route-model-binding/latest.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@adonisjs/route-model-binding/v/latest "npm") ![](https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript) [![license-image](https://img.shields.io/github/license/adonisjs/route-model-binding?style=for-the-badge)](https://npmcn.com/package/%40adonisjs/route-model-binding/LICENSE.md)

## 导言

> 将路由参数与 Lucid 模型捆绑并自动查询数据库

路由模型绑定是从您的代码库中去掉单行道 Lucid 查询,并在HTTP请求时使用常规查询数据库的通畅方式.

在下面的例子中,我们连接路线参数 `:post` 财务报告和审定财务报表 `:comments` 二、缔约国接受的论点 `show` 方法.

-   来自 URL 的第一个参数的值将用来查询第一个输入的提示模型 `show` 方法(即员额).
-   同样地,第二段的值将被用于查询第二个被打入提示的模型(即注释).

> **说明**: 参数和模型使用它们出现的顺序而不是名称来连接. 这是因为TypeScript装饰器无法知道一种方法接受的参数的名称.

```ts
// Routes file
import router from '@adonisjs/core/services/router'

const PostsController = () => import('#controllers/posts_controller')

router.get('/posts/:post/comments/:comment', [PostsController, 'show'])
```

```ts
// Controller
import { bind } from '@adonisjs/route-model-binding'

import Post from '#models/post'
import Comment from '#models/comment'

export default class PostsController {
  @bind()
  async show({}, post: Post, comment: Comment) {
    return { post, comment }
  }
}
```

> ▶️: **你是视觉学习者吗**检查出 [这些屏幕播放器](https://learn.adonisjs.com/series/route-model-binding/introduction) 了解路由模型的装订、设置和使用.

## 设置

从 npm 登记册中安装软件包如下 .

```sh
npm i @adonisjs/route-model-binding

# yarn lovers
yarn add @adonisjs/route-model-binding
```

接下来,通过运行以下 A 命令来配置软件包.

```sh
node ace configure @adonisjs/route-model-binding
```

最后一步是登记 `RmbMiddleware` 内部 `start/kernel.ts` 文档.

```ts
import router from '@adonisjs/core/services/router'

router.use([
  // ...other middleware
  () => import('@adonisjs/route-model-binding/rmb_middleware'),
])
```

## 基本用途

从最基本的例子开始,然后调整复杂程度,为不同的使用案例服务.

在下面的例子中,我们将约束 `Post` 第一个参数的模型 `posts/:id` 路线.

```ts
import router from '@adonisjs/core/services/router'

const PostsController = () => import('#controllers/posts_controller.js')

router.get('/posts/:id', [PostsController, 'show'])
```

```ts
import { bind } from '@adonisjs/route-model-binding'

import Post from '#models/post'

export default class PostsController {
  @bind()
  async show({}, post: Post) {
    return { post }
  }
}
```

参数和模型按定义顺序相匹配. 因此URL中的第一个参数与控制器方法中的第一个打入型号相匹配.

由于TypeScript装饰器无法读取,因此不使用控制器方法参数的名称来进行匹配(因此技术限制让我们只能使用以订单为基础的匹配).

## 更改查找密钥

默认情况下,该模型的主键用于在数据库中找到匹配行. 你要么改变全球,要么改变它 只是为了一个特定路线.

### 通过模型在全球更改搜索键

以下更改后,将使用 `slug` 属性而不是主键。 简而言之 `Post.findByOrFail('slug', value)` 查询已执行 .

```ts
class Post extends BaseModel {
  static routeLookupKey = 'slug'
}
```

### 更改单一路径的搜索密钥 .

在下面的例子中,我们直接定义了括号所包围的路由上的查找键.

```ts
import router from '@adonisjs/core/services/router'

const PostsController = () => import('#controllers/posts_controller')

router.get('/posts/:id(slug)', [PostsController, 'show'])
```

**你注意到我们的路线 读起来有点好笑吗?**  
该段落写为 `:id(slug)`,但翻译不善。 因此,随着路由模型的约束,我们建议使用模型名称作为路由参数,因为我们不处理 `id` 现在 我们正在从数据库中获取模型实例.

遵循是写同样路线的更好方法.

```ts
import router from '@adonisjs/core/services/router'

const PostsController = () => import('#controllers/posts_controller')

router.get('/posts/:post(slug)', [PostsController, 'show'])
```

## 更改查询逻辑

您可以通过定义静态来改变搜索逻辑 `findForRequest` 模型本身上的方法。 该方法获得以下参数.

-   `ctx` - 当前请求的 HTTP 上下文
-   `param` - 解析参数。 该参数具有以下属性.
    -   `param.name` - 参数的正统名称.
    -   `param.param` - 路线上定义的参数的原名.
    -   `param.scoped` - 狦 `true`,该参数必须被扩展至其母模型.
    -   `param.lookupKey` - 在路线或模型上定义的查找键.
    -   `param.parent` - 家长代表的名字.
-   `value` - 本次请求中的参数值.

在下面的例子中,我们只查询已发表的文章。 另外,确保这种方法要么返回模型实例,要么提出例外.

```ts
class Post extends BaseModel {
  static findForRequest(ctx, param, value) {
    const lookupKey = param.lookupKey === '$primaryKey' ? 'id' : param.lookupKey

    return this
      .query()
      .where(lookupKey, value)
      .whereNotNull('publishedAt')
      .firstOrFail()
  }
}
```

## 范围参数

在使用被嵌入的路由资源时,您可能想要将第二段拓宽为与第一段拓宽的关系.

一个很好的例子就是通过 id 找到一个帖子评论.

这个 `posts/1/comments/2` 如果注释的后号不是,则应返回404 `1`。 。 。 .

您可以使用 `>` 大于标志或著名的 [面包屑标志](https://www.smashingmagazine.com/2009/03/breadcrumbs-in-web-design-examples-and-best-practices/#:~:text=You%20also%20see%20them%20in,the%20page%20links%20beside%20it.)

```ts
import router from '@adonisjs/core/services/router'

const PostsController = () => import('#controllers/posts_controller')

router.get('/posts/:post/comments/:>comment', [PostsController, 'show'])
```

```ts
import { bind } from '@adonisjs/route-model-binding'

import Post from '#models/post'
import Comment from '#models/comment'

export default class PostsController {
  @bind()
  async show({}, post: Post, comment: Comment) {
    return { post, comment }
  }
}
```

要使上述例子发挥作用,就必须界定 `comments` 关系的关系 `Post` 型号。 关系的类型并不重要.

```ts
class Post extends BaseModel {
  @hasMany(() => Comment)
  declare comments: HasMany<typeof Comment>
}
```

将参数名称转换为 `camelCase`我们将使用复数形式和单数形式寻找关系.

### 自定义关系查询

默认情况下,关系会使用绑定子模型的查找键来获取. 有效执行下列查询.

```ts
await parent
  .related('relationship')
  .query()
  .where(lookupKey, value)
  .firstOrFail()
```

不过,您可以通过定义“定义”来自定义浏览 `findRelatedForRequest` 模型上的方法(注,这不是静态方法).

```ts
class Post extends BaseModel {
  findRelatedForRequest(ctx, param, value) {
    /**
     * Have to do this weird dance because of
     * https://github.com/microsoft/TypeScript/issues/37778
     */
    const self = this as unknown as Post
    const lookupKey = param.lookupKey === '$primaryKey' ? 'id' : param.lookupKey

    if (param.name === 'comment') {
      return self
      .related('comments')
      .query()
      .where(lookupKey, value)
      .firstOrFail()
    }
  }
}
```

## 无约束的参数

您通常会有原始值参数, 并且不能与模型相绑定 。 例如 `version` 是正则字符串值,不使用数据库支持.

```ts
import router from '@adonisjs/core/services/router'

const PostsController = () => import('#controllers/posts_controller')

router.get(
  '/api/:version/posts/:post',
  [PostsController, 'show']
)
```

你可以代表 `version` 作为控制器方法上的字符串,我们将不进行数据库搜索。 例如:

```ts
import { bind } from '@adonisjs/route-model-binding'

import Post from '#models/post'

class PostsController {
  @bind()
  async show({}, version: string, post: Post) {}
}
```

由于路由参数和控制器方法参数的匹配顺序与定义的顺序相同,所以你总是必须打入所有参数.

## 行为守则

为了确保AdonisJS社区欢迎所有人,请审查和遵守 [行为守则](https://github.com/adonisjs/.github/blob/main/docs/CODE_OF_CONDUCT.md)。 。 。 .

## 许可证

AdonisJS 路由模型装订是开源软件,根据 [麻省理工学院许可证](https://npmcn.com/package/%40adonisjs/route-model-binding/LICENSE.md)。 。 。 .

## 常见问题

### @adonisjs/route-model-binding 是什么？

AdonisJS 的路由模型

### 如何安装 @adonisjs/route-model-binding？

在项目目录运行 npm install @adonisjs/route-model-binding，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@adonisjs/core（^6\.9\.0）、@adonisjs/lucid（^20\.5\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @adonisjs/route-model-binding 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @adonisjs/route-model-binding 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @adonisjs/route-model-binding 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.11\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @adonisjs/route-model-binding 可以商用吗？

@adonisjs/route-model-binding 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @adonisjs/route-model-binding 的下载量有多少？

根据 npm 官方下载统计，@adonisjs/route-model-binding 在 2026/10/05 – 2026/11/03 这 30 天内被下载 4,842 次，日均约 161 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adonisjs/route-model-binding 还在维护吗？

最新版本 2\.0\.0-0 发布于 2024/05/10（2 年前）；至今共发布 8 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/05/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。