深入解析Shadow Editor Pro后端架构：从Electron主进程到NestJS模块的完整技术指南

本文档详细说明 Shadow Editor Pro 后端代码的目录结构和各模块功能。

技术栈

框架: NestJS 10
语言: TypeScript 5
运行时: Node.js
数据库: 文件存储
日志: electron-log
桌面框架: Electron

目录结构概览

electron/
├── main.ts              # Electron主进程
├── preload.ts           # 预加载脚本
├── server.ts            # NestJS服务启动
├── config.ts            # 配置文件
├── common/              # 公共模块
│   ├── PageData.ts      # 分页数据
│   └── Result.ts        # 响应结果
├── data/                # 业务数据模块
│   ├── controller/      # 控制器
│   ├── entity/          # 实体
│   └── service/         # 服务
├── three/               # 3D资源模块
│   ├── controller/      # 控制器
│   ├── entity/          # 实体
│   └── service/         # 服务
├── filter/              # 异常过滤器
├── interceptor/         # 拦截器
├── pipe/                # 管道
├── utils/               # 工具函数
└── __tests__/           # 测试文件

1. Electron主进程 (main.ts)

功能: Electron应用的主进程，负责创建窗口和管理应用生命周期

主要功能:

创建和管理BrowserWindow窗口
启动NestJS后端服务
处理窗口控制（最大化、最小化、还原等）
处理IPC通信（进程间通信）
集成开发工具（DevTools）

IPC事件:

exit: 退出应用
maximize: 最大化窗口
minimize: 最小化窗口
restore: 还原窗口大小
openDevTools: 打开开发者工具
openInBrowser: 在浏览器中打开URL

使用示例:

// 前端调用IPC
window.api.maximize()
window.api.exit()

2. 预加载脚本 (preload.ts)

功能: 连接主进程和渲染进程，暴露安全的API给前端

主要功能:

暴露IPC接口给渲染进程
提供类型安全的API
确保安全性（contextIsolation）

3. 服务启动 (server.ts)

功能: 启动和配置NestJS服务器

主要配置:

全局异常过滤器
日志拦截器
请求体解析（支持200MB）
静态文件服务
CORS配置

模块导入:

DataModule: 业务数据模块
ThreeModule: 3D资源模块
ServeStaticModule: 静态文件服务

启动流程:

创建NestJS应用实例
配置全局拦截器和过滤器
配置请求体解析
监听指定端口
记录启动日志

4. 配置文件 (config.ts)

功能: 应用配置管理

配置项:

port: 服务器端口
数据存储路径
日志配置
其他运行时配置

5. 公共模块 (common/)

功能: 提供公共类型和工具类

PageData.ts

分页数据类型定义

interface PageData<T> {
  data: T[] // 数据列表
  total: number // 总数
  page: number // 当前页码
  pageSize: number // 每页大小
}

Result.ts

统一响应结果类型

interface Result<T = any> {
  success: boolean // 是否成功
  data?: T // 响应数据
  message?: string // 消息
  code?: number // 错误代码
}

6. 业务数据模块 (data/)

功能: 管理业务数据（设备、测量、属性、字典等）

Controller层

控制器列表:

AttributeController: 属性管理
DeviceController: 设备管理
DeviceMeasureController: 设备测量关联
DictionaryController: 字典管理
MeasureController: 测量管理
ModelAttributeController: 模型属性关联
ModelDeviceController: 模型设备关联
ModelMeasureController: 模型测量关联
StationController: 站点管理

Entity层

实体列表:

Attribute: 属性实体
Device: 设备实体
DeviceMeasure: 设备测量关联实体
Dictionary: 字典实体
DictionaryItem: 字典项实体
Measure: 测量实体
ModelAttribute: 模型属性关联实体
ModelDevice: 模型设备关联实体
ModelMeasure: 模型测量关联实体
Station: 站点实体

Service层

服务列表:

AttributeService: 属性服务
DeviceService: 设备服务
DeviceMeasureService: 设备测量关联服务
DictionaryService: 字典服务
DictionaryItemService: 字典项服务
MeasureService: 测量服务
ModelAttributeService: 模型属性关联服务
ModelDeviceService: 模型设备关联服务
ModelMeasureService: 模型测量关联服务
StationService: 站点服务

主要功能:

业务数据的CRUD操作
数据关联管理
分页查询
条件筛选
数据验证

示例API:

POST /api/device/add          # 添加设备
POST /api/device/update       # 更新设备
POST /api/device/delete       # 删除设备
POST /api/device/list         # 设备列表
POST /api/device/detail       # 设备详情

7. 3D资源模块 (three/)

功能: 管理3D资源（场景、模型、材质、动画等）

Controller层

控制器列表:

SceneController: 场景管理
MeshController: 模型管理
MaterialController: 材质管理
AnimationController: 动画管理
AudioController: 音频管理
VideoController: 视频管理
MapController: 贴图管理
TypefaceController: 字体管理
ScreenshotController: 截图管理
ThumbnailController: 缩略图管理
CategoryController: 分类管理
FileController: 文件访问
DownloadController: 文件下载
SummaryController: 资源汇总

Entity层

实体列表:

Scene: 场景实体
Mesh: 模型实体
Material: 材质实体
Animation: 动画实体
Audio: 音频实体
Video: 视频实体
Map: 贴图实体
Typeface: 字体实体
Screenshot: 截图实体
Thumbnail: 缩略图实体
Category: 分类实体
Summary: 汇总实体
BaseEntity: 基础实体
BaseFileEntity: 基础文件实体

基础实体:

interface BaseEntity {
  id?: string // 实体ID
  name?: string // 实体名称
  categoryId?: string // 分类ID
  createTime?: string // 创建时间
  updateTime?: string // 更新时间
}

interface BaseFileEntity extends BaseEntity {
  filename?: string // 文件名
  size?: number // 文件大小
  type?: string // 文件类型
  url?: string // 下载地址
  thumbnail?: string // 缩略图
}

Service层

服务列表:

SceneService: 场景服务
MeshService: 模型服务
MaterialService: 材质服务
AnimationService: 动画服务
AudioService: 音频服务
VideoService: 视频服务
MapService: 贴图服务
TypefaceService: 字体服务
ScreenshotService: 截图服务
ThumbnailService: 缩略图服务
CategoryService: 分类服务
FileService: 文件服务
DownloadService: 下载服务
SummaryService: 汇总服务
BaseEntityService: 基础实体服务
BaseFileService: 基础文件服务

主要功能:

3D资源的CRUD操作
文件上传和下载
文件访问控制
缩略图生成
分类管理
资源汇总统计

示例API:

POST /api/scene/add           # 添加场景
POST /api/scene/update        # 更新场景
POST /api/scene/delete        # 删除场景
POST /api/scene/list          # 场景列表
POST /api/scene/detail        # 场景详情
GET  /api/file/scene/{id}     # 访问场景文件
GET  /api/download/scene/{id} # 下载场景文件

8. 异常过滤器 (filter/)

AllExceptionsFilter

功能: 全局异常处理，统一错误响应格式

主要功能:

捕获所有异常
统一错误响应格式
记录错误日志
友好的错误提示

错误响应格式:

{
  "success": false,
  "code": 500,
  "message": "错误信息"
}

9. 拦截器 (interceptor/)

LoggingInterceptor

功能: 请求日志记录

主要功能:

记录所有HTTP请求
记录请求方法和URL
记录请求耗时
记录响应状态

10. 管道 (pipe/)

FileNameEncodePipe

功能: 文件名编码处理

主要功能:

处理文件名编码
防止文件名冲突
支持中文文件名

11. 工具函数 (utils/)

TimeUtils

功能: 时间处理工具

主要功能:

时间格式化
时间计算
时间戳转换

API接口规范

请求格式

所有API请求使用RESTful风格：

GET: 获取数据
POST: 创建或更新数据
DELETE: 删除数据

响应格式

所有API响应包含统一的Result结构：

{
  "success": true,
  "data": {},
  "message": "操作成功",
  "code": 0
}

分页请求

分页请求参数：

{
  page: number      // 页码，从0开始
  pageSize: number  // 每页大小
  keyword?: string  // 关键字搜索（可选）
  categoryId?: string  // 分类ID（可选）
}

分页响应

分页响应数据：

{
  data: [],        // 数据列表
  total: 100,      // 总数
  page: 0,        // 当前页码
  pageSize: 20     // 每页大小
}

文件存储

存储结构

data/
├── scene/          # 场景文件
├── mesh/           # 模型文件
├── material/       # 材质文件
├── animation/      # 动画文件
├── audio/          # 音频文件
├── video/          # 视频文件
├── map/            # 贴图文件
├── typeface/       # 字体文件
├── screenshot/    # 截图文件
└── thumbnail/      # 缩略图文件

文件上传

支持单文件和批量上传：

// 单文件上传
POST /api/mesh/add
Content-Type: multipart/form-data
Body: file=...

// 批量上传（多个文件）
POST /api/mesh/add
Content-Type: multipart/form-data
Body: files=...

文件访问

文件访问接口：

GET /api/file/{type}/{filename}

示例:

GET /api/file/mesh/cube.gltf
GET /api/file/scene/scene001.json
GET /api/file/texture/brick.jpg

文件下载

文件下载接口：

GET /api/download/{type}/{id}

示例:

GET /api/download/mesh/1
GET /api/download/scene/5

NestJS模块架构

模块组织

AppModule (根模块)
├── DataModule (业务数据模块)
│   ├── AttributeController
│   ├── DeviceController
│   ├── MeasureController
│   └── ...
├── ThreeModule (3D资源模块)
│   ├── SceneController
│   ├── MeshController
│   ├── MaterialController
│   └── ...
└── ServeStaticModule (静态文件服务)

依赖注入

NestJS使用依赖注入（DI）来管理服务和控制器：

@Controller('scene')
export class SceneController {
  constructor(private readonly sceneService: SceneService) {}

  @Post('add')
  add(@Body() data: SceneDto) {
    return this.sceneService.add(data)
  }
}

装饰器说明

常用装饰器

@Controller('path'): 定义控制器路由前缀
@Get('path'): GET请求
@Post('path'): POST请求
@Delete('path'): DELETE请求
@Body(): 获取请求体
@Query(): 获取查询参数
@Param('id'): 获取路径参数
@UsePipes(): 使用管道
@UseGuards(): 使用守卫
@UseInterceptors(): 使用拦截器

示例:

@Controller('scene')
export class SceneController {
  @Post('add')
  add(@Body() body: any) {
    // ...
  }

  @Get(':id')
  detail(@Param('id') id: string) {
    // ...
  }

  @Post('list')
  list(@Body() body: { page: number; pageSize: number }) {
    // ...
  }
}

错误代码

代码	说明
0	成功
400	请求参数错误
401	未授权
404	资源不存在
500	服务器内部错误

日志系统

日志级别

fatal: 致命错误
error: 错误
warn: 警告
log: 一般日志
debug: 调试信息
verbose: 详细信息

日志记录

import log from 'electron-log/main'

log.info('信息日志')
log.warn('警告日志')
log.error('错误日志')

开发和部署

开发环境

# 启动开发环境
npm run dev

# 启动后端
npm run dev:electron

生产环境

# 构建
npm run build

# 打包Electron应用
npm run build:electron

环境变量

NODE_ENV: 运行环境（development/production）
端口配置在config.ts中

安全性

CORS配置

已在NestJS中配置CORS，允许跨域访问。

文件安全

文件上传大小限制：200MB
支持的文件类型：在服务层验证
文件名编码：防止路径遍历攻击

IPC安全

启用contextIsolation
禁用nodeIntegration
预加载脚本暴露安全的API

性能优化

静态文件缓存: 使用NestJS静态文件服务，支持缓存
请求压缩: 配置body-parser压缩
日志异步: 使用异步日志记录
文件流传输: 大文件使用流式传输

测试

单元测试

测试文件位于__tests__/目录。

# 运行测试
npm test

测试覆盖

Controller层测试
Service层测试
工具函数测试

常见问题

Q: 如何添加新的API接口？

A: 在对应的Module中添加Controller和Service：

在controller/目录创建Controller
在service/目录创建Service
在Module中注册Controller

Q: 如何修改文件存储路径？

A: 修改config.ts中的配置，或修改Service中的路径处理。

Q: 如何添加新的资源类型？

在three/entity/创建实体
在three/controller/创建控制器
在three/service/创建服务
在ThreeModule中注册

Q: 如何添加全局中间件？

A: 在server.ts的bootstrap函数中使用：

app.use(middleware)

更新日志

v0.0.1 (2024-10-19)

初始版本
完整的后端架构文档
所有模块说明
API接口规范

技术栈

目录结构概览

1. Electron主进程 (main.ts)

2. 预加载脚本 (preload.ts)

3. 服务启动 (server.ts)

4. 配置文件 (config.ts)

5. 公共模块 (common/)

PageData.ts

Result.ts

6. 业务数据模块 (data/)

Controller层

Entity层

Service层

7. 3D资源模块 (three/)

Controller层

Entity层

Service层

8. 异常过滤器 (filter/)

AllExceptionsFilter

9. 拦截器 (interceptor/)

LoggingInterceptor

10. 管道 (pipe/)

FileNameEncodePipe

11. 工具函数 (utils/)

TimeUtils

API接口规范

请求格式

响应格式

分页请求

分页响应

文件存储

存储结构

文件上传

文件访问

文件下载

NestJS模块架构

模块组织

依赖注入

装饰器说明

常用装饰器

错误代码

日志系统

日志级别

日志记录

开发和部署

开发环境

生产环境

环境变量

安全性

CORS配置

文件安全

IPC安全

性能优化

测试

单元测试

测试覆盖

常见问题

Q: 如何添加新的API接口？

Q: 如何修改文件存储路径？

Q: 如何添加新的资源类型？

Q: 如何添加全局中间件？

相关文档

更新日志

v0.0.1 (2024-10-19)

推荐阅读

超腾开源平台用户手册

XWiki知识库使用手册

超腾开源平台

超腾开源平台仪表盘模块

超腾开源平台网站模块

XWiki知识库

评论 (0)

发表评论

邮件订阅

文档大纲