NestJS 中文文档

主题

版本控制 ​

提示

本章仅与基于 HTTP 的应用程序相关。

版本控制允许你在同一个应用程序中运行不同版本的控制器或单独的路由。应用程序经常发生变化，在仍需要支持先前版本的应用程序的同时，需要进行破坏性更改的情况并不少见。

支持 4 种类型的版本控制：

类型描述
URI Versioning版本将在请求的 URI 中传递（默认）
Header Versioning自定义请求头将指定版本
Media Type Versioning请求的 Accept 头将指定版本
Custom Versioning请求的任何方面都可以用于指定版本。提供自定义函数来提取所述版本。

URI 版本控制类型 ​

URI 版本控制使用请求 URI 中传递的版本，例如 https://example.com/v1/route 和 https://example.com/v2/route。

注意

使用 URI 版本控制时，版本会自动添加到全局路径前缀之后（如果存在的话），以及任何控制器或路由路径之前。

要为你的应用程序启用 URI 版本控制，请执行以下操作：

typescript
// main.ts
const app = await NestFactory.create(AppModule);
// 或 "app.enableVersioning()"
app.enableVersioning({
  type: VersioningType.URI,
});
await app.listen(process.env.PORT ?? 3000);

注意

默认情况下，URI 中的版本会自动添加 v 前缀，但可以通过将 prefix 属性设置为所需的前缀来配置前缀值，或者设置为 false 来禁用它。

提示

VersioningType 枚举可用于 type 属性，它从 @nestjs/common 包中导入。

Header 版本控制类型 ​

Header 版本控制使用自定义的、用户指定的请求头来指定版本，其中请求头的值将是用于该请求的版本。

要为你的应用程序启用 Header 版本控制，请执行以下操作：

typescript
// main.ts
const app = await NestFactory.create(AppModule);
app.enableVersioning({
  type: VersioningType.HEADER,
  header: 'Custom-Header',
});
await app.listen(process.env.PORT ?? 3000);

header 属性应该是包含请求版本的请求头名称。

提示

VersioningType 枚举可用于 type 属性，它从 @nestjs/common 包中导入。

Media Type 版本控制类型 ​

Media Type 版本控制使用请求的 Accept 头来指定版本。

在 Accept 头中，版本将通过分号 ; 与媒体类型分隔。然后它应该包含一个表示请求所用版本的键值对，例如 Accept: application/json;v=2。在确定版本时，键被视为前缀，需要将键和分隔符一起进行配置。

要为你的应用程序启用 Media Type 版本控制，请执行以下操作：

typescript
// main.ts
const app = await NestFactory.create(AppModule);
app.enableVersioning({
  type: VersioningType.MEDIA_TYPE,
  key: 'v=',
});
await app.listen(process.env.PORT ?? 3000);

key 属性应该是包含版本的键值对的键和分隔符。对于示例 Accept: application/json;v=2，key 属性应设置为 v=。

提示

VersioningType 枚举可用于 type 属性，它从 @nestjs/common 包中导入。

自定义版本控制类型 ​

自定义版本控制使用请求的任何方面来指定版本（或多个版本）。传入的请求通过 extractor 函数进行分析，该函数返回一个字符串或字符串数组。

如果请求者提供了多个版本，提取器函数可以返回一个字符串数组，按从最大/最高版本到最小/最低版本的顺序排序。版本按从高到低的顺序与路由匹配。

如果 extractor 返回空字符串或空数组，则不会匹配任何路由，并返回 404。

例如，如果传入请求指定它支持版本 1、2 和 3，extractor 必须返回 [3, 2, 1]。这确保首先选择最高的可用路由版本。

如果提取了版本 [3, 2, 1]，但路由仅存在于版本 2 和 1，则选择匹配版本 2 的路由（版本 3 会被自动忽略）。

注意

由于设计限制，基于 extractor 返回数组选择最高匹配版本的方式在 Express 适配器中无法可靠工作。单个版本（字符串或包含 1 个元素的数组）在 Express 中可以正常工作。Fastify 正确支持最高匹配版本选择和单版本选择。

要为你的应用程序启用自定义版本控制，请创建一个 extractor 函数并将其传递到应用程序中，如下所示：

typescript
// main.ts
// 示例提取器：从自定义请求头中提取版本列表并将其转换为排序后的数组。
// 此示例使用 Fastify，但 Express 请求可以以类似方式处理。
const extractor = (request: FastifyRequest): string | string[] =>
  [request.headers['custom-versioning-field'] ?? '']
     .flatMap(v => v.split(','))
     .filter(v => !!v)
     .sort()
     .reverse()

const app = await NestFactory.create(AppModule);
app.enableVersioning({
  type: VersioningType.CUSTOM,
  extractor,
});
await app.listen(process.env.PORT ?? 3000);

用法 ​

版本控制允许你对控制器和单独的路由进行版本管理，还提供了让某些资源不参与版本控制的方式。无论应用程序使用哪种版本控制类型，版本控制的用法都是相同的。

注意

如果应用程序启用了版本控制，但控制器或路由未指定版本，则对该控制器/路由的任何请求都将返回 404 响应状态。同样，如果接收到包含没有对应控制器或路由的版本的请求，也将返回 404 响应状态。

控制器版本 ​

可以为控制器应用版本，为控制器内的所有路由设置版本。

要为控制器添加版本，请执行以下操作：

typescript
// cats.controller.ts
@Controller({
  version: '1',
})
export class CatsControllerV1 {
  @Get('cats')
  findAll(): string {
    return 'This action returns all cats for version 1';
  }
}

路由版本 ​

可以为单独的路由应用版本。此版本将覆盖任何其他会影响该路由的版本，例如控制器版本。

要为单独的路由添加版本，请执行以下操作：

typescript
// cats.controller.ts
import { Controller, Get, Version } from '@nestjs/common';

@Controller()
export class CatsController {
  @Version('1')
  @Get('cats')
  findAllV1(): string {
    return 'This action returns all cats for version 1';
  }

  @Version('2')
  @Get('cats')
  findAllV2(): string {
    return 'This action returns all cats for version 2';
  }
}

多版本 ​

可以为控制器或路由应用多个版本。要使用多个版本，需要将版本设置为数组。

要添加多个版本，请执行以下操作：

typescript
// cats.controller.ts
@Controller({
  version: ['1', '2'],
})
export class CatsController {
  @Get('cats')
  findAll(): string {
    return 'This action returns all cats for version 1 or 2';
  }
}

版本 "Neutral" ​

某些控制器或路由可能不关心版本，无论版本如何都具有相同的功能。为了适应这种情况，可以将版本设置为 VERSION_NEUTRAL 符号。

无论请求中发送的版本是什么，传入的请求都会被映射到 VERSION_NEUTRAL 控制器或路由，即使请求完全不包含版本也是如此。

注意

对于 URI 版本控制，VERSION_NEUTRAL 资源的 URI 中不会包含版本信息。

要添加版本中性的控制器或路由，请执行以下操作：

typescript
// cats.controller.ts
import { Controller, Get, VERSION_NEUTRAL } from '@nestjs/common';

@Controller({
  version: VERSION_NEUTRAL,
})
export class CatsController {
  @Get('cats')
  findAll(): string {
    return 'This action returns all cats regardless of version';
  }
}

全局默认版本 ​

如果你不想为每个控制器或单独的路由提供版本，或者你想为未指定版本的每个控制器/路由设置特定版本作为默认版本，可以按如下方式设置 defaultVersion：

typescript
// main.ts
app.enableVersioning({
  // ...
  defaultVersion: '1'
  // 或
  defaultVersion: ['1', '2']
  // 或
  defaultVersion: VERSION_NEUTRAL
});

中间件版本控制 ​

中间件也可以使用版本控制元数据来为特定路由的版本配置中间件。为此，请将版本号作为 MiddlewareConsumer.forRoutes() 方法的参数之一提供：

typescript
// app.module.ts
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { LoggerMiddleware } from './common/middleware/logger.middleware';
import { CatsModule } from './cats/cats.module';
import { CatsController } from './cats/cats.controller';

@Module({
  imports: [CatsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware)
      .forRoutes({ path: 'cats', method: RequestMethod.GET, version: '2' });
  }
}

通过上面的代码，LoggerMiddleware 将仅应用于 /cats 端点的版本 '2'。

注意

中间件可以与本节中描述的任何版本控制类型一起使用：URI、Header、Media Type 或 Custom。

基于 NestJS 官方文档翻译

Copyright © 2024-present