快捷導(dǎo)航

NestJS實(shí)現(xiàn)接口的多版本管理

更新時(shí)間：2024年06月13日 08:42:44 作者：云牧

在軟件開(kāi)發(fā)中,隨著應(yīng)用的迭代更新,經(jīng)常需要引入新的接口版本同時(shí)保留舊版本以保證向后兼容,本教程將通過(guò) NestJS 框架演示如何實(shí)現(xiàn)接口的多版本管理,感興趣的小伙伴跟著小編一起來(lái)看看吧

創(chuàng)建和運(yùn)行項(xiàng)目

首先，我們需要?jiǎng)?chuàng)建一個(gè)新的 NestJS 項(xiàng)目，并啟動(dòng)服務(wù)：

nest new version-test -p pnpm
cd version-test
nest g resource TestVersion --no-spec
pnpm start:dev

啟用接口版本控制

在 main.ts 文件中，引入版本控制功能，并設(shè)置版本信息通過(guò) HTTP 頭部傳遞：

import { VersioningType } from '@nestjs/common';
import { AppModule } from './app.module';
import { NestFactory } from '@nestjs/core';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.enableVersioning({
    type: VersioningType.HEADER,
    header: 'version', // 指定傳遞版本信息的 HTTP 頭部字段名為 'version'
  });

  await app.listen(3000);
}

bootstrap();

配置版本控制

在控制器中，我們可以通過(guò) @Version 裝飾器指定接口版本。

例如，將默認(rèn)接口設(shè)置為版本 1，并為新版本創(chuàng)建專(zhuān)門(mén)的接口：

import { Controller, Get, Version } from '@nestjs/common';
import { TestVersionService } from './test-version.service';

@Controller('test-version')
export class TestVersionController {
  constructor(private readonly testVersionService: TestVersionService) {}

  @Get()
  @Version('1')
  findAllV1() {
    return this.testVersionService.findAll();
  }

  @Get()
  @Version('2')
  findAllV2() {
    return this.testVersionService.findAll() + '版本2';
  }
}

帶上不同的請(qǐng)求頭，獲得的結(jié)果不一樣。

版本中立的接口

如果希望某些接口無(wú)論什么版本號(hào)如何都能訪問(wèn)，可以使用 VERSION_NEUTRAL 常量：

import { VERSION_NEUTRAL, Controller, Get } from '@nestjs/common';

@Controller({
  path: 'test-version',
  version: VERSION_NEUTRAL
})
export class NeutralAaaController {
  // 接口實(shí)現(xiàn)
}

其他版本控制方式

NestJS 還支持通過(guò)媒體類(lèi)型（Media Type）或 URI 路徑來(lái)控制版本：

Media Type

版本信息通過(guò) Accept 頭部傳遞：

app.enableVersioning({
    type: VersioningType.MEDIA_TYPE,
    key: 'vvv='
})

如果客戶(hù)端希望請(qǐng)求版本 1 的 API，它需要在 HTTP 請(qǐng)求的 Accept 頭部中加入如下內(nèi)容：

Accept: application/json;vvv=1

URI 版本控制

版本信息直接在 URL 路徑中指定：

app.enableVersioning({
  type: VersioningType.URI,
});

在這個(gè)設(shè)置下，如果客戶(hù)端需要訪問(wèn)版本 1 的 API，URL 應(yīng)該像這樣：

http://localhost:3000/v1/users

對(duì)于版本 2，URL 應(yīng)該是：

http://localhost:3000/v2/users

這種方式使得版本控制非常明顯，客戶(hù)端一看 URL 就能明白所請(qǐng)求的 API 版本。但可能會(huì)導(dǎo)致 URL 空間的膨脹。
注意這種方式不支持 VERSION_NEUTRAL，需要明確版本號(hào)：

@Controller({
  path: 'test-version',
  version: ["2", "3"]
})

自定義版本控制邏輯

如果內(nèi)置的版本控制方式不滿足需求，可以實(shí)現(xiàn)自定義版本控制邏輯：

import { VersioningType, NestFactory } from '@nestjs/common';
import { AppModule } from './app.module';
import { Request } from 'express';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const extractor = (request: Request) => {
    if (request.headers['disable-custom']) {
      return '';
    }
    return request.url.includes('yun') ? '2' : '1';
  };
  app.enableVersioning({
    type: VersioningType.CUSTOM,
    extractor
  });
  await app.listen(3000);
}

bootstrap();