剪藏
Rethinking your position
Learn how to learn
3R编码 | nestjs最佳实践 - 课程概览
3R编码 | Node.js开发环境搭建
3R编码 | Nestjs+Eslint+SWC应用初始化及断点调试
3R编码 | 装饰器与反射
3R编码 | Nestjs核心概念
3R编码 | 无懈可击的Linux服务器构建
3R编码 | 使用Turborepo+pnpm workspaces构建monorepo应用
3R编码 | 使用Gitea+Drone自建CICD平台
3R编码 | 整合Typeorm实现CRUD
3R编码 | 请求数据的验证和响应数据的序列化
3R编码 | 数据关联与树形嵌套结构的分类和评论的实现
3R编码 | 自定义全局的验证管道,拦截器和过滤器
3R编码 | 自定义数据验证约束及约束中的依赖注入
3R编码 | 批量操作及软删除(回收站)功能使用
3R编码 | 数据库与MeiliSearch的全文搜索
3R编码 | 数据操作代码的抽象化
3R编码 | 整合bun与pm2实现开发环境与生产环境免编译和自启
3R编码 | 自建配置系统实现
3R编码 | 嵌套路由与Swagger文档实现
3R编码 | 使用Yargs构建命令行工具
3R编码 | 生产环境下静默启动以及PM2 API的使用
3R编码 | 数据迁移功能的实现
3R编码 | 数据填充命令实现
3R编码 | 用户模块开发以及使用Passport实现JWT认证和无痛刷新
3R编码 | 基于CASL的RBAC动态角色及权限系统实现
3R编码 | 模型动态关联与基于CASL的动态权限的实现
3R编码 | 使用BullMQ实现异步验证短信与邮件发送
3R编码 | WebSocket实现消息广播功能
3R编码 | chapter27
3R编码 | chapter28
3R编码 | TS全栈+AI开发实战 - 课程概览
3R编码 | Node.js环境搭建及应用初始化
3R编码 | Next.js应用初始化
3R编码 | React内置Hooks的使用与自定义详解
3R编码 | Next.js中使用Zustand进行状态管理详解
3R编码 | Next.js核心概念及应用构建
微电子学第1话 MOS Differential Pair (I)
微电子学第1话 MOS Differential Pair (I)
微电子学第3话 CMRR
微电子学第2话 MOS Differential Pair (II)
终于有人讲了,凭什么三极管能放大?
降低人类负担:类型系统即边界
固态变压器SST是什么
本站点使用 MrDoc 构建
-
+
3R编码 | 用户模块开发以及使用Passport实现JWT认证和无痛刷新
### 提前学习[](#提前学习 "提前学习的直接链接") 请在学习本课程之前最好先学习这些知识 - [JSON Web Token 入门教程](https://www.ruanyifeng.com/blog/2018/07/json_web_token-tutorial.html) - [laravel jwt无痛刷新](https://learnku.com/articles/7264/using-jwt-auth-to-implement-api-user-authentication-and-painless-refresh-access-token)(原symfony无痛刷新这边写得很好,在思否上找不到了,随便找了一篇差不多的可以看一下) - [nestjs与passport整合的官方文档](https://docs.nestjs.com/recipes/passport) ### 文件结构[](#文件结构 "文件结构的直接链接") 本节课主要新增了用户模块的文件 ``` ./src├── assets├── config│ ├── #...│ └── user.config.ts├── console├── database│ ├── factories│ │ ├── content.data.ts│ │ ├── content.factory.ts│ │ └── user.factory.ts│ ├── migrations│ │ ├── 1706571795562-EKYJug.ts│ │ └── 1706643367986-TpXOwV.ts│ └── seeders│ ├── content.seeder.ts│ └── user.seeder.ts├── main.ts├── metadata.ts├── modules│ ├── config│ ├── content│ ├── core│ ├── database│ ├── meilisearch│ ├── restful│ └── user│ ├── config.ts│ ├── constants.ts│ ├── controllers│ │ ├── account.controller.ts│ │ ├── index.ts│ │ └── user.controller.ts│ ├── decorators│ │ ├── guest.decorator.ts│ │ ├── index.ts│ │ └── user-request.decorator.ts│ ├── dtos│ │ ├── account.dto.ts│ │ ├── auth.dto.ts│ │ ├── common.dto.ts│ │ ├── index.ts│ │ └── user.dto.ts│ ├── entities│ │ ├── access-token.entity.ts│ │ ├── base.token.ts│ │ ├── index.ts│ │ ├── refresh-token.entity.ts│ │ └── user.entity.ts│ ├── guards│ │ ├── index.ts│ │ ├── jwt-auth.guard.ts│ │ └── local-auth.guard.ts│ ├── helpers.ts│ ├── repositories│ │ ├── index.ts│ │ └── user.repository.ts│ ├── routes.ts│ ├── services│ │ ├── auth.service.ts│ │ ├── index.ts│ │ ├── token.service.ts│ │ └── user.service.ts│ ├── strategies│ │ ├── index.ts│ │ ├── jwt.strategy.ts│ │ └── local.strategy.ts│ ├── subscribers│ │ ├── index.ts│ │ └── user.subscriber.ts│ ├── types.ts│ ├── user.interceptor.ts│ └── user.module.ts ``` ### 依赖解析[](#依赖解析 "依赖解析的直接链接") - bcrypt: 用于加密密码和密码检测 - passport: 最流行的node.js的auth库 - @nestjs/passport: nest整合passport的模块 - passport-local: passport的本地策略,用于对用户通过账户名密码登录进行验证 - jsonwebtoken: 用于生成jwt token - passport-jwt: passport的Jwt策略,用于对已登录用户的token进行验证 - @nestjs/jwt: passport-jwt与nestjs的整合包 - uuid用于生成一个uuid字符串 ``` pnpm add bcrypt @nestjs/jwt @nestjs/passport passport passport-jwt passport-local jsonwebtoken uuid pnpm add @types/bcrypt @types/passport-jwt @types/uuid @types/jsonwebtoken @types/passport-local -D ``` ### 运行流程[](#运行流程 "运行流程的直接链接") 这张流程图即为本节课的用户登录与注册流程,请仔细查看并理解  经过了前面几节课的改造之后,目前我们开发模块的流程大致为 1. 编写模块配置(包括默认配置,配置生成器和自定义配置) 2. 编写模型(Entity) 3. 编写存储类(Repository) 4. 数据操作订阅者(Subscriber) 5. 数据验证类(DTO) 6. 服务类(Service) 7. 控制器(Controller) 8. 模块(module.ts文件) 可能还有其他的一些特殊的代码,比如守卫、装饰器等,接下来我们按这个流程编写一下用户模块 ### 配置与函数[](#配置与函数 "配置与函数的直接链接") 首先,构建用户模块的配置 #### 类型[](#类型 "类型的直接链接") 用户配置类型 - hash: 对密码进行混淆时的hash数量值 - jwt: jwt token的生成配置 ``` // src/modules/user/types.tsexport interface UserConfig { hash: number; jwt: JwtConfig;} ``` JWT配置类型 - `token_expired`: token过期时间 - `refresh_token_expired`: refresh token ``` // src/modules/user/types.tsexport interface JwtConfig { token_expired: number; refresh_token_expired: number;} ``` JWT荷载签出对象 - `sub`: 用户ID - `iat`: 签出时间 ``` // src/modules/user/types.tsexport interface JwtPayload { sub: string; iat: number;} ``` #### 默认配置[](#默认配置 "默认配置的直接链接") 信息 后续我们可以做个安装应用命令,用于自动生成`secrect` ``` // src/modules/user/config.ts/** * 默认用户配置 */export const defaultUserConfig = (configure: Configure): UserConfig => { return { hash: 10, jwt: { token_expired: configure.env.get('USER_TOKEN_EXPIRED', (v) => toNumber(v), 3600), refresh_token_expired: configure.env.get( 'USER_REFRESH_TOKEN_EXPIRED', (v) => toNumber(v), 3600 * 30, ), }, };}; ``` #### 配置创建[](#配置创建 "配置创建的直接链接") 与内容模块一样,编写一个配置构建器用于构建自定义配置 ``` // src/modules/user/config.ts/** * 用户配置创建函数 * @param register */export const createUserConfig: ( register: ConfigureRegister<RePartial<UserConfig>>,) => ConfigureFactory<UserConfig> = (register) => ({ register, defaultRegister: defaultUserConfig,}); ``` #### 获取配置[](#获取配置 "获取配置的直接链接") 此函数用于快速的获取一个用户模块的配置 ``` // src/modules/user/config.ts/** * 获取user模块配置的值 * @param configure * @param key */export async function getUserConfig<T>(configure: Configure, key?: string): Promise<T> { const userConfig = await configure.get<UserConfig>('user', defaultUserConfig(configure)); if (isNil(key)) return userConfig as T; return get(userConfig, key) as T;} ``` #### 自定义配置[](#自定义配置 "自定义配置的直接链接") ``` // src/config/user.config.tsexport const user = createUserConfig(() => ({})); ``` #### 密码加密和对比[](#密码加密和对比 "密码加密和对比的直接链接") 用户密码一般不会使用明文直接存储在数据库中,这样非常不安全,所以此处我们选择使用**bcrypt**对密码进行加密后存储 这里的`hash`是密码混淆值,默认为`10`位,我们可以在用户配置中进行自定义位数。 ``` // src/modules/user/helpers.ts/** * 加密明文密码 * @param configure * @param password */export const encrypt = async (configure: Configure, password: string) => { const hash = (await getUserConfig<number>(configure, 'hash')) || 10; return bcrypt.hashSync(password, hash);};/** * 验证密码 * @param password * @param hashed */export const decrypt = (password: string, hashed: string) => { return bcrypt.compareSync(password, hashed);}; ``` ### 模型[](#模型 "模型的直接链接") 用户模块的模型分为两部分 - 用户模型:对应用户表(后续我们可以细化,比如拆分用户表和用户信息表等) - JWT Token模型:有两个表组成,用于用户访问的access\_token,这个token返回给前端;用于无痛刷新的token,用于延长登录时间 #### 用户模型[](#用户模型 "用户模型的直接链接") ``` // src/modules/user/entities/user.entity.ts/** * 用户模型 */@Exclude()@Entity('users')export class UserEntity { @Expose() @PrimaryColumn({ type: 'varchar', generated: 'uuid', length: 36 }) id: string; @Expose() @Column({ comment: '姓名', nullable: true, }) nickname?: string; @Expose() @Column({ comment: '用户名', unique: true }) username: string; @Column({ comment: '密码', length: 500, select: false }) password: string; @Expose() @Column({ comment: '手机号', nullable: true, unique: true }) phone?: string; @Expose() @Column({ comment: '邮箱', nullable: true, unique: true }) email?: string; @Expose() @Type(() => Date) @CreateDateColumn({ comment: '用户创建时间', }) createdAt: Date; @Expose() @Type(() => Date) @UpdateDateColumn({ comment: '用户更新时间', }) updatedAt: Date; @Expose() @Type(() => Date) @DeleteDateColumn({ comment: '删除时间', }) deletedAt: Date;} ``` 添加关联与反向关联关系:用户与文章一对多(一个用户可以发布多篇文章)、用户与评论一对多(一个用户可以发表多条评论) ``` // src/modules/user/entities/user.entity.ts@Exclude()@Entity('users')export class UserEntity { // ... @OneToMany(() => PostEntity, (post) => post.author, { cascade: true, }) posts: Relation<PostEntity>[]; @OneToMany(() => CommentEntity, (comment) => comment.author, { cascade: true, }) comments: Relation<CommentEntity>[];}// src/modules/content/entities/post.entity.ts@Exclude()@Entity('content_posts')export class PostEntity extends BaseEntity { // ... @Expose() @ManyToOne(() => UserEntity, (user) => user.posts, { nullable: false, onDelete: 'CASCADE', onUpdate: 'CASCADE', }) author: Relation<UserEntity>;}// src/modules/content/entities/comment.entity.ts@Exclude()@Tree('materialized-path')@Entity('content_comments')export class CommentEntity extends BaseEntity { // ... @Expose() @ManyToOne((type) => UserEntity, (user) => user.comments, { nullable: false, onDelete: 'CASCADE', onUpdate: 'CASCADE', }) author: Relation<UserEntity>;} ``` #### Token模型[](#token模型 "Token模型的直接链接") 公共字段:token与refresh\_token有一些都有的通用字段,我们可以把它们抽象出来 ``` // src/modules/user/entities/base.token.ts/** * AccessToken与RefreshToken的公共字段 */@Exclude()export abstract class BaseToken extends BaseEntity { @PrimaryColumn({ type: 'varchar', generated: 'uuid', length: 36 }) id: string; @Column({ length: 500, comment: '令牌字符串' }) value: string; @Column({ comment: '令牌过期时间', }) expired_at: Date; @CreateDateColumn({ comment: '令牌创建时间', }) createdAt: Date;} ``` 访问密钥:访问密钥与刷新密钥是一对一的关系,一个访问密钥必然带有一个刷新密钥 ``` // src/modules/user/entities/access-token.entity.ts/** * 用户认证token模型 */@Entity('user_access_tokens')export class AccessTokenEntity extends BaseToken { /** * 关联的刷新令牌 */ @OneToOne(() => RefreshTokenEntity, (refreshToken) => refreshToken.accessToken, { cascade: true, }) refreshToken: RefreshTokenEntity;} ``` 无痛刷新密钥与访问密钥反向关联 ``` // src/modules/user/entities/refresh-token.entity.ts/** * 刷新Token的Token模型 */@Entity('user_refresh_tokens')export class RefreshTokenEntity extends BaseToken { /** * 关联的登录令牌 */ @OneToOne(() => AccessTokenEntity, (accessToken) => accessToken.refreshToken, { onDelete: 'CASCADE', }) @JoinColumn() accessToken: Relation<AccessTokenEntity>;} ``` 添加与用户模型的关联关系:一个用户可能使用不同的设备登录,所以用户与访问密钥间是一对多的关系 ``` // src/modules/user/entities/access-token.entity.ts@Entity('user_access_tokens')export class AccessTokenEntity extends BaseToken { // ... @ManyToOne((type) => UserEntity, (user) => user.accessTokens, { onDelete: 'CASCADE', }) user: Relation<UserEntity>;}// src/modules/user/entities/user.entity.ts@Exclude()@Entity('users')export class UserEntity { // ... @OneToMany(() => AccessTokenEntity, (accessToken) => accessToken.user, { cascade: true, }) accessTokens: Relation<AccessTokenEntity>[];} ``` ### 存储类[](#存储类 "存储类的直接链接") 查询用户名时默认简单地安装创建时间排序即可 ``` // src/modules/user/repositories/user.repository.ts@CustomRepository(UserEntity)export class UserRepository extends BaseRepository<UserEntity> { protected _qbName = 'user'; buildBaseQuery() { return this.createQueryBuilder(this.qbName).orderBy(`${this.qbName}.createdAt`, 'DESC'); }} ``` ### 订阅者[](#订阅者 "订阅者的直接链接") `beforeInsert`做以下处理 警告 这部分内容用于后续课程,比如使用邮箱或短信来注册用户时自动生成用户名及密码,本节课不需要这个功能,因为本节课的用户注册和用户添加的DTO数据验证中我们的要求为必须手动设置用户名和密码 1. 在插入数据之前先判断用户有无设置用户名,如没有设置,则使用`generateUserName`方法生成一个随机用户名 2. 为了保证用户名的唯一性,`generateUserName`会检测随机生成的用户名是否已经被占用,如果占用在递归生成一个新的,直到生成出来的用户名没有被占用为止 3. 在插入数据之前先判断用户有无设置密码,如没有设置,则生成一个随机密码 4. 在插入数据库之前使用`encrypt`函数对密码进行加密 `beforeUpdate`目前用于在用户更新密码时,对新密码使用`encrypt`函数加密 ``` // src/modules/user/subscribers/user.subscriber.ts@EventSubscriber()export class UserSubscriber extends BaseSubscriber<UserEntity> { protected entity = UserEntity; protected async generateUserName(event: InsertEvent<UserEntity>): Promise<string> { const username = `user_${randomBytes(4).toString('hex').slice(0, 8)}`; const user = await event.manager.findOne(UserEntity, { where: { username }, }); return !user ? username : this.generateUserName(event); } async beforeInsert(event: InsertEvent<UserEntity>) { // 自动生成唯一用户名 if (!event.entity.username) { event.entity.username = await this.generateUserName(event); } // 自动生成密码 if (!event.entity.password) { event.entity.password = randomBytes(11).toString('hex').slice(0, 22); } // 自动加密密码 event.entity.password = await encrypt(this.configure, event.entity.password); } async beforeUpdate(event: UpdateEvent<UserEntity>) { if (this.isUpdated('password', event)) { event.entity.password = encrypt(this.configure, event.entity.password); } }} ``` ### 数据验证[](#数据验证 "数据验证的直接链接") 因为用户模块后续会涉及到非常多的功能,比如找回密码,OAuth登录,邮箱或短信验证的注册登录等,这样就需要写非常多的重复性的字段验证,使得代码大量冗余。于是,我们可以把重复性的验证字段抽象出来,并使用不同的分组来实现不同的DTO类中同一个字段的不同验证组 #### 验证组枚举[](#验证组枚举 "验证组枚举的直接链接") 暂时我们只需要3个验证组 - `user-create`: 创建用户验证(在后续权限模块的课程后,此验证组只用于管理员对用户的CRUD操作) - `user-update`: 更新用户验证(在后续权限模块的课程后,此验证组只用于管理员对用户的CRUD操作) - `user-register`: 用户注册验证 - `user-account-update`: 用户账户信息更新验证 - `user-change-password`: 用户密码更新验证 ``` // src/modules/user/constants.ts/** * 用户请求DTO验证组 */export enum UserValidateGroups { USER_CREATE = 'user-create', USER_UPDATE = 'user-update', USER_REGISTER = 'user-register', ACCOUNT_UPDATE = 'account-update', CHANGE_PASSWORD = 'change-password',} ``` #### 排序规则[](#排序规则 "排序规则的直接链接") 添加用户查询排序,目前只需要简单地根据创建时间或更新时间排序即可 ``` // src/modules/user/constants.tsexport enum UserOrderType { CREATED = 'createdAt', UPDATED = 'updatedAt',} ``` #### 公共验证字段[](#公共验证字段 "公共验证字段的直接链接") 备注 篇幅有限,下面这些字段的验证规则及验证组请自行查看。非常简单,不再赘述 提示 由于手机号和邮箱此处还没用到,会在后续课程讲解,所以只做新增用户时的唯一性验证即可 ``` // src/modules/user/dtos/common.dto.ts/** * 用户模块DTO的通用基础字段 */@Injectable()export class UserCommonDto { /** * 登录凭证:可以是用户名,手机号,邮箱地址 */ @Length(4, 30, { message: '登录凭证长度必须为$constraint1到$constraint2', always: true, }) @IsNotEmpty({ message: '登录凭证不得为空', always: true }) credential: string; /** * 用户名 */ @IsUnique( { entity: UserEntity }, { groups: [UserValidateGroups.USER_CREATE, UserValidateGroups.USER_REGISTER], message: '该用户名已被注册', }, ) @IsUniqueExist( { entity: UserEntity, ignore: 'id' }, { groups: [UserValidateGroups.USER_UPDATE], message: '该用户名已被注册', }, ) @IsUniqueExist( { entity: UserEntity, ignore: 'id', ignoreKey: 'userId' }, { groups: [UserValidateGroups.ACCOUNT_UPDATE], message: '该用户名已被注册', }, ) @Length(4, 30, { always: true, message: '用户名长度必须为$constraint1到$constraint2', }) @IsOptional({ groups: [UserValidateGroups.USER_UPDATE, UserValidateGroups.ACCOUNT_UPDATE], }) username: string; /** * 昵称:不设置则为用户名 */ @Length(3, 20, { always: true, message: '昵称必须为$constraint1到$constraint2', }) @IsOptional({ always: true }) nickname?: string; /** * 手机号:必须是区域开头的,比如+86.15005255555 */ @IsUnique( { entity: UserEntity }, { message: '手机号已被注册', groups: [UserValidateGroups.USER_CREATE, UserValidateGroups.USER_REGISTER], }, ) @IsMatchPhone( undefined, { strictMode: true }, { message: '手机格式错误,示例: +86.15005255555', always: true, }, ) @IsOptional({ groups: [ UserValidateGroups.USER_CREATE, UserValidateGroups.USER_UPDATE, UserValidateGroups.USER_REGISTER, ], }) phone: string; /** * 邮箱地址:必须符合邮箱地址规则 */ @IsUnique( { entity: UserEntity }, { message: '邮箱已被注册', groups: [UserValidateGroups.USER_CREATE, UserValidateGroups.USER_REGISTER], }, ) @IsEmail(undefined, { message: '邮箱地址格式错误', always: true, }) @IsOptional({ groups: [ UserValidateGroups.USER_CREATE, UserValidateGroups.USER_UPDATE, UserValidateGroups.USER_REGISTER, ], }) email: string; /** * 用户密码:密码必须由小写字母,大写字母,数字以及特殊字符组成 */ @IsPassword(5, { message: '密码必须由小写字母,大写字母,数字以及特殊字符组成', always: true, }) @Length(8, 50, { message: '密码长度不得少于$constraint1', always: true, }) @IsMatch('oldPassword', true, { message: '新密码与旧密码不得相同', groups: [UserValidateGroups.CHANGE_PASSWORD], }) @IsOptional({ groups: [UserValidateGroups.USER_UPDATE] }) password: string; /** * 确认密码:必须与用户密码输入相同的字符串 */ @IsMatch('password', false, { message: '两次输入密码不同', always: true }) @IsNotEmpty({ message: '请再次输入密码以确认', always: true }) plainPassword: string;} ``` #### CRUD验证[](#crud验证 "CRUD验证的直接链接") 备注 篇幅有限,下面这些字段的验证规则及验证组请自行查看。非常简单,不再赘述 ``` // src/modules/user/dtos/user.dto.ts/** * 创建用的请求数据验证 */@DtoValidation({ groups: [UserValidateGroups.USER_CREATE] })export class CreateUserDto extends PickType(UserCommonDto, [ 'username', 'nickname', 'password', 'phone', 'email',]) {}/** * 更新用户 */@DtoValidation({ groups: [UserValidateGroups.USER_UPDATE] })export class UpdateUserDto extends PartialType(CreateUserDto) { /** * 待更新的用户ID */ @IsUUID(undefined, { groups: [UserValidateGroups.USER_UPDATE], message: '用户ID格式不正确' }) @IsDefined({ groups: ['update'], message: '用户ID必须指定' }) id: string;}/** * 查询用户列表的Query数据验证 */@DtoValidation({ type: 'query' })export class QueryUserDto extends PaginateWithTrashedDto { /** * 排序规则:可指定用户列表的排序规则,默认为按创建时间降序排序 */ @IsEnum(UserOrderType) orderBy?: UserOrderType;} ``` #### 注册登录验证[](#注册登录验证 "注册登录验证的直接链接") 备注 篇幅有限,下面这些字段的验证规则及验证组请自行查看。非常简单,不再赘述 ``` // src/modules/user/dtos/auth.dto.ts/** * 用户正常方式登录 */export class CredentialDto extends PickType(UserCommonDto, ['credential', 'password']) {}/** * 普通方式注册用户 */@DtoValidation({ groups: [UserValidateGroups.USER_REGISTER] })export class RegisterDto extends PickType(UserCommonDto, [ 'username', 'nickname', 'password', 'plainPassword',] as const) {} ``` #### 账户操作验证[](#账户操作验证 "账户操作验证的直接链接") 备注 篇幅有限,下面这些字段的验证规则及验证组请自行查看。非常简单,不再赘述 ``` // src/modules/user/dtos/account.dto.ts/** * 更新用户信息 */@DtoValidation({ groups: [UserValidateGroups.ACCOUNT_UPDATE], whitelist: false,})export class UpdateAccountDto extends PickType(UserCommonDto, ['username', 'nickname']) {}/** * 更改用户密码 */@DtoValidation({ groups: [UserValidateGroups.CHANGE_PASSWORD],})export class UpdatePasswordDto extends PickType(UserCommonDto, ['password', 'plainPassword']) { /** * 旧密码:用户在更改密码时需要输入的原密码 */ @IsPassword(5, { message: '密码必须由小写字母,大写字母,数字以及特殊字符组成', always: true, }) @Length(8, 50, { message: '密码长度不得少于$constraint1', always: true, }) oldPassword: string;} ``` ### 服务类[](#服务类 "服务类的直接链接") 服务类目前需要编写三个,分别用于操作密钥,操作账户以及用户管理 #### Token操作[](#token操作 "Token操作的直接链接") `generateAccessToken` 该方法用于在用户登录后签出新的访问密钥,其流程为 1. 获取用户模块的jwt配置 2. 设置荷载对象:用户id作为`sub`,当前时间作为`iat`(当然你也可以添加更多的信息进去) 3. 使用`jwtService`签出一个token 4. 把签出的token:包括token值,关联的用户以及过期时间(当前签出时间加上自定义设置的有效时间)存储到`user_access_tokens`表中 5. 最后使用`generateRefreshToken`生成一个关联的刷新token并保存到数据库 `generateRefreshToken` 生成RefreshToken并存入数据库 1. 获取用户模块的jwt配置 2. 设置荷载对象:使用`uuid`生成一个随机的id即可 3. 使用`jwt`(`jwtService`也是基于`jwt`对象来签出访问token的,只不过`jwtService`是个单例注入的服务,所以再使用它签出accessToken后不能再用它签出refreshToken,那就使用原生的`jwt`来签出) 4. 设置关联的accessToken并保存到`user_refresh_tokens`表中 `refreshToken` 该方法用于刷新token 1. 通过传入的accessToken获取其关联的refreshToken和user对象 2. 如果不存在关联的refreshToken则返回`null`,也就是无法签出新的accessToken 3. 如果存在供刷新使用的refreshToken,则先获取当前时间 4. 然后对比refreshToken的过期时间,如果refreshToken也过期了,则直接返回`null` 5. 如果refreshToken没过期,则先生成一个新的accessToken,然后把旧的删除掉 6. 接下来把新的accessToken放入响应的`response`里面,方便客户端存储新的accessToken 7. 最后返回新的accessToken `removeAccessToken`与`removeRefreshToken`用于删除访问和刷新token,在删除刷新token时同时删除其关联的访问token `checkAccessToken`用于查询token是否存在,如存在,则返回其数据模型的对象 `verifyAccessToken`用于验证accessToken或refreshToken是否正确 ``` // src/modules/user/services/token.service.ts/** * 令牌服务 */@Injectable()export class TokenService { constructor( protected configure: Configure, protected jwtService: JwtService, ) {} /** * 根据accessToken刷新AccessToken与RefreshToken * @param accessToken * @param response */ async refreshToken(accessToken: AccessTokenEntity, response: Response) { const { user, refreshToken } = accessToken; if (refreshToken) { const now = await getTime(this.configure); // 判断refreshToken是否过期 if (now.isAfter(refreshToken.expired_at)) return null; // 如果没过期则生成新的access_token和refresh_token const token = await this.generateAccessToken(user, now); await accessToken.remove(); response.header('token', token.accessToken.value); return token; } return null; } /** * 根据荷载签出新的AccessToken并存入数据库 * 且自动生成新的Refresh也存入数据库 * @param user * @param now */ async generateAccessToken(user: UserEntity, now: dayjs.Dayjs) { const config = await getUserConfig<JwtConfig>(this.configure, 'jwt'); const accessTokenPayload: JwtPayload = { sub: user.id, iat: now.unix(), }; const signed = this.jwtService.sign(accessTokenPayload); const accessToken = new AccessTokenEntity(); accessToken.value = signed; accessToken.user = user; accessToken.expired_at = now.add(config.token_expired, 'second').toDate(); await accessToken.save(); const refreshToken = await this.generateRefreshToken( accessToken, await getTime(this.configure), ); return { accessToken, refreshToken }; } /** * 生成新的RefreshToken并存入数据库 * @param accessToken * @param now */ async generateRefreshToken( accessToken: AccessTokenEntity, now: dayjs.Dayjs, ): Promise<RefreshTokenEntity> { const config = await getUserConfig<JwtConfig>(this.configure, 'jwt'); const refreshTokenPayload = { uuid: uuid(), }; const refreshToken = new RefreshTokenEntity(); refreshToken.value = jwt.sign( refreshTokenPayload, this.configure.env.get('USER_REFRESH_TOKEN_SECRET', 'my-refresh-secret'), ); refreshToken.expired_at = now.add(config.refresh_token_expired, 'second').toDate(); refreshToken.accessToken = accessToken; await refreshToken.save(); return refreshToken; } /** * 检查accessToken是否存在 * @param value */ async checkAccessToken(value: string) { return AccessTokenEntity.findOne({ where: { value }, relations: ['user', 'refreshToken'], }); } /** * 移除AccessToken且自动移除关联的RefreshToken * @param value */ async removeAccessToken(value: string) { const accessToken = await AccessTokenEntity.findOne({ where: { value }, }); if (accessToken) await accessToken.remove(); } /** * 移除RefreshToken * @param value */ async removeRefreshToken(value: string) { const refreshToken = await RefreshTokenEntity.findOne({ where: { value }, relations: ['accessToken'], }); if (refreshToken) { if (refreshToken.accessToken) await refreshToken.accessToken.remove(); await refreshToken.remove(); } } /** * 验证Token是否正确,如果正确则返回所属用户对象 * @param token */ async verifyAccessToken(token: AccessTokenEntity) { const result = jwt.verify( token.value, this.configure.env.get('USER_TOKEN_SECRET', 'my-access-secret'), ); if (!result) return false; return token.user; }} ``` #### 账户操作[](#账户操作 "账户操作的直接链接") 该服务主要用于用户的注册、登录等功能 `validateUser` 信息 之所以没有直接使用`username`而使用`credential`(凭证)是因为我们同时需要开启手机号+密码、邮箱地址+密码等方式来登录 该方法用于验证使用用户名及密码登录的用户是否正确。需要注意的是:在查询用户时带上`addSelect`,因为`UserEntity`中默认把`password`设置为不可查询了 `login` 在验证凭证和密码正确后,签出一个新的accessToken和refreshToken给客户端,使用户登录成功即可 `logout` 注销登录的逻辑是从请求中拿到用户的accessToken并从数据库中删除(关联的refreshToken也会自动删除) `createToken` 该方法为已登录的用户手动签出一个新的accessToken和refreshToken `register`方法用于注册用户 `updatePassword` 该方法用于用户修改密码(并不是找回密码,找回密码后续我们会在邮件与短信模块里编写)。在修改密码时必须要填入正确的旧密码! `jwtModuleFactory` 该方法是一个用于注册`@nestjs/jwt`模块的静态方法,如果在非生产环境下忽略过期时间(貌似放在`TokenService`里面更合理?) ``` // src/modules/user/services/auth.service.ts/** * 账户与认证服务 */@Injectable()export class AuthService { constructor( protected configure: Configure, protected userService: UserService, protected tokenService: TokenService, protected userRepository: UserRepository, ) {} /** * 用户登录验证 * @param credential * @param password */ async validateUser(credential: string, password: string) { const user = await this.userService.findOneByCredential(credential, async (query) => query.addSelect('user.password'), ); if (user && decrypt(password, user.password)) { return user; } return false; } /** * 登录用户,并生成新的token和refreshToken * @param user */ async login(user: UserEntity) { const now = await getTime(this.configure); const { accessToken } = await this.tokenService.generateAccessToken(user, now); return accessToken.value; } /** * 注销登录 * @param req */ async logout(req: Request) { const accessToken = ExtractJwt.fromAuthHeaderAsBearerToken()(req as any); if (accessToken) { await this.tokenService.removeAccessToken(accessToken); } return { msg: 'logout_success', }; } /** * 登录用户后生成新的token和refreshToken * @param id */ async createToken(id: string) { const now = await getTime(this.configure); let user: UserEntity; try { user = await this.userService.detail(id); } catch (error) { throw new ForbiddenException(); } const { accessToken } = await this.tokenService.generateAccessToken(user, now); return accessToken.value; } /** * 使用用户名密码注册用户 * @param data */ async register(data: RegisterDto) { const { username, nickname, password } = data; const user = await this.userService.create({ username, nickname, password, actived: true, } as any); return this.userService.findOneByCondition({ id: user.id }); } /** * 更新用户密码 * @param user * @param param1 */ async updatePassword(user: UserEntity, { password, oldPassword }: UpdatePasswordDto) { const item = await this.userRepository.findOneOrFail({ select: ['password'], where: { id: user.id }, }); if (!decrypt(oldPassword, item.password)) throw new ForbiddenException('old password not matched'); await this.userRepository.save({ id: user.id, password }, { reload: true }); return this.userService.detail(user.id); } /** * 导入Jwt模块 */ static jwtModuleFactory(configure: Configure) { return JwtModule.registerAsync({ useFactory: async (): Promise<JwtModuleOptions> => { const config = await configure.get<UserConfig>( 'user', defaultUserConfig(configure), ); const option: JwtModuleOptions = { secret: configure.env.get('USER_TOKEN_SECRET', 'my-access-secret'), verifyOptions: { ignoreExpiration: !configure.env.isProd(), }, }; if (configure.env.isProd()) { option.signOptions = { expiresIn: `${config.jwt.token_expired}s` }; } return option; }, }); }} ``` #### 用户管理[](#用户管理 "用户管理的直接链接") 用户管理服务即管理员对用户的CRUD操作 信息 后续我们完成RBAC权限课程后,这个服务类主要用于超级管理员管理用户 `create`、`update`、`buildListQB`非常简单,不再赘述 `findOneByCredential` 该方法通过凭证查询出一个用户,凭证可以是用户名,邮箱地址,手机号(也可以自行添加其它的) `findOneByCondition` 该方法通过任意条件查询出一个用户,重点在于`Object.fromEntries`和`Object.entries`语法的灵活使用,请自行谷歌研究一下 ``` // src/modules/user/services/user.service.ts/** * 用户管理服务 */@Injectable()export class UserService extends BaseService<UserEntity, UserRepository> { protected enable_trash = true; constructor( protected configure: Configure, protected dataSource: DataSource, protected userRepository: UserRepository, ) { super(userRepository); } /** * 创建用户 * @param data */ async create(data: CreateUserDto) { const user = await this.userRepository.save(data, { reload: true }); return this.detail(user.id); } /** * 更新用户 * @param data */ async update(data: UpdateUserDto) { const updated = await this.userRepository.save(data, { reload: true }); const user = await this.detail(updated.id); return this.detail(user.id); } /** * 根据用户用户凭证查询用户 * @param credential * @param callback */ async findOneByCredential(credential: string, callback?: QueryHook<UserEntity>) { let query = this.userRepository.buildBaseQB(); if (callback) { query = await callback(query); } return query .where('user.username = :credential', { credential }) .orWhere('user.email = :credential', { credential }) .orWhere('user.phone = :credential', { credential }) .getOne(); } /** * 根据对象条件查找用户,不存在则抛出异常 * @param condition * @param callback */ async findOneByCondition(condition: { [key: string]: any }, callback?: QueryHook<UserEntity>) { let query = this.userRepository.buildBaseQB(); if (callback) { query = await callback(query); } const wheres = Object.fromEntries( Object.entries(condition).map(([key, value]) => [key, value]), ); const user = query.where(wheres).getOne(); if (!user) { throw new EntityNotFoundError(UserEntity, Object.keys(condition).join(',')); } return user; } protected async buildListQB( queryBuilder: SelectQueryBuilder<UserEntity>, options: QueryUserDto, callback?: QueryHook<UserEntity>, ) { const { orderBy } = options; const qb = await super.buildListQB(queryBuilder, options, callback); if (isNil(orderBy)) qb.orderBy(`${this.repository.qbName}.${orderBy}`, 'ASC'); return qb; }} ``` ### 本地策略[](#本地策略 "本地策略的直接链接") 策略是配合守卫使用的,本地策略用于通过凭证+密码的方式登录用户 #### 策略类[](#策略类 "策略类的直接链接") 默认的本地策略是`passport-local`包中的`Strategy`,我们需要用`PassportStrategy`它以整合Nestjs,并在此基础上扩展出自己的本地策略,然后进行自定义 - 在构造方法中把请求中的验证字段设置为`credential` - 使用`AuthService`的`validateUser`方法对用户凭证与密码进行验证 ``` // src/modules/user/strategies/local.strategy.ts/** * 用户认证本地策略 */@Injectable()export class LocalStrategy extends PassportStrategy(Strategy) { constructor(protected authService: AuthService) { super({ usernameField: 'credential', passwordField: 'password', }); } async validate(credential: string, password: string): Promise<any> { const user = await this.authService.validateUser(credential, password); if (!user) { throw new UnauthorizedException(); } return user; }} ``` #### 本地验证守卫[](#本地验证守卫 "本地验证守卫的直接链接") 有了本地策略后,在请求加了本地守卫 `AuthGuard('local')`的方法上都会使用本地策略类去进行验证。因为该守卫的`canActivate`方法会自动把请求数据传入本地策略类的实例并调用`validate`方法对用户凭证和密码进行验证。 为了准确的得到验证结果和更精准的返回错误信息,我们继承默认的本地守卫类并重载`canActivate`。使用`plainToClass(CredentialDto, request.body)`把请求数据赋值给`CredentialDto`的对象并一一对应字段,然后根据`CredentialDto`中的字段验证规则先验证请求数据中`credential`和`password`等字段的合法性,然后再使用本地策略进行数据准确验证 ``` // src/modules/user/guards/local-auth.guard.ts/** * 用户登录守卫 */@Injectable()export class LocalAuthGuard extends AuthGuard('local') { async canActivate(context: ExecutionContext) { const request = context.switchToHttp().getRequest(); try { await validateOrReject(plainToClass(CredentialDto, request.body), { validationError: { target: false }, }); } catch (errors) { const messages = (errors as any[]) .map((e) => e.constraints ?? {}) .reduce((o, n) => ({ ...o, ...n }), {}); throw new BadRequestException(Object.values(messages)); } return super.canActivate(context) as boolean; }} ``` ### JWT策略[](#jwt策略 "JWT策略的直接链接") JWT策略用于在访问一个端点API是检测用户是否已登录(即拥有存在数据库中,并和当前用户对应且未过期的有效accessToken)。 #### 策略类[](#策略类-1 "策略类的直接链接") 默认的JWT策略类使用`PassportStrategy`包装`passport-jwt`中的`Strategy`,我们扩展它并自定义一下 - 在构造函数中,我们传入自定义的验证密钥 - 在`validate`(与前面的本地策略一样,在本地守卫中自动执行)中使用从请求中拿到的accessToken中通过`secret`解构出的荷载的`sub`作为查询用户的ID ``` // src/modules/user/strategies/jwt.strategy.ts/** * 用户认证JWT策略 */@Injectable()export class JwtStrategy extends PassportStrategy(Strategy) { constructor( protected configure: Configure, protected userRepository: UserRepository, ) { const secret = configure.env.get('USER_TOKEN_SECRET', 'my-access-secret'); super({ jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(), ignoreExpiration: false, secretOrKey: secret, }); } /** * 通过荷载解析出用户ID * 通过用户ID查询出用户是否存在,并把id放入request方便后续操作 * @param payload */ async validate(payload: JwtPayload) { const user = await this.userRepository.findOneOrFail({ where: { id: payload.sub } }); return instanceToPlain(user); }} ``` #### 匿名端点装饰器[](#匿名端点装饰器 "匿名端点装饰器的直接链接") `Guest`装饰器用于装饰一些可不登录匿名访问的接口(控制器方法) 信息 后面我们会把下面的JWT添加到全局,默认所有接口都需要登录后访问,所以对于一些不需要登录即可访问的接口添加这个装饰器 ``` // src/modules/user/constants.tsexport const ALLOW_GUEST = 'allowGuest';// src/modules/user/decorators/guest.decorator.tsexport const Guest = () => SetMetadata(ALLOW_GUEST, true); ``` #### JWT守卫[](#jwt守卫 "JWT守卫的直接链接") JWT守卫继承自`AuthGuard('jwt')`,并在重载了`canActive`等方法 - 重载`handleRequest`,在无法通过JWT验证的情况下抛出**401**错误 - 重载`getRequest`,用于获取请求数据 - 重载`getResponse`,用于获取响应数据 - 重载`canActive`,用于自定义验证逻辑,其逻辑查看下面的代码注释 ``` // src/modules/user/guards/jwt-auth.guard.ts/** * 用户JWT认证守卫 * 检测用户是否已登录 */@Injectable()export class JwtAuthGuard extends AuthGuard('jwt') { constructor( protected reflector: Reflector, protected tokenService: TokenService, ) { super(); } /** * 守卫方法 * @param context */ async canActivate(context: ExecutionContext) { const allowGuest = this.reflector.getAllAndOverride<boolean>(ALLOW_GUEST, [ context.getHandler(), context.getClass(), ]); if (allowGuest) return true; const request = this.getRequest(context); const response = this.getResponse(context); // if (!request.headers.authorization) return false; // 从请求头中获取token // 如果请求头不含有authorization字段则认证失败 const requestToken = ExtractJwt.fromAuthHeaderAsBearerToken()(request); if (isNil(requestToken)) throw new UnauthorizedException(); // 判断token是否存在,如果不存在则认证失败 const accessToken = isNil(requestToken) ? undefined : await this.tokenService.checkAccessToken(requestToken!); if (isNil(accessToken)) throw new UnauthorizedException(); try { // 检测token是否为损坏或过期的无效状态,如果无效则尝试刷新token return (await super.canActivate(context)) as boolean; } catch (e) { // 尝试通过refreshToken刷新token // 刷新成功则给请求头更换新的token // 并给响应头添加新的token和refreshtoken const token = await this.tokenService.refreshToken(accessToken, response); if (isNil(token)) throw new UnauthorizedException(); if (token.accessToken) { request.headers.authorization = `Bearer ${token.accessToken.value}`; } // 刷新失败则再次抛出认证失败的异常 return (await super.canActivate(context)) as boolean; } } /** * 自动请求处理 * 如果请求中有错误则抛出错误 * 如果请求中没有用户信息则抛出401异常 * @param err * @param user * @param _info */ handleRequest(err: any, user: any, _info: Error) { if (err || isNil(user)) { if (isNil(user)) throw new UnauthorizedException(); throw err; } return user; } getRequest(context: ExecutionContext) { return context.switchToHttp().getRequest(); } getResponse(context: ExecutionContext) { return context.switchToHttp().getResponse(); }} ``` #### 全局守卫[](#全局守卫 "全局守卫的直接链接") 为了使所有API默认必须通过JWT守卫,也就是登录后才能访问(除了加了`@Guest`这个装饰器的),我们改造一下核心模块 在`createOptions`的`globals`中添加一个新的类型`guard`,该类型用于设置全局守卫 ``` // src/modules/core/types.tsexport interface CreateOptions { // ... globals?: { // ... /** * 全局守卫 */ guard?: Type<IAuthGuard>; };} ``` 然后修改一下`createBootModule`这个启动模块创建函数,为启动模块添加一个`APP_GUARD`的提供者用于设置全局守卫 ``` // src/modules/core/helpers/app.tsexport async function createBootModule( configure: Configure, options: Pick<CreateOptions, 'globals' | 'modules'>,): Promise<Type<any>> { // ... if (!isNil(globals.guard)) { providers.push({ provide: APP_GUARD, useClass: globals.guard, }); } return CreateModule('BootModule', () => { const meta: ModuleMetadata = { imports, providers, }; return meta; });} ``` 最后,我们在应用配置中设置全局守卫为`JwtAuthGuard` ``` // src/options.tsexport const createOptions: CreateOptions = { // ... globals: { guard: JwtAuthGuard, },}; ``` #### 当前用户装饰器[](#当前用户装饰器 "当前用户装饰器的直接链接") 这个装饰器用于从当前请求中获取当前用户对象(JWT策略类的`validate`方法解析出来的) ``` // src/modules/user/decorators/user-request.decorator.ts/** * 当前用户装饰器 * 通过request查询通过jwt解析出来的当前登录的ID查询当前用户模型实例 * 并用于控制器直接注入 */export const ReqUser = createParamDecorator(async (_data: unknown, ctx: ExecutionContext) => { const request = ctx.switchToHttp().getRequest(); return request.user as ClassToPlain<UserEntity>;}); ``` ### 拦截器[](#拦截器 "拦截器的直接链接") 当一个用户登录后,需要更新自己的账户用户名时,需要对用户名进行唯一性验证。但并不需要像后台管理那样在请求中传自己的id进行唯一性忽略,而是可以通过当前登录的token获取用户ID。然后把id赋值给`request.body.userId`,因为DTO可以拿到`body`,这就是我们的方案!但需要设置DTO为`whitelist: false`,因为`userId`不在DTO类的属性列表内,可以看到前面编写的`UpdateAccountDto`这个DTO。 要实现上面的方案,我们需要写个拦截器来实现 ``` // src/modules/user/user.interceptor.ts@Injectable()export class UserIdInterceptor implements NestInterceptor { intercept(context: ExecutionContext, next: CallHandler): Observable<any> { const request: any = context.switchToHttp().getRequest(); if (!isNil(request.user?.id)) { if (isNil(request.body)) request.body = { userId: request.user.id }; else request.body.userId = request.user.id; } return next.handle(); }} ``` 然后可以这样用 ``` @UseInterceptors(UserIdInterceptor) async update( @ReqUser() user: ClassToPlain<UserEntity>, @Body() data: UpdateAccountDto, ) { return this.userService.update({ id: user.id, ...pick(data, ['username', 'nickname']) }); } ``` ### 控制器[](#控制器 "控制器的直接链接") 控制器代码非常简单,请自行查看,但需要注意以下几点 - 对于允许匿名访问的API请加上`@Guest`装饰器 - 对于必须登录后访问的API请加上`@ApiBearerAuth`装饰器,如果整个控制器的所有方法都是必须登录后访问的,那么只需要在控制器顶部加上`@ApiBearerAuth`装饰器。这个装饰器的作用在于openapi(swagger)给API展示出一个必须登录后访问的锁 - 为`AuthController.login`方法添加上本地守卫`@UseGuards(LocalAuthGuard)` - `@ReqUser() user`用于获取当前用户 #### 用户管理[](#用户管理-1 "用户管理的直接链接") ``` // src/modules/user/controllers/user.controller.ts@ApiTags('用户管理')@Depends(UserModule)@Controller('users')export class UserController { constructor(protected service: UserService) {} /** * 用户列表 */ @Get() @Guest() @SerializeOptions({ groups: ['user-list'] }) async list() { return this.service.list(); } /** * 获取用户信息 * @param id */ @Get(':id') @Guest() @SerializeOptions({ groups: ['user-detail'] }) async detail( @Param('id', new ParseUUIDPipe()) id: string, ) { return this.service.detail(id); } /** * 新增用户 * @param data */ @Post() @ApiBearerAuth() @SerializeOptions({ groups: ['user-detail'] }) async store( @Body() data: CreateUserDto, ) { return this.service.create(data); } /** * 更新用户 * @param data */ @Patch() @ApiBearerAuth() @SerializeOptions({ groups: ['user-detail'] }) async update( @Body() data: UpdateUserDto, ) { return this.service.update(data); } /** * 批量删除用户 * @param data */ @Delete() @ApiBearerAuth() @SerializeOptions({ groups: ['user-list'] }) async delete( @Body() data: DeleteWithTrashDto, ) { const { ids, trash } = data; return this.service.delete(ids, trash); } /** * 批量恢复用户 * @param data */ @Patch('restore') @ApiBearerAuth() @SerializeOptions({ groups: ['user-list'] }) async restore( @Body() data: RestoreDto, ) { const { ids } = data; return this.service.restore(ids); }} ``` #### 账户操作[](#账户操作-1 "账户操作的直接链接") ``` // src/modules/user/controllers/account.controller.ts@ApiTags('账户操作')@Depends(UserModule)@Controller('account')export class AccountController { constructor( protected authService: AuthService, protected userService: UserService, ) {} /** * 使用用户名密码注册用户 * @param data */ @Post('register') @Guest() async register( @Body() data: RegisterDto, ) { return this.authService.register(data); } /** * 用户登录[凭证(可以是用户名,邮箱,手机号等)+密码登录] * @param user */ @Post('login') @Guest() @UseGuards(LocalAuthGuard) async login(@ReqUser() user: ClassToPlain<UserEntity>, @Body() _data: CredentialDto) { return { token: await this.authService.createToken(user.id) }; } /** * 注销登录 * @param req */ @Post('logout') @ApiBearerAuth() async logout(@Request() req: any) { return this.authService.logout(req); } /** * 获取账户信息[只有用户自己才能查询] * @param user */ @Get('profile') @ApiBearerAuth() @SerializeOptions({ groups: ['user-detail'], }) async profile(@ReqUser() user: ClassToPlain<UserEntity>) { return this.userService.detail(user.id); } /** * 更改账户信息 * @param user * @param data */ @Patch() @ApiBearerAuth() @SerializeOptions({ groups: ['user-detail'], }) @UseInterceptors(UserIdInterceptor) async update( @ReqUser() user: ClassToPlain<UserEntity>, @Body() data: UpdateAccountDto, ) { return this.userService.update({ id: user.id, ...pick(data, ['username', 'nickname']) }); } /** * 修改密码[必须知道原密码] * @param user * @param data */ @Patch('reset-passowrd') @ApiBearerAuth() @SerializeOptions({ groups: ['user-detail'], }) async resetPassword( @ReqUser() user: ClassToPlain<UserEntity>, @Body() data: UpdatePasswordDto, ) { return this.authService.updatePassword(user, data); }} ``` #### API路由[](#api路由 "API路由的直接链接") 为了更清晰的解耦(如果后续我们有需要可以自行在monorepo把每个模块单独发布到npm作为第三方模块),我们把路由API专门封装到一个函数内 目前路由前后台的操作不分离,都放在`app`即可,权限课程后我们会分开前后台的API ``` // src/modules/user/routes.tsimport * as controllers from './controllers';export const createUserApi = () => { const routes: Record<'app', RouteOption[]> = { app: [ { name: 'app.user', path: 'user', controllers: Object.values(controllers), }, ], }; const tags: Record<'app', (string | TagOption)[]> = { app: [ { name: '用户管理', description: '对用户进行CRUD操作' }, { name: '账户操作', description: '注册登录、查看修改账户信息、修改密码等' }, ], }; return { routes, tags };}; ``` 现在,我们可以通过函数快速获得用户模块的API(包括标签和路由),并放到我们的api配置中 ``` // src/config/api.config.tsexport const v1 = async (configure: Configure): Promise<VersionOption> => { const userApi = createUserApi(); return { routes: [ { name: 'app', path: '/', controllers: [], doc: { // title: '应用接口', description: '3R教室《Nestjs实战开发》课程应用的客户端接口(应用名称随机自动生成)', tags: [ { name: '分类操作', description: '对分类进行CRUD操作' }, { name: '标签操作', description: '对标签进行CRUD操作' }, { name: '文章操作', description: '对文章进行CRUD操作' }, { name: '评论操作', description: '对评论进行CRUD操作' }, ...userApi.tags.app, ], }, children: [ { name: 'content', path: 'content', controllers: Object.values(contentControllers), }, ...userApi.routes.app, ], }, ], };}; ``` ### 编写模块[](#编写模块 "编写模块的直接链接") #### 模块类[](#模块类 "模块类的直接链接") 除了服务,控制器,模型,存储类,订阅者等外,我们还需要导入`PassportModule`和 `services.AuthService.jwtModuleFactory(configure)`(就是`JwtModule`)两个模块,并且添加了策略,守卫两种新的提供者 ``` // src/modules/user/user.module.ts// ...import * as entities from './entities';import * as guards from './guards';import * as repositories from './repositories';import * as services from './services';import * as strategies from './strategies';import * as subscribers from './subscribers';import { UserIdInterceptor } from './user.interceptor';@Module({})export class UserModule { static async forRoot(configure: Configure) { return { module: UserModule, imports: [ PassportModule, PassportModule, services.AuthService.jwtModuleFactory(configure), addEntities(configure, Object.values(entities)), DatabaseModule.forRepository(Object.values(repositories)), ], providers: [ UserIdInterceptor, ...Object.values(services), ...(await addSubscribers(configure, Object.values(subscribers))), ...Object.values(strategies), ...Object.values(guards), ], exports: [ ...Object.values(services), DatabaseModule.forRepository(Object.values(repositories)), ], }; }} ``` #### 注册模块[](#注册模块 "注册模块的直接链接") 所有模块开发后都需要注册到启动模块才能使用 ``` // src/options.tsexport const createOptions: CreateOptions = { commands: () => [...Object.values(dbCommands)], config: { factories: configs as any, storage: { enabled: true } }, modules: async (configure) => [ DatabaseModule.forRoot(configure), MeilliModule.forRoot(configure), RestfulModule.forRoot(configure), UserModule.forRoot(configure), ContentModule.forRoot(configure), ], globals: { guard: JwtAuthGuard, }, // ...}; ``` #### 控制器依赖[](#控制器依赖 "控制器依赖的直接链接") 最后,别忘了给我们的控制器添加上`UserModule`依赖 ``` // src/modules/user/controllers@ApiTags('账户操作')@Depends(UserModule)@Controller('account')export class AccountController { // ...} ``` 编写完用户模块后,我们还需要修改一下内容模块,以使其与用户模块相关联 ### 存储类[](#存储类-1 "存储类的直接链接") 为`PostRepository`和`CommentRepository`添加上作者查询 信息 文章和评论与用户模型间的关联前面已经添加;树形评论不需要根据用户查询 ``` // src/modules/content/repositories/post.repository.ts@CustomRepository(PostEntity)export class PostRepository extends BaseRepository<PostEntity> { protected _qbName = 'post'; buildBaseQB() { // 在查询之前先查询出评论数量在添加到commentCount字段上 return this.createQueryBuilder(this.qbName) .leftJoinAndSelect(`${this.qbName}.author`, 'author') // ... }}// src/modules/content/repositories/comment.repository.ts@CustomRepository(CommentEntity)export class CommentRepository extends BaseTreeRepository<CommentEntity> { /** * 构建基础查询器 */ buildBaseQB(qb: SelectQueryBuilder<CommentEntity>): SelectQueryBuilder<CommentEntity> { return super .buildBaseQB(qb) .leftJoinAndSelect(`${this.qbName}.author`, 'author') .leftJoinAndSelect(`${this.qbName}.post`, 'post'); } // ...} ``` ### 数据验证[](#数据验证-1 "数据验证的直接链接") 添加上根据作者查询文章的数据验证 #### 文章[](#文章 "文章的直接链接") ``` /** * 文章分页查询验证 */@DtoValidation({ type: 'query' })export class QueryPostDto extends PaginateWithTrashedDto { // ... /** * 根据文章作者ID查询 */ @IsDataExist(UserEntity, { message: '指定的用户不存在', }) @IsUUID(undefined, { message: '用户ID格式错误' }) @IsOptional() author?: string;} ``` #### 评论[](#评论 "评论的直接链接") ``` /** * 评论分页查询验证 */@DtoValidation({ type: 'query' })export class QueryCommentDto extends PaginateDto { /** * 根据传入评论发布者的ID对评论进行过滤 */ @IsDataExist(UserEntity, { message: '所属的用户不存在', }) @IsUUID(undefined, { message: '用户ID格式错误' }) @IsOptional() author?: string; // ...} ``` ### 控制器[](#控制器-1 "控制器的直接链接") 为控制器添加上 `@ApiBearerAuth`,`@Guest`等装饰器,**由于篇幅所限,此处以分类管理控制器为例,其它控制器请自行查看代码** ``` // src/modules/content/controllers/category.controller.ts@ApiTags('分类操作')@Depends(ContentModule)@Controller('categories')export class CategoryController { constructor(protected service: CategoryService) {} /** * 查询分类树 */ @Get('tree') @Guest() @SerializeOptions({ groups: ['category-tree'] }) async tree() { return this.service.findTrees(); } /** * 分页查询分类列表 * @param options */ @Get() @Guest() @SerializeOptions({ groups: ['category-list'] }) async list( @Query() options: PaginateDto, ) { return this.service.paginate(options); } /** * 分页详解查询 * @param id */ @Get(':id') @Guest() @SerializeOptions({ groups: ['category-detail'] }) async detail( @Param('id', new ParseUUIDPipe()) id: string, ) { return this.service.detail(id); } /** * 新增分类 * @param data */ @Post() @ApiBearerAuth() @SerializeOptions({ groups: ['category-detail'] }) async store( @Body() data: CreateCategoryDto, ) { return this.service.create(data); } /** * 更新分类 * @param data */ @Patch() @ApiBearerAuth() @SerializeOptions({ groups: ['category-detail'] }) async update( @Body() data: UpdateCategoryDto, ) { return this.service.update(data); } /** * 批量删除分类 * @param data */ @Delete() @ApiBearerAuth() @SerializeOptions({ groups: ['category-list'] }) async delete( @Body() data: DeleteDto, ) { const { ids } = data; return this.service.delete(ids); }} ``` ### 服务[](#服务 "服务的直接链接") - 为文章和评论服务的列表查询添加上根据作者查询的功能 - 为文章和评论的创建添加上当前登录用户为作者(当前用户在控制器中通过`@ReqUser()`获取) - 全文搜索中加入文章作者的`username`和`nickname`字段 #### 文章服务[](#文章服务 "文章服务的直接链接") ``` // src/modules/content/services/post.service.ts@Injectable()export class PostService extends BaseService<PostEntity, PostRepository, FindParams> { protected enableTrash = true; constructor( protected repository: PostRepository, protected categoryRepository: CategoryRepository, protected categoryService: CategoryService, protected tagRepository: TagRepository, protected userRepository: UserRepository, protected searchService?: SearchService, protected search_type: SearchType = 'mysql', ) { super(repository); } /** * 创建文章 * @param data */ async create(data: CreatePostDto, author: ClassToPlain<UserEntity>) { const createPostDto = { ...data, // 文章作者 author: await this.userRepository.findOneByOrFail({ id: author.id }), //... }; // ... } protected async buildListQuery( qb: SelectQueryBuilder<PostEntity>, options: FindParams, callback?: QueryHook<PostEntity>, ) { // ... // 查询某个标签关联的文章 if (tag) qb.where('tags.id = :id', { id: tag }); // 根据作者查询文章 if (author) qb.where('author.id = :id', { id: author }); // 是否全文搜索 if (!isNil(search)) this.buildSearchQuery(qb, search); // 是否查询回收站 if (trashed === SelectTrashMode.ALL || trashed === SelectTrashMode.ONLY) { qb.withDeleted(); if (trashed === SelectTrashMode.ONLY) qb.where(`post.deletedAt is not null`); } if (callback) return callback(qb); return qb; } protected async buildSearchQuery(qb: SelectQueryBuilder<PostEntity>, search: string) { qb.andWhere('title LIKE :search', { search: `%${search}%` }) .orWhere('body LIKE :search', { search: `%${search}%` }) .orWhere('summary LIKE :search', { search: `%${search}%` }) .orWhere('category.name LIKE :search', { search: `%${search}%`, }) .orWhere('tags.name LIKE :search', { search: `%${search}%`, }) .orWhere('author.username LIKE :search', { search: `%${search}%`, }) .orWhere('author.nickname LIKE :search', { search: `%${search}%`, }); return qb; }} ``` #### 全文搜索[](#全文搜索 "全文搜索的直接链接") ``` // src/modules/content/helpers.tsexport async function getSearchItem( catRepo: CategoryRepository, cmtRepo: CommentRepository, post: PostEntity,) { // ... return [ { ...pick(instanceToPlain(post), [ 'id', 'title', 'body', 'summary', 'commentCount', 'deletedAt', 'publishedAt', 'createdAt', 'updatedAt', ]), categories, tags: post.tags.map((item) => ({ id: item.id, name: item.name })), author: pick(instanceToPlain(post.author), ['id', 'username', 'nickname']), comments, }, ];} ``` #### 评论服务[](#评论服务 "评论服务的直接链接") ``` // src/modules/content/services/comment.service.ts@Injectable()export class CommentService extends BaseService<CommentEntity, CommentRepository> { constructor( protected repository: CommentRepository, protected userRepository: UserRepository, protected postRepository: PostRepository, ) { super(repository); } /** * 查找一篇文章的评论并分页 * @param dto */ async paginate(options: QueryCommentDto) { const { post, author } = options; const addQuery = (qb: SelectQueryBuilder<CommentEntity>) => { const condition: Record<string, string> = {}; if (!isNil(post)) condition.post = post; if (!isNil(author)) condition.author = author; return Object.keys(condition).length > 0 ? qb.andWhere(condition) : qb; }; return super.paginate({ ...options, addQuery, }); } /** * 新增评论 * @param data * @param author */ async create(data: CreateCommentDto, author: ClassToPlain<UserEntity>) { // ... const item = await this.repository.save({ ...data, parent, post: await this.getPost(data.post), author: await this.userRepository.findOneByOrFail({ id: author.id }), }); return this.repository.findOneOrFail({ where: { id: item.id } }); } // ...} ``` #### 控制器[](#控制器-2 "控制器的直接链接") ``` // src/modules/content/controllers/post.controller.tsexport class PostController { // ... /** * 新增文章 * @param data */ @Post() @ApiBearerAuth() @SerializeOptions({ groups: ['post-detail'] }) async store( @Body() data: CreatePostDto, @ReqUser() author: ClassToPlain<UserEntity>, ) { return this.service.create(data, author); }}// src/modules/content/controllers/comment.controller.ts@ApiTags('评论操作')@Depends(ContentModule)@Controller('comments')export class CommentController { // ... /** * 新增评论 * @param data */ @Post() @ApiBearerAuth() @SerializeOptions({ groups: ['comment-detail'] }) async store( @Body() data: CreateCommentDto, @ReqUser() author: ClassToPlain<UserEntity>, ) { return this.service.create(data, author); }} ``` ### 修改模块[](#修改模块 "修改模块的直接链接") 在模块中导入`UserModule`以使用用户模块导出的提供者,比如`PostService`中注入了`UserRepository` ``` @Module({})export class ContentModule { static async forRoot(configure: Configure) { // ... useFactory( postRepository: repositories.PostRepository, userRepository: UserRepository, // ... ) { return new PostService( postRepository, userRepository, // ... ); }, }, ]; // ... return { module: ContentModule, imports: [ UserModule, addEntities(configure, Object.values(entities)), DatabaseModule.forRepository(Object.values(repositories)), ], // ... }; }} ``` ### 路由端点[](#路由端点 "路由端点的直接链接") 最后,与用户模块一样,我们编写一个API构建函数并在api配置文件中导入 #### 创建路由[](#创建路由 "创建路由的直接链接") ``` // src/modules/content/routes.tsimport * as controllers from './controllers';export const createContentApi = () => { const routes: Record<'app', RouteOption[]> = { app: [ { name: 'app.content', path: 'content', controllers: Object.values(controllers), }, ], }; const tags: Record<'app', (string | TagOption)[]> = { app: [ { name: '分类操作', description: '对分类进行CRUD操作' }, { name: '标签操作', description: '对标签进行CRUD操作' }, { name: '文章操作', description: '对文章进行CRUD操作' }, { name: '评论操作', description: '对评论进行CRUD操作' }, ], }; return { routes, tags };}; ``` #### 导入配置[](#导入配置 "导入配置的直接链接") ``` // src/config/api.config/v1.tsexport const v1 = async (configure: Configure): Promise<VersionOption> => { const contentApi = createContentApi(); const userApi = createUserApi(); return { routes: [ { name: 'app', path: '/', controllers: [], doc: { // title: '应用接口', description: '3R教室《Nestjs实战开发》课程应用的客户端接口(应用名称随机自动生成)', tags: [...contentApi.tags.app, ...userApi.tags.app], }, children: [...contentApi.routes.app, ...userApi.routes.app], }, ], };}; ``` 需要使用并测试本节课的功能需要以下几步 提示 后续一个新功能模块开发完毕后大致都是这样操作 1. 生成数据迁移(如果是已上线项目扩展,则建议手动编写) 2. 运行数据迁移(生成数据迁移和运行数据迁移可以直接使用一条命令合并运行) 3. 编写数据工厂和数据填充类,并运行数据填充命令 4. 启动应用并在insomnia或者其它的API测试工具中导入OpenAPI(Swagger)进行测试 ### 数据迁移[](#数据迁移 "数据迁移的直接链接") 首先,生成数据迁移并运行数据迁移 ``` pnpm cli dbmg -r ``` 或者 ``` pnpm cli dbmgpnpm cli dbmr ``` 其实,上述命令的`-r`不加或者`pnpm cli dbmr`不运行也是可以的。因为我们已经编写了自动迁移并默认开启,所以直接启动应用就会自动运行迁移的 ### 数据工厂[](#数据工厂 "数据工厂的直接链接") 编写一个用于生成用户数据的数据工厂 ``` // src/database/factories/content.factory.tsexport type IUserFactoryOptions = Partial<{ [key in keyof UserEntity]: UserEntity[key];}>;export const UserFactory = defineFactory( UserEntity, async (configure: Configure, settings: IUserFactoryOptions = {}) => { const faker = new fakerjs.Faker({ locale: await getFakerLocales(configure), }); const user = new UserEntity(); const optionals: (keyof IUserFactoryOptions)[] = ['username', 'password', 'email', 'phone']; optionals.forEach((key) => { if (settings[key] !== undefined) { user[key] = settings[key] as any; } }); user.nickname = settings.nickname ?? faker.person.fullName(); return user; },);// src/config/database.config.tsexport const database = createDbConfig((configure) => ({ common: { synchronize: true, }, connections: [ { // ... factories: [UserFactory, ContentFactory], seeders: [ContentSeeder], }, ],})); ``` ### 数据填充[](#数据填充 "数据填充的直接链接") 注意 注意:注册用户数据填充类时,用户填充类必须在内容填充类之前。因为必须先有用户才能设置文章作者,而seeder是根据注册顺序执行的 1. 为文章和评论数据添加作者:固定文章数据均使用第一位用户作为作者,faker生成的文章和评论数据使用随机作者 2. 编写用户数据填充类 3. 注册用户数据填充类 ``` // src/database/seeders/user.seeder.tsexport default class UserSeeder extends BaseSeeder { protected truncates = [UserEntity, AccessTokenEntity, RefreshTokenEntity]; protected factorier: DbFactory; async run(_factorier: DbFactory, _dataSource: DataSource, _em: EntityManager): Promise<any> { this.factorier = _factorier; await this.loadUsers(); } private async loadUsers() { const repository = getCustomRepository(this.dataSource, UserRepository); const userFactory = this.factorier(UserEntity); const count = await repository.count(); if (count < 2) { await userFactory<IUserFactoryOptions>({ username: 'pincman', nickname: 'pincman', password: '123456aA$', }).create({}, 'username'); await userFactory<IUserFactoryOptions>({ username: 'xiaoming', nickname: '小明', phone: '+86.18605853847', password: '123456aA$', }).create({}, 'username'); await userFactory<IUserFactoryOptions>({ username: 'lige', nickname: '李哥', phone: '+86.15955959999', password: '123456aA$', }).create({}, 'username'); await userFactory<IUserFactoryOptions>().createMany(15, {}, 'username'); } }}// src/database/factories/content.factory.tsexport type IPostFactoryOptions = Partial<{ // ...}> & { author: UserEntity };export const ContentFactory = defineFactory( PostEntity, async (configure: Configure, options: IPostFactoryOptions) => { // ... const { title, summary, body, category, tags, author } = options; //... post.author = author; return post; },);// src/database/seeders/content.seeder.tsexport default class ContentSeeder extends BaseSeeder { protected truncates = [PostEntity, TagEntity, CategoryEntity, CommentEntity]; protected users: UserEntity[] = []; protected factorier: DbFactory; async run(_factorier: DbFactory, _dataSource: DataSource, _em: EntityManager): Promise<any> { this.factorier = _factorier; const userRepo = getCustomRepository(this.dataSource, UserRepository); this.users = await userRepo.find({ take: 5 }); // ... } private async genRandomComments(post: PostEntity, count: number, parent?: CommentEntity) { const comments: CommentEntity[] = []; for (let i = 0; i < count; i++) { // ... comment.author = getRandItemData(this.users); comments.push(await this.em.save(comment)); // ... } return comments; } // ... private async loadPosts(data: PostData[]) { const author = await this.em.createQueryBuilder(UserEntity, 'user').getOne(); // ... for (const item of data) { // ... const options: IPostFactoryOptions = { title: item.title, body: fs.readFileSync(filePath, 'utf8'), isPublished: true, author, }; // ... } await this.factorier(PostEntity)<IPostFactoryOptions>({ tags: getRandListData(allTags), category: getRandItemData(allCategories), author: getRandItemData(this.users), }).createMany(10); }}// src/database/seeders/user.seeder.tsexport default class UserSeeder extends BaseSeeder { protected truncates = [UserEntity, AccessTokenEntity, RefreshTokenEntity]; protected factorier: DbFactory; async run(_factorier: DbFactory, _dataSource: DataSource, _em: EntityManager): Promise<any> { this.factorier = _factorier; await this.loadUsers(); } private async loadUsers() { const repository = getCustomRepository(this.dataSource, UserRepository); const userFactory = this.factorier(UserEntity); const count = await repository.count(); if (count < 2) { await userFactory<IUserFactoryOptions>({ username: 'pincman', nickname: 'pincman', password: '123456aA$', }).create({}, 'username'); await userFactory<IUserFactoryOptions>({ username: 'xiaoming', nickname: '小明', phone: '+86.18605853847', password: '123456aA$', }).create({}, 'username'); await userFactory<IUserFactoryOptions>({ username: 'lige', nickname: '李哥', phone: '+86.15955959999', password: '123456aA$', }).create({}, 'username'); await userFactory<IUserFactoryOptions>().createMany(15, {}, 'username'); } }}// src/config/database.config.tsexport const database = createDbConfig((configure) => ({ common: { synchronize: true, }, connections: [ { // ... factories: [UserFactory, ContentFactory], seeders: [UserSeeder, ContentSeeder], }, ],})); ``` 运行数据填充命令 ``` pnpm cli dbs ``` ### 测试接口[](#测试接口 "测试接口的直接链接") 最后,使用`pnpm dev`或`pnpm start:dev`启动应用,并把`http://127.0.0.1:3100/api/docs-json`导入insomnia或者其它类似apifox之类的工具就可以测试接口了
peipeo
2026年11月8日 10:34
转发文档
收藏文档
上一篇
下一篇
手机扫码
复制链接
手机扫一扫转发分享
复制链接
Markdown文件
PDF文档(打印)
分享
链接
类型
密码
更新密码