## 版本控制 > **提示**：本章僅與基于 HTTP 的應用程序相關。 版本控制允許您在同一應用程序中運行**不同版本的控制器或單獨的路由。**應用程序**變化非常頻繁，您需要進行重大更改，同時仍需要支持應用程序的先前版本，這并不罕見。 支持 3 種類型的版本控制： | | | | --- | --- | | `URI Versioning ` | 版本將在請求的 URI 中傳遞（默認）| | `Header Versioning` | 自定義請求標頭將指定版本 | | `Media Type Versioning` | 請求的`Accept`標頭將指定版本 | ## URI 版本控制類型(URI Versioning)[#](#uri-versioning-type) URI 版本控制使用在請求的 URI 中傳遞的版本，例如`https://example.com/v1/route`和`https://example.com/v2/route`。 > **注意**使用 URI 版本控制，版本將自動添加到 URI 中[全局路徑前綴](https://docs.nestjs.com/faq/global-prefix)（如果存在）之后，任何控制器或路由路徑之前。 要為您的應用程序啟用 URI 版本控制，請執行以下操作： >main.ts ~~~typescript const app = await NestFactory.create(AppModule); // or "app.enableVersioning()" app.enableVersioning({ type: VersioningType.URI, }); await app.listen(3000); ~~~ > **注意**默認情況下，URI 中的版本將自動以 `v` 為前綴，但是可以通過將前綴鍵設置為您想要的前綴來配置前綴值，如果您希望禁用它，則可以設置為 false。 > **提示**：`VersioningType` 枚舉可用于 `type` 屬性，并從 `@nestjs/common` 包中導入。 ## 標頭版本控制類型(Header Versioning)[#](#header-versioning-type) 標頭版本控制使用自定義的、用戶指定的請求標頭來指定標頭的值將是用于請求的版本的版本。 標頭版本控制的 HTTP 請求示例： 要為您的應用程序啟用**標頭版本控制**，請執行以下操作： >main.ts ~~~typescript const app = await NestFactory.create(AppModule); app.enableVersioning({ type: VersioningType.HEADER, header: 'Custom-Header', }); await app.listen(3000); ~~~ 該`header`屬性應該是包含請求版本的標頭的名稱。 > **提示**：`VersioningType` 枚舉可用于 `type` 屬性，并從 `@nestjs/common` 包中導入。 ## 媒體類型 版本控制類型(Media Type Versioning)[#](https://docs.nestjs.com/techniques/versioning#media-type-versioning-type) 媒體類型版本控制使用`Accept`請求的標頭來指定版本。 在`Accept`標頭中，版本將與媒體類型用分號分隔，`;`.然后它應該包含一個鍵值對，表示用于請求的版本，例如`Accept: application/json;v=2`.在確定要配置為包含鍵和分隔符的版本時，它們的鍵更多地被視為前綴。 要為您的應用程序啟用**媒體類型版本控制**，請執行以下操作： >main.ts ~~~typescript const app = await NestFactory.create(AppModule); app.enableVersioning({ type: VersioningType.MEDIA_TYPE, key: 'v=', }); await app.listen(3000); ~~~ 該`key`屬性應該是包含版本的鍵值對的鍵和分隔符。例如`Accept: application/json;v=2`，該`key`屬性將設置為`v=`。 > **提示**：`VersioningType` 枚舉可用于 `type` 屬性，并從 `@nestjs/common` 包中導入。 ## 用法[#](#usage) 版本控制允許您對控制器、單個路由進行版本控制，并且還為某些資源提供了一種選擇退出版本控制的方法。無論您的應用程序使用何種版本控制類型，版本控制的使用都是相同的。 > **注意**如果為應用程序啟用了版本控制，但控制器或路由未指定版本，則對該控制器/路由的任何請求都將返回`404`響應狀態。類似地，如果接收到的請求包含沒有對應控制器或路由的版本，也會返回`404`響應狀態。 #### 控制器版本[#](#controller-versions) 可以將版本應用于控制器，為控制器內的所有路由設置版本。 要將版本添加到控制器，請執行以下操作： >cats.controller.ts ~~~typescript @Controller({ version: '1', }) export class CatsControllerV1 { @Get('cats') findAll(): string { return 'This action returns all cats for version 1'; } } ~~~ #### 路由版本[#](#route-versions) 一個版本可以應用于單個路由。此版本將覆蓋任何其他會影響路由的版本，例如控制器版本。 要將版本添加到單個路由，請執行以下操作： >cats.controller.ts ~~~typescript 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'; } } ~~~ #### 多個版本[#](https://docs.nestjs.com/techniques/versioning#multiple-versions) 多個版本可以應用于控制器或路由。要使用多個版本，您可以將版本設置為數組。 要添加多個版本，請執行以下操作： >cats.controller.ts ~~~typescript @Controller({ version: ['1', '2'], }) export class CatsController { @Get('cats') findAll(): string { return 'This action returns all cats for version 1 or 2'; } } ~~~ #### 版本“中性”[#](#version-neutral) 一些控制器或路由可能不關心版本，并且無論版本如何都具有相同的功能。為了適應這種情況，可以將版本設置為`VERSION_NEUTRAL`符號。 傳入的請求將被映射到`VERSION_NEUTRAL`控制器或路由，無論請求中發送的版本如何，除非請求根本不包含版本。 > **注意**對于 URI 版本控制，`VERSION_NEUTRAL`資源的版本不會出現在 URI 中。 要添加版本中性控制器或路由，請執行以下操作： >cats.controller.ts ~~~typescript 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'; } } ~~~ ## 全局默認版本[#](#global-default-version) 如果您不想為每個控制器/或單個路由提供版本，或者如果您希望將特定版本設置為每個未指定版本的控制器/路由的默認版本，則可以設置 `defaultVersion` 如下： >main.ts ~~~typescript app.enableVersioning({ // ... defaultVersion: '1' // or defaultVersion: ['1', '2'] // or defaultVersion: VERSION_NEUTRAL }); ~~~