NestJS自定义ACL访问控制终极教程nestjs-starter-rest-api如何实现细粒度权限引擎【免费下载链接】nestjs-starter-rest-apiNestJS Starter Kit. Monolithic Backend. REST API.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-apinestjs-starter-rest-api 是一个基于 NestJS 的单体 REST API 后端 Starter Kit内置了一套可自定义的 ACLAccess Control List访问控制权限引擎。本文将带你拆解它的真实实现如何用角色 动作 回调规则三件套做出只有文章作者本人才能修改自己文章这种细粒度权限新手也能快速上手 NestJS 权限设计。为什么路由级鉴权还不够很多 NestJS 项目只做两层防护JWT 认证确认你是谁jwt-auth.guard.ts角色守卫确认你有没有资格访问这个路由roles.guard.ts但业务里经常出现更细的问题张三能访问文章接口可他不能改李四写的文章。角色级判断回答不了这个问题必须把权限检查下沉到具体对象文章、用户级别。这就是 ACL 权限引擎要解决的——把谁能对哪个对象做什么操作抽象成一张规则表。官方文档 docs/acl.md 对此有完整说明本教程按实际代码带你走一遍。5分钟跑起来获取 nestjs-starter-rest-apigit clone https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-api cd nestjs-starter-rest-api npm install按 ormconfig.ts 配置好数据库连接后启动TypeORM 迁移脚本位于 migrations/ 目录npm run start:dev启动后可通过/api/docs的 Swagger 页面调试文章、用户等受权限保护的接口直观感受 ACL 的拦截效果。权限引擎的 4 个核心概念整个 ACL 引擎只有四个概念全部集中在src/shared/acl/目录下概念所在文件作用Role 角色role.constant.ts内置USER、ADMIN两种角色Action 动作action.constant.ts一次可执行的操作类型Actor 行为者actor.constant.ts当前操作用户含id和rolesAclRule 规则acl-rule.constant.ts某角色 某几个动作 可选回调其中 Action 内置了 6 种标准动作动作含义Create创建Read读取单个Update更新Delete删除List列表查询Manage超级权限拥有它即可执行一切操作三步定义一个业务 ACL 服务引擎的基类是 acl.service.ts 中的BaseAclService。每个业务模块只需继承它并声明规则。以文章模块为例article-acl.service.ts第 1 步继承基类指定资源类型export class ArticleAclService extends BaseAclServiceArticle { ... }第 2 步用canDo声明角色 → 动作映射this.canDo(ROLE.ADMIN, [Action.Manage]); // 管理员通吃 this.canDo(ROLE.USER, [Action.Create, Action.List, Action.Read]); // 普通用户可发布、看列表、阅读第 3 步给例外情况挂回调函数。canDo的第三个参数是自定义规则回调签名是(resource, actor) booleanthis.canDo(ROLE.USER, [Action.Update, Action.Delete], this.isArticleAuthor); isArticleAuthor(article: Article, user: Actor): boolean { return article.author.id user.id; // 只有作者本人能改/删 }用户模块的同款玩法见 user-acl.service.ts普通用户可读任意用户资料但Update动作挂上isUserItself回调——只能改自己。在业务代码里执行权限判定规则声明好后判定只需一行链式调用forActor(用户)拿到该用户的专属权限对象再用canDoAction检查具体动作。以 article.service.ts 中的更新文章为例模式是统一的const isAllowed this.aclService .forActor(actor) .canDoAction(Action.Update, article); // 把对象传进去回调规则才会生效 if (!isAllowed) { throw new UnauthorizedException(); // 401 拦截 }引擎内部的判定逻辑acl.service.ts遍历用户拥有的所有角色匹配对应角色的全部规则只要规则包含目标动作、或包含Manage超级权限且如有回调函数返回true即放行。 小技巧Manage是超级动作。给某角色配置Manage后它对该资源的任何动作检查都会直接通过非常适合管理员。双层防线路由守卫 ACL 引擎nestjs-starter-rest-api 的权限体系是粗细两层配合的层级实现粒度典型场景路由级粗Roles()装饰器 RolesGuard按角色放行整条路由获取用户列表仅管理员和登录用户可访问对象级细BaseAclService ACL 服务按用户 × 动作 × 对象判定只有作者能改这篇文章路由级用法见 user.controller.tsUseGuards(JwtAuthGuard, RolesGuard) Roles(ROLE.ADMIN, ROLE.USER) async getUsers(...) { ... }装饰器定义在 role.decorator.ts守卫逻辑在 roles.guard.ts——它通过反射读取路由上标注的角色不匹配就抛出UnauthorizedException。推荐实践先用路由守卫挡住完全无权的角色省算力再在 Service 层用 ACL 引擎做对象级精确判定保安全。关键源码文件一览文件作用acl.service.tsBaseAclService权限引擎核心canDo声明规则、forActor执行判定action.constant.ts6 种标准动作枚举含Manage超级权限acl-rule.constant.tsAclRule规则结构与RuleCallback回调定义actor.constant.tsActor行为者接口id rolesrole.constant.tsUSER/ADMIN角色枚举article-acl.service.ts文章 ACL 完整示例作者本人回调user-acl.service.ts用户 ACL 示例仅能更新自己roles.guard.ts路由级角色守卫role.decorator.tsRoles()元数据装饰器docs/acl.md官方 ACL 使用说明文档相关测试用例位于 acl.service.spec.ts想深入验证引擎行为可以跑npm test。动手清单给你的项目加上同款 ACL把src/shared/acl/下的 4 个文件引擎核心复制到你的项目为你的角色体系补全ROLE枚举role.constant.ts每个业务模块新建一个XxxAclService extends BaseAclServiceXxxEntity在构造函数里canDo声明规则在 Service 层注入该 ACL 服务对每个写操作执行forActor(user).canDoAction(action, resource)并拦截 401总结nestjs-starter-rest-api 的 ACL 权限引擎用极少的代码量实现了细粒度访问控制BaseAclService一个基类管判定canDo一行声明规则回调函数兜底个性化例外。配合路由级的Roles()守卫形成粗筛 精判的双层防线。这套模式不依赖任何第三方权限库逻辑透明、易于扩展非常值得在自己的 NestJS REST API 项目中直接借鉴。【免费下载链接】nestjs-starter-rest-apiNestJS Starter Kit. Monolithic Backend. REST API.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考