forked from datawhale/whale-town-end
refactor:项目架构重构和命名规范化
- 统一文件命名为snake_case格式(kebab-case snake_case) - 重构zulip模块为zulip_core,明确Core层职责 - 重构user-mgmt模块为user_mgmt,统一命名规范 - 调整模块依赖关系,优化架构分层 - 删除过时的文件和目录结构 - 更新相关文档和配置文件 本次重构涉及大量文件重命名和模块重组, 旨在建立更清晰的项目架构和统一的命名规范。
This commit is contained in:
97
src/business/shared/README.md
Normal file
97
src/business/shared/README.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user