diff --git a/src/core/db/users/base_users.service.ts b/src/core/db/users/base_users.service.ts index 3069406..b29b926 100644 --- a/src/core/db/users/base_users.service.ts +++ b/src/core/db/users/base_users.service.ts @@ -14,13 +14,14 @@ * - 搜索优化:搜索异常的特殊处理机制 * * 最近修改: + * - 2026-01-15: 代码规范优化 - 为保护方法补充@example示例 (修改者: moyin) * - 2026-01-07: 代码规范优化 - 完善注释规范,添加完整的文件头和方法注释 * - 2026-01-07: 功能新增 - 添加敏感信息脱敏处理和结构化日志记录 * * @author moyin - * @version 1.0.1 + * @version 1.0.2 * @since 2025-01-07 - * @lastModified 2026-01-07 + * @lastModified 2026-01-15 */ import { Logger, ConflictException, NotFoundException, BadRequestException } from '@nestjs/common'; @@ -33,6 +34,12 @@ export abstract class BaseUsersService { * * @param error 原始错误对象 * @returns 格式化后的错误信息字符串 + * + * @example + * ```typescript + * const errorMsg = this.formatError(new Error('数据库连接失败')); + * // 返回: "数据库连接失败" + * ``` */ protected formatError(error: unknown): string { if (error instanceof Error) { @@ -48,6 +55,15 @@ export abstract class BaseUsersService { * @param operation 操作名称 * @param context 上下文信息 * @throws 处理后的标准异常 + * + * @example + * ```typescript + * try { + * // 业务操作 + * } catch (error) { + * this.handleServiceError(error, '创建用户', { username: 'test' }); + * } + * ``` */ protected handleServiceError(error: unknown, operation: string, context?: Record): never { const errorMessage = this.formatError(error); @@ -78,6 +94,15 @@ export abstract class BaseUsersService { * @param operation 操作名称 * @param context 上下文信息 * @returns 空数组 + * + * @example + * ```typescript + * try { + * // 搜索操作 + * } catch (error) { + * return this.handleSearchError(error, '搜索用户', { keyword: 'test' }); + * } + * ``` */ protected handleSearchError(error: unknown, operation: string, context?: Record): any[] { const errorMessage = this.formatError(error); @@ -98,6 +123,11 @@ export abstract class BaseUsersService { * @param operation 操作名称 * @param context 上下文信息 * @param duration 操作耗时 + * + * @example + * ```typescript + * this.logSuccess('创建用户', { userId: '123', username: 'test' }, 50); + * ``` */ protected logSuccess(operation: string, context?: Record, duration?: number): void { this.logger.log(`${operation}成功`, { @@ -113,6 +143,11 @@ export abstract class BaseUsersService { * * @param operation 操作名称 * @param context 上下文信息 + * + * @example + * ```typescript + * this.logStart('创建用户', { username: 'test' }); + * ``` */ protected logStart(operation: string, context?: Record): void { this.logger.log(`开始${operation}`, { @@ -127,6 +162,16 @@ export abstract class BaseUsersService { * * @param data 原始数据 * @returns 脱敏后的数据 + * + * @example + * ```typescript + * const sanitized = this.sanitizeLogData({ + * email: 'test@example.com', + * phone: '13800138000', + * password_hash: 'secret' + * }); + * // 返回: { email: 'te***@example.com', phone: '138****00', password_hash: '[REDACTED]' } + * ``` */ protected sanitizeLogData(data: Record): Record { const sanitized = { ...data }; diff --git a/src/core/db/users/users.constants.ts b/src/core/db/users/users.constants.ts index 3e59307..65f263f 100644 --- a/src/core/db/users/users.constants.ts +++ b/src/core/db/users/users.constants.ts @@ -6,13 +6,19 @@ * - 避免魔法数字,提高代码可维护性 * - 集中管理配置参数 * + * 职责分离: + * - 常量定义:用户角色、字段限制、查询限制等常量值 + * - 错误消息:统一的错误消息定义和管理 + * - 工具类:性能监控和验证工具的封装 + * * 最近修改: + * - 2026-01-15: 代码规范优化 - 补充职责分离描述 (修改者: moyin) * - 2026-01-09: 代码质量优化 - 提取魔法数字为常量定义 (修改者: moyin) * * @author moyin - * @version 1.0.0 + * @version 1.0.1 * @since 2026-01-09 - * @lastModified 2026-01-09 + * @lastModified 2026-01-15 */ import { ValidationError } from 'class-validator';