守衛(wèi)是一個(gè)使用 @Injectable() 裝飾器的類(lèi)。 守衛(wèi)應(yīng)該實(shí)現(xiàn) CanActivate 接口。
守衛(wèi)有一個(gè)單獨(dú)的責(zé)任。它們根據(jù)運(yùn)行時(shí)出現(xiàn)的某些條件(例如權(quán)限,角色,訪問(wèn)控制列表等)來(lái)確定給定的請(qǐng)求是否由路由處理程序處理。 這通常稱(chēng)為授權(quán)。在傳統(tǒng)的 Express 應(yīng)用程序中,通常由中間件處理授權(quán)。中間件是身份驗(yàn)證的良好選擇。到目前為止,訪問(wèn)限制邏輯大多在中間件內(nèi)。這樣很好,因?yàn)橹T如 token 驗(yàn)證或?qū)?nbsp;request 對(duì)象附加屬性與特定路由沒(méi)有強(qiáng)關(guān)聯(lián)。
中間件不知道調(diào)用 next() 函數(shù)后會(huì)執(zhí)行哪個(gè)處理程序。另一方面,守衛(wèi)可以訪問(wèn) ExecutionContext 實(shí)例,因此確切地知道接下來(lái)要執(zhí)行什么。它們的設(shè)計(jì)與異常過(guò)濾器、管道和攔截器非常相似,目的是讓您在請(qǐng)求/響應(yīng)周期的正確位置插入處理邏輯,并以聲明的方式進(jìn)行插入。這有助于保持代碼的簡(jiǎn)潔和聲明性。
守衛(wèi)在每個(gè)中間件之后執(zhí)行,但在任何攔截器或管道之前執(zhí)行。
正如前面提到的,授權(quán)是保護(hù)的一個(gè)很好的用例,因?yàn)橹挥挟?dāng)調(diào)用者(通常是經(jīng)過(guò)身份驗(yàn)證的特定用戶(hù))具有足夠的權(quán)限時(shí),特定的路由才可用。我們現(xiàn)在要構(gòu)建的 AuthGuard 假設(shè)用戶(hù)是經(jīng)過(guò)身份驗(yàn)證的(因此,請(qǐng)求頭附加了一個(gè)token)。它將提取和驗(yàn)證token,并使用提取的信息來(lái)確定請(qǐng)求是否可以繼續(xù)。
auth.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(
context: ExecutionContext,
): boolean | Promise<boolean> | Observable<boolean> {
const request = context.switchToHttp().getRequest();
return validateRequest(request);
}
}
validateRequest() 函數(shù)中的邏輯可以根據(jù)需要變得簡(jiǎn)單或復(fù)雜。本例的主要目的是說(shuō)明保護(hù)如何適應(yīng)請(qǐng)求/響應(yīng)周期。
每個(gè)守衛(wèi)必須實(shí)現(xiàn)一個(gè)canActivate()函數(shù)。此函數(shù)應(yīng)該返回一個(gè)布爾值,指示是否允許當(dāng)前請(qǐng)求。它可以同步或異步地返回響應(yīng)(通過(guò) Promise 或 Observable)。Nest使用返回值來(lái)控制下一個(gè)行為:
canActivate() 函數(shù)接收單個(gè)參數(shù) ExecutionContext 實(shí)例。ExecutionContext 繼承自 ArgumentsHost 。ArgumentsHost 是傳遞給原始處理程序的參數(shù)的包裝器,在上面的示例中,我們只是使用了之前在 ArgumentsHost上定義的幫助器方法來(lái)獲得對(duì)請(qǐng)求對(duì)象的引用。有關(guān)此主題的更多信息。你可以在這里了解到更多(在異常過(guò)濾器章節(jié))。
ExecutionContext 提供了更多功能,它擴(kuò)展了 ArgumentsHost,但是也提供了有關(guān)當(dāng)前執(zhí)行過(guò)程的更多詳細(xì)信息。
export interface ExecutionContext extends ArgumentsHost {
getClass<T = any>(): Type<T>;
getHandler(): Function;
}
getHandler()方法返回對(duì)將要調(diào)用的處理程序的引用。getClass()方法返回這個(gè)特定處理程序所屬的 Controller 類(lèi)的類(lèi)型。例如,如果當(dāng)前處理的請(qǐng)求是 POST 請(qǐng)求,目標(biāo)是 CatsController上的 create() 方法,那么 getHandler() 將返回對(duì) create() 方法的引用,而 getClass()將返回一個(gè)CatsControllertype(而不是實(shí)例)。
一個(gè)更詳細(xì)的例子是一個(gè) RolesGuard 。這個(gè)守衛(wèi)只允許具有特定角色的用戶(hù)訪問(wèn)。我們將從一個(gè)基本模板開(kāi)始,并在接下來(lái)的部分中構(gòu)建它。目前,它允許所有請(qǐng)求繼續(xù):
roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';
@Injectable()
export class RolesGuard implements CanActivate {
canActivate(
context: ExecutionContext,
): boolean | Promise<boolean> | Observable<boolean> {
return true;
}
}
與管道和異常過(guò)濾器一樣,守衛(wèi)可以是控制范圍的、方法范圍的或全局范圍的。下面,我們使用 @UseGuards()裝飾器設(shè)置了一個(gè)控制范圍的守衛(wèi)。這個(gè)裝飾器可以使用單個(gè)參數(shù),也可以使用逗號(hào)分隔的參數(shù)列表。也就是說(shuō),你可以傳遞幾個(gè)守衛(wèi)并用逗號(hào)分隔它們。
@Controller('cats')
@UseGuards(RolesGuard)
export class CatsController {}
@UseGuards() 裝飾器需要從 @nestjs/common 包導(dǎo)入。
上例,我們已經(jīng)傳遞了 RolesGuard 類(lèi)型而不是實(shí)例, 讓框架進(jìn)行實(shí)例化,并啟用了依賴(lài)項(xiàng)注入。與管道和異常過(guò)濾器一樣,我們也可以傳遞一個(gè)實(shí)例:
@Controller('cats')
@UseGuards(new RolesGuard())
export class CatsController {}
上面的構(gòu)造將守衛(wèi)附加到此控制器聲明的每個(gè)處理程序。如果我們決定只限制其中一個(gè), 我們只需要在方法級(jí)別設(shè)置守衛(wèi)。為了綁定全局守衛(wèi), 我們使用 Nest 應(yīng)用程序?qū)嵗?nbsp;useGlobalGuards() 方法:
為了設(shè)置一個(gè)全局守衛(wèi),使用Nest應(yīng)用程序?qū)嵗?nbsp;useGlobalGuards() 方法:
const app = await NestFactory.create(AppModule);
app.useGlobalGuards(new RolesGuard());
對(duì)于混合應(yīng)用程序,useGlobalGuards() 方法不會(huì)為網(wǎng)關(guān)和微服務(wù)設(shè)置守衛(wèi)。對(duì)于“標(biāo)準(zhǔn)”(非混合)微服務(wù)應(yīng)用程序,useGlobalGuards()在全局安裝守衛(wèi)。
全局守衛(wèi)用于整個(gè)應(yīng)用程序, 每個(gè)控制器和每個(gè)路由處理程序。在依賴(lài)注入方面, 從任何模塊外部注冊(cè)的全局守衛(wèi) (如上面的示例中所示) 不能插入依賴(lài)項(xiàng), 因?yàn)樗鼈儾粚儆谌魏文K。為了解決此問(wèn)題, 您可以使用以下構(gòu)造直接從任何模塊設(shè)置一個(gè)守衛(wèi):
app.module.ts
import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
@Module({
providers: [
{
provide: APP_GUARD,
useClass: RolesGuard,
},
],
})
export class AppModule {}
當(dāng)使用此方法為守衛(wèi)程序執(zhí)行依賴(lài)項(xiàng)注入時(shí),請(qǐng)注意,無(wú)論使用此構(gòu)造的模塊是什么,守衛(wèi)程序?qū)嶋H上是全局的。應(yīng)該在哪里進(jìn)行?選擇定義守衛(wèi)的模塊(上例中的 RolesGuard)。此外,useClass不是處理自定義 providers 注冊(cè)的唯一方法。在這里了解更多。
守衛(wèi)現(xiàn)在在正常工作,但還不是很智能。我們?nèi)匀粵](méi)有利用最重要的守衛(wèi)的特征,即執(zhí)行上下文。它還不知道角色,或者每個(gè)處理程序允許哪些角色。例如,CatsController 可以為不同的路由提供不同的權(quán)限方案。其中一些可能只對(duì)管理用戶(hù)可用,而另一些則可以對(duì)所有人開(kāi)放。我們?nèi)绾我造`活和可重用的方式將角色與路由匹配起來(lái)?
這就是自定義元數(shù)據(jù)發(fā)揮作用的地方。Nest提供了通過(guò) @SetMetadata() 裝飾器將定制元數(shù)據(jù)附加到路由處理程序的能力。這些元數(shù)據(jù)提供了我們所缺少的角色數(shù)據(jù),而守衛(wèi)需要這些數(shù)據(jù)來(lái)做出決策。讓我們看看使用@SetMetadata():
cats.controller.ts
@Post()
@SetMetadata('roles', ['admin'])
async create(@Body() createCatDto: CreateCatDto) {
this.catsService.create(createCatDto);
}
@SetMetadata() 裝飾器需要從 @nestjs/common 包導(dǎo)入。
通過(guò)上面的構(gòu)建,我們將 roles 元數(shù)據(jù)(roles 是一個(gè)鍵,而 ['admin'] 是一個(gè)特定的值)附加到 create() 方法。 直接使用 @SetMetadata() 并不是一個(gè)好習(xí)慣。 相反,你應(yīng)該創(chuàng)建你自己的裝飾器。
roles.decorator.ts
import { SetMetadata } from '@nestjs/common';
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
這種方法更簡(jiǎn)潔、更易讀,而且是強(qiáng)類(lèi)型的。現(xiàn)在我們有了一個(gè)自定義的 @Roles() 裝飾器,我們可以使用它來(lái)裝飾 create()方法。
cats.controller.ts
@Post()
@Roles('admin')
async create(@Body() createCatDto: CreateCatDto) {
this.catsService.create(createCatDto);
}
讓我們?cè)俅位氐?nbsp;RolesGuard 。 它只是在所有情況下返回 true,到目前為止允許請(qǐng)求繼續(xù)。我們希望根據(jù)分配給當(dāng)前用戶(hù)的角色與正在處理的當(dāng)前路由所需的實(shí)際角色之間的比較來(lái)設(shè)置返回值的條件。 為了訪問(wèn)路由的角色(自定義元數(shù)據(jù)),我們將使用在 @nestjs/core 中提供的 Reflector 幫助類(lèi)。
roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
const roles = this.reflector.get<string[]>('roles', context.getHandler());
if (!roles) {
return true;
}
const request = context.switchToHttp().getRequest();
const user = request.user;
return matchRoles(roles, user.roles);
}
}
在 node.js 世界中,將授權(quán)用戶(hù)附加到 request 對(duì)象是一種常見(jiàn)的做法。 因此,在上面的示例代碼中。我們假設(shè) request.user 包含用戶(hù)實(shí)例和允許的角色。 在您的應(yīng)用中,您可能會(huì)在自定義身份驗(yàn)證(或中間件)中建立該關(guān)聯(lián)。
matchRoles() 函數(shù)內(nèi)部的邏輯可以根據(jù)需要簡(jiǎn)單或復(fù)雜。該示例的重點(diǎn)是顯示防護(hù)如何適應(yīng)請(qǐng)求/響應(yīng)周期。
現(xiàn)在,當(dāng)用戶(hù)嘗試在沒(méi)有足夠權(quán)限的情況下調(diào)用 /cats POST端點(diǎn)時(shí),Nest 會(huì)自動(dòng)返回以下響應(yīng):
有關(guān)以上下文相關(guān)方式進(jìn)行利用的更多詳細(xì)信息,請(qǐng)參見(jiàn)“ 執(zhí)行”上下文章節(jié)的“ 反射和元數(shù)據(jù)”部分。
當(dāng)特權(quán)不足的用戶(hù)請(qǐng)求端點(diǎn)時(shí),Nest自動(dòng)返回以下響應(yīng):
{
"statusCode": 403,
"message": "Forbidden resource"
}
實(shí)際上,返回 false 的守衛(wèi)會(huì)拋出一個(gè) HttpException 異常。如果您想要向最終用戶(hù)返回不同的錯(cuò)誤響應(yīng),你應(yīng)該拋出一個(gè)異常。
throw new UnauthorizedException();
由守衛(wèi)引發(fā)的任何異常都將由異常層(全局異常過(guò)濾器和應(yīng)用于當(dāng)前上下文的任何異常過(guò)濾器)處理。
更多建議: