Files

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

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

本次重构涉及大量文件重命名和模块重组，
旨在建立更清晰的项目架构和统一的命名规范。

2026-01-08 00:14:14 +08:00

3.1 KiB

Raw Blame History

Shared 共享数据结构模块

Shared 是应用的跨业务模块共享数据结构模块，提供标准化的数据传输对象和API响应格式，确保整个应用的数据结构一致性和API规范性。

应用状态管理

AppStatusResponseDto

定义应用健康检查和状态查询接口的标准响应格式，包含服务信息、运行状态、环境配置等完整的应用运行时数据。

错误响应处理

ErrorResponseDto

定义全局异常处理的统一错误响应格式，提供标准化的错误信息结构，支持HTTP状态码、错误消息、时间戳等完整的错误上下文。

使用的项目内部依赖

ApiProperty (来自 @nestjs/swagger)

NestJS Swagger装饰器，用于生成API文档和定义响应数据结构的元数据信息。

核心特性

标准化数据结构

统一的DTO类设计模式，确保数据传输对象的一致性
完整的属性类型定义，提供强类型支持和编译时检查
规范的命名约定，遵循camelCase属性命名和PascalCase类命名

Swagger文档集成

完整的ApiProperty装饰器配置，自动生成API文档
详细的属性描述和示例值，提升API可读性和可用性
枚举值定义和类型约束，确保API契约的准确性

跨模块复用设计

统一的导出接口，简化其他模块的导入路径
模块化的文件组织，支持按功能分类管理DTO类
清晰的职责分离，专注于数据结构定义而非业务逻辑

潜在风险

API契约变更风险

DTO结构变更可能影响多个业务模块的API兼容性
建议在修改现有DTO时进行充分的影响评估和版本管理
推荐使用渐进式API演进策略，避免破坏性变更

数据验证缺失风险

当前DTO类只定义数据结构，不包含数据验证逻辑
建议在使用DTO的Controller层添加适当的数据验证
考虑引入class-validator装饰器增强数据验证能力

文档同步风险

Swagger装饰器配置需要与实际数据结构保持同步
建议定期检查API文档的准确性和完整性
推荐在CI/CD流程中集成API文档生成和验证

使用示例

// 导入共享DTO
import { AppStatusResponseDto, ErrorResponseDto } from '@/business/shared';

// 在Controller中使用
@ApiResponse({ type: AppStatusResponseDto })
@Get('status')
async getStatus(): Promise<AppStatusResponseDto> {
  return {
    service: 'Pixel Game Server',
    version: '1.0.0',
    status: 'running',
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
    environment: process.env.NODE_ENV || 'development',
    storageMode: 'database'
  };
}

// 在异常过滤器中使用
@Catch()
export class GlobalExceptionFilter implements ExceptionFilter {
  catch(exception: any, host: ArgumentsHost) {
    const response: ErrorResponseDto = {
      statusCode: 500,
      message: 'Internal server error',
      timestamp: new Date().toISOString(),
      path: request.url,
      error: 'INTERNAL_ERROR'
    };
    
    return response;
  }
}

版本信息

版本: 1.0.1
作者: moyin
创建时间: 2025-12-17
最后修改: 2026-01-07

3.1 KiB Raw Blame History Unescape Escape