whale-town-end/docs/development/backend_development_guide.md

后端开发规范指南

本文档定义了后端开发的核心规范，包括注释规范、日志规范、业务逻辑规范等，确保代码质量和团队协作效率。

📋 目录

• 注释规范
• 日志规范
• 业务逻辑规范
• 异常处理规范
• 代码质量规范
• 最佳实践

---

📝 注释规范

文件头注释

每个 TypeScript 文件都必须包含完整的文件头注释：

/**
 * 文件功能描述
 * 
 * 功能描述：
 * - 主要功能点1
 * - 主要功能点2
 * - 主要功能点3
 * 
 * 职责分离：
 * - 职责描述1
 * - 职责描述2
 * 
 * 最近修改：
 * - YYYY-MM-DD: 修改类型 - 具体修改内容描述
 * - YYYY-MM-DD: 修改类型 - 具体修改内容描述
 * 
 * @author 作者名
 * @version x.x.x
 * @since 创建日期
 * @lastModified 最后修改日期
 */

类注释

/**
 * 类功能描述
 * 
 * 职责：
 * - 主要职责1
 * - 主要职责2
 * 
 * 主要方法：
 * - method1() - 方法1功能
 * - method2() - 方法2功能
 * 
 * 使用场景：
 * - 场景描述
 */
@Injectable()
export class ExampleService {
  // 类实现
}

方法注释（三级注释标准）

必须包含以下三个级别的注释：

1. 功能描述级别

/**
 * 用户登录验证
 */

2. 业务逻辑级别

/**
 * 用户登录验证
 * 
 * 业务逻辑：
 * 1. 验证用户名或邮箱格式
 * 2. 查找用户记录
 * 3. 验证密码哈希值
 * 4. 检查用户状态是否允许登录
 * 5. 记录登录日志
 * 6. 返回认证结果
 */

3. 技术实现级别

/**
 * 用户登录验证
 * 
 * 业务逻辑：
 * 1. 验证用户名或邮箱格式
 * 2. 查找用户记录
 * 3. 验证密码哈希值
 * 4. 检查用户状态是否允许登录
 * 5. 记录登录日志
 * 6. 返回认证结果
 * 
 * @param loginRequest 登录请求数据
 * @returns 认证结果，包含用户信息和认证状态
 * @throws UnauthorizedException 用户名或密码错误时
 * @throws ForbiddenException 用户状态不允许登录时
 * 
 * @example
 * ```typescript
 * const result = await loginService.validateUser({
 *   identifier: 'user@example.com',
 *   password: 'password123'
 * });
 * ```
 */
async validateUser(loginRequest: LoginRequest): Promise<AuthResult> {
  // 实现代码
}

修改记录规范

修改类型定义

• 代码规范优化 - 命名规范、注释规范、代码清理等
• 功能新增 - 添加新的功能或方法
• 功能修改 - 修改现有功能的实现
• Bug修复 - 修复代码缺陷
• 性能优化 - 提升代码性能
• 重构 - 代码结构调整但功能不变

修改记录格式

/**
 * 最近修改：
 * - 2025-01-07: 代码规范优化 - 清理未使用的导入(EmailSendResult, crypto)
 * - 2025-01-07: 代码规范优化 - 修复常量命名(saltRounds -> SALT_ROUNDS)
 * - 2025-01-07: 功能新增 - 添加用户验证码登录功能
 * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误
 * 
 * @version 1.0.1 (修改后需要递增版本号)
 * @lastModified 2025-01-07
 */

修改记录长度限制

重要：为保持文件头注释简洁，修改记录只保留最近的5次修改。

• ✅ 保留最新5条记录 - 便于快速了解最近变更
• ✅ 超出时删除最旧记录 - 保持注释简洁
• ✅ 重要修改可标注 - 重大版本更新可特别标注

// ✅ 正确示例：保持最新5条记录
/**
 * 最近修改：
 * - 2025-01-07: 功能新增 - 添加用户头像上传功能
 * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误  
 * - 2025-01-05: 代码规范优化 - 统一异常处理格式
 * - 2025-01-04: 功能修改 - 优化用户状态管理逻辑
 * - 2025-01-03: 性能优化 - 优化数据库查询性能
 * 
 * @version 1.3.0
 */

// ❌ 错误示例：记录过多，注释冗长
/**
 * 最近修改：
 * - 2025-01-07: 功能新增 - 添加用户头像上传功能
 * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误
 * - 2025-01-05: 代码规范优化 - 统一异常处理格式
 * - 2025-01-04: 功能修改 - 优化用户状态管理逻辑
 * - 2025-01-03: 性能优化 - 优化数据库查询性能
 * - 2025-01-02: 重构 - 重构用户认证逻辑
 * - 2025-01-01: 功能新增 - 添加用户权限管理
 * - 2024-12-31: Bug修复 - 修复登录超时问题
 * // ... 更多记录导致注释过长
 */

版本号递增规则

• 代码规范优化、Bug修复 → 修订版本 +1 (1.0.0 → 1.0.1)
• 功能新增、功能修改 → 次版本 +1 (1.0.1 → 1.1.0)
• 重构、架构变更 → 主版本 +1 (1.1.0 → 2.0.0)

---

📊 日志规范

日志级别使用

// ERROR - 系统错误，需要立即处理
this.logger.error('用户登录失败', { userId, error: error.message });

// WARN - 警告信息，需要关注但不影响系统运行
this.logger.warn('用户多次登录失败', { userId, attemptCount });

// INFO - 重要的业务操作记录
this.logger.info('用户登录成功', { userId, loginTime: new Date() });

// DEBUG - 调试信息，仅在开发环境使用
this.logger.debug('验证用户密码', { userId, hashedPassword: '***' });

日志格式规范

// ✅ 正确格式
this.logger.info('操作描述', {
  userId: 'user123',
  action: 'login',
  timestamp: new Date(),
  metadata: { ip: '192.168.1.1' }
});

// ❌ 错误格式
this.logger.info('用户登录');
this.logger.info(`用户${userId}登录成功`);

---

🏗️ 业务逻辑规范

防御性编程

async getUserById(userId: string): Promise<User> {
  // 1. 参数验证
  if (!userId) {
    throw new BadRequestException('用户ID不能为空');
  }

  // 2. 业务逻辑验证
  const user = await this.usersService.findOne(userId);
  if (!user) {
    throw new NotFoundException('用户不存在');
  }

  // 3. 状态检查
  if (user.status === UserStatus.DELETED) {
    throw new ForbiddenException('用户已被删除');
  }

  // 4. 返回结果
  return user;
}

业务逻辑分层

// Controller 层 - 只处理HTTP请求和响应
@Controller('users')
export class UsersController {
  @Get(':id')
  async getUser(@Param('id') id: string) {
    return this.usersService.getUserById(id);
  }
}

// Service 层 - 处理业务逻辑
@Injectable()
export class UsersService {
  async getUserById(id: string): Promise<User> {
    // 业务逻辑实现
    return this.usersCoreService.findUserById(id);
  }
}

// Core 层 - 核心业务实现
@Injectable()
export class UsersCoreService {
  async findUserById(id: string): Promise<User> {
    // 核心逻辑实现
  }
}

---

⚠️ 异常处理规范

异常类型使用

// 400 - 客户端请求错误
throw new BadRequestException('参数格式错误');

// 401 - 未授权
throw new UnauthorizedException('用户名或密码错误');

// 403 - 禁止访问
throw new ForbiddenException('用户状态不允许此操作');

// 404 - 资源不存在
throw new NotFoundException('用户不存在');

// 409 - 资源冲突
throw new ConflictException('用户名已存在');

// 500 - 服务器内部错误
throw new InternalServerErrorException('系统内部错误');

异常处理模式

async createUser(userData: CreateUserDto): Promise<User> {
  try {
    // 1. 参数验证
    this.validateUserData(userData);
    
    // 2. 业务逻辑检查
    await this.checkUserExists(userData.email);
    
    // 3. 执行创建操作
    const user = await this.usersRepository.create(userData);
    
    // 4. 记录成功日志
    this.logger.info('用户创建成功', { userId: user.id });
    
    return user;
  } catch (error) {
    // 5. 记录错误日志
    this.logger.error('用户创建失败', {
      userData: { ...userData, password: '***' },
      error: error.message
    });
    
    // 6. 重新抛出业务异常
    if (error instanceof BadRequestException) {
      throw error;
    }
    
    // 7. 转换为系统异常
    throw new InternalServerErrorException('用户创建失败');
  }
}

---

🔍 代码质量规范

代码检查清单

在提交代码前，请确保：

• 注释完整性

  • 文件头注释包含功能描述、修改记录、作者信息
  • 类注释包含职责、主要方法、使用场景
  • 方法注释包含三级注释（功能、业务逻辑、技术实现）
  • 修改现有文件时添加了修改记录和更新版本号
  • 修改记录只保留最近5次，保持注释简洁

• 业务逻辑完整性

  • 所有参数都进行了验证
  • 所有异常情况都进行了处理
  • 关键操作都记录了日志
  • 业务逻辑考虑了所有边界情况

• 代码质量

  • 没有未使用的导入和变量
  • 常量使用了正确的命名规范
  • 方法长度合理（建议不超过50行）
  • 单一职责原则，每个方法只做一件事

• 安全性

  • 敏感信息不在日志中暴露
  • 用户输入都进行了验证和清理
  • 权限检查在适当的位置进行

---

💡 最佳实践

1. 注释驱动开发

/**
 * 用户注册功能
 * 
 * 业务逻辑：
 * 1. 验证邮箱格式和唯一性
 * 2. 验证密码强度
 * 3. 生成邮箱验证码
 * 4. 创建用户记录
 * 5. 发送验证邮件
 * 6. 返回注册结果
 * 
 * @param registerData 注册数据
 * @returns 注册结果
 */
async registerUser(registerData: RegisterDto): Promise<RegisterResult> {
  // 先写注释，再写实现
  // 这样确保逻辑清晰，不遗漏步骤
}

2. 错误优先处理

async processPayment(paymentData: PaymentDto): Promise<PaymentResult> {
  // 1. 先处理所有可能的错误情况
  if (!paymentData.amount || paymentData.amount <= 0) {
    throw new BadRequestException('支付金额必须大于0');
  }
  
  if (!paymentData.userId) {
    throw new BadRequestException('用户ID不能为空');
  }
  
  const user = await this.usersService.findOne(paymentData.userId);
  if (!user) {
    throw new NotFoundException('用户不存在');
  }
  
  // 2. 再处理正常的业务逻辑
  return this.executePayment(paymentData);
}

3. 日志驱动调试

async complexBusinessLogic(data: ComplexData): Promise<Result> {
  this.logger.debug('开始执行复杂业务逻辑', { data });
  
  try {
    // 步骤1
    const step1Result = await this.step1(data);
    this.logger.debug('步骤1完成', { step1Result });
    
    // 步骤2
    const step2Result = await this.step2(step1Result);
    this.logger.debug('步骤2完成', { step2Result });
    
    // 步骤3
    const finalResult = await this.step3(step2Result);
    this.logger.info('复杂业务逻辑执行成功', { finalResult });
    
    return finalResult;
  } catch (error) {
    this.logger.error('复杂业务逻辑执行失败', { data, error: error.message });
    throw error;
  }
}

4. 版本管理最佳实践

/**
 * 用户服务
 * 
 * 最近修改：
 * - 2025-01-07: 功能新增 - 添加用户头像上传功能 (v1.2.0)
 * - 2025-01-06: Bug修复 - 修复邮箱验证逻辑错误 (v1.1.1)
 * - 2025-01-05: 代码规范优化 - 统一异常处理格式 (v1.1.0)
 * - 2025-01-04: 功能新增 - 添加用户状态管理 (v1.1.0)
 * - 2025-01-03: 重构 - 重构用户认证逻辑 (v2.0.0)
 * 
 * @version 1.2.0
 * @lastModified 2025-01-07
 */

修改记录管理原则：

• ✅ 保持简洁 - 只保留最近5次修改
• ✅ 定期清理 - 超出5条时删除最旧记录
• ✅ 重要标注 - 重大版本更新可特别标注版本号
• ✅ 描述清晰 - 每条记录都要说明具体改动内容

---

🎯 总结

遵循后端开发规范能够：

1. 提高代码质量 - 通过完整的注释和规范的实现
2. 提升团队效率 - 统一的规范减少沟通成本
3. 降低维护成本 - 清晰的文档和日志便于问题定位
4. 增强系统稳定性 - 完善的异常处理和防御性编程
5. 促进知识传承 - 详细的修改记录和版本管理

记住：好的代码不仅要能运行，更要能被理解、维护和扩展。

---

📚 相关文档

• 命名规范 - 代码命名规范
• NestJS 使用指南 - 框架最佳实践
• Git 提交规范 - 版本控制规范
• AI 辅助开发规范 - AI 辅助开发指南