ANGJustinl/whale-town-end
1
0
Fork 0
forked from datawhale/whale-town-end
Code Pull Requests Activity

refactor：项目架构重构和命名规范化

Browse Source 
- 统一文件命名为snake_case格式（kebab-case  snake_case）
- 重构zulip模块为zulip_core，明确Core层职责
- 重构user-mgmt模块为user_mgmt，统一命名规范
- 调整模块依赖关系，优化架构分层
- 删除过时的文件和目录结构
- 更新相关文档和配置文件

本次重构涉及大量文件重命名和模块重组，
旨在建立更清晰的项目架构和统一的命名规范。
This commit is contained in:
moyin
2026-01-08 00:14:14 +08:00
parent 4fa4bd1a70
commit bb796a2469
178 changed files with 24767 additions and 3484 deletions
Download Patch File Download Diff File Expand all files Collapse all files

505
docs/development/backend_development_guide.md Normal file
View File

@@ -0,0 +1,505 @@
# 后端开发规范指南
本文档定义了后端开发的核心规范，包括注释规范、日志规范、业务逻辑规范等，确保代码质量和团队协作效率。
## 📋 目录
- [注释规范](#注释规范)
- [日志规范](#日志规范)
- [业务逻辑规范](#业务逻辑规范)
- [异常处理规范](#异常处理规范)
- [代码质量规范](#代码质量规范)
- [最佳实践](#最佳实践)
---
## 📝 注释规范
### 文件头注释
每个 TypeScript 文件都必须包含完整的文件头注释：
```typescript
/**
* 文件功能描述
*
* 功能描述：
* - 主要功能点1
* - 主要功能点2
* - 主要功能点3
*
* 职责分离：
* - 职责描述1
* - 职责描述2
*
* 最近修改：
* - YYYY-MM-DD: 修改类型 - 具体修改内容描述
* - YYYY-MM-DD: 修改类型 - 具体修改内容描述
*
* @author 作者名
* @version x.x.x
* @since 创建日期
* @lastModified 最后修改日期
*/
```
### 类注释
```typescript
/**
* 类功能描述
*
* 职责：
* - 主要职责1
* - 主要职责2
*
* 主要方法：
* - method1() - 方法1功能
* - method2() - 方法2功能
*
* 使用场景：
* - 场景描述
*/
@Injectable()
export class ExampleService {
// 类实现
}
```
### 方法注释（三级注释标准）
**必须包含以下三个级别的注释：**
#### 1. 功能描述级别
```typescript
/**
* 用户登录验证
*/
```
#### 2. 业务逻辑级别
```typescript
/**
* 用户登录验证
*
* 业务逻辑：
* 1. 验证用户名或邮箱格式
* 2. 查找用户记录
* 3. 验证密码哈希值
* 4. 检查用户状态是否允许登录
* 5. 记录登录日志
* 6. 返回认证结果
*/
```
#### 3. 技术实现级别
```typescript
/**
* 用户登录验证
*
* 业务逻辑：
* 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修复** - 修复代码缺陷
- **性能优化** - 提升代码性能
- **重构** - 代码结构调整但功能不变
#### 修改记录格式
```typescript
/**
* 最近修改：
* - 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条记录** - 便于快速了解最近变更
- ✅ **超出时删除最旧记录** - 保持注释简洁
- ✅ **重要修改可标注** - 重大版本更新可特别标注
```typescript
// ✅ 正确示例：保持最新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)
---
## 📊 日志规范
### 日志级别使用
```typescript
// 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: '***' });
```
### 日志格式规范
```typescript
// ✅ 正确格式
this.logger.info('操作描述', {
userId: 'user123',
action: 'login',
timestamp: new Date(),
metadata: { ip: '192.168.1.1' }
});
// ❌ 错误格式
this.logger.info('用户登录');
this.logger.info(`用户${userId}登录成功`);
```
---
## 🏗️ 业务逻辑规范
### 防御性编程
```typescript
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;
}
```
### 业务逻辑分层
```typescript
// 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> {
// 核心逻辑实现
}
}
```
---
## ⚠️ 异常处理规范
### 异常类型使用
```typescript
// 400 - 客户端请求错误
throw new BadRequestException('参数格式错误');
// 401 - 未授权
throw new UnauthorizedException('用户名或密码错误');
// 403 - 禁止访问
throw new ForbiddenException('用户状态不允许此操作');
// 404 - 资源不存在
throw new NotFoundException('用户不存在');
// 409 - 资源冲突
throw new ConflictException('用户名已存在');
// 500 - 服务器内部错误
throw new InternalServerErrorException('系统内部错误');
```
### 异常处理模式
```typescript
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. 注释驱动开发
```typescript
/**
* 用户注册功能
*
* 业务逻辑：
* 1. 验证邮箱格式和唯一性
* 2. 验证密码强度
* 3. 生成邮箱验证码
* 4. 创建用户记录
* 5. 发送验证邮件
* 6. 返回注册结果
*
* @param registerData 注册数据
* @returns 注册结果
*/
async registerUser(registerData: RegisterDto): Promise<RegisterResult> {
// 先写注释，再写实现
// 这样确保逻辑清晰，不遗漏步骤
}
```
### 2. 错误优先处理
```typescript
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. 日志驱动调试
```typescript
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. 版本管理最佳实践
```typescript
/**
* 用户服务
*
* 最近修改：
* - 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. **促进知识传承** - 详细的修改记录和版本管理
**记住：好的代码不仅要能运行，更要能被理解、维护和扩展。**
---
## 📚 相关文档
- [命名规范](./naming_convention.md) - 代码命名规范
- [NestJS 使用指南](./nestjs_guide.md) - 框架最佳实践
- [Git 提交规范](./git_commit_guide.md) - 版本控制规范
- [AI 辅助开发规范](./AI辅助开发规范指南.md) - AI 辅助开发指南