# 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文档生成和验证

## 使用示例

```typescript
// 导入共享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