前后端传输数据DTO搭建任务（续）
根据会议讨论确定的基础CRUD部分的Restful API设计方案，我将任务分为以下三个子任务：
- 整理schemas层具体设计表
- 整理路由路径-DTO映射表
- 完成DTO数据结构代码
继上次完成schemas层具体设计表任务后，我又陆续完成了后两个子任务，成果如下：
文章目录
- 前后端传输数据DTO搭建任务（续）
- 一、路由路径-DTO映射表
- 1. 用户模块 (User)
- 2. 文件模块 (File)
- 3. 文件类型模块 (File Type)
- 4. 分析模块 (Analysis)
- 5. 项目模块 (Project)
- 6. 服务模块 (Service)
- 7. 空间转录组模块 (Spatial) & 8. 可视化模块 (Visualization)
- 二、DTO数据结构代码
- 三、个人感悟
一、路由路径-DTO映射表
1. 用户模块 (User)
| 接口路径 | 方法 | 功能 | 请求 DTO | 响应 DTO |
|---|---|---|---|---|
/api/user/register | POST | 用户注册 | UserRegisterRequest | UserRegisterResponse |
/api/user/login | POST | 用户登录 | UserLoginRequest | UserLoginResponse |
/api/user/info | GET | 获取当前用户信息 | - | UserInfoResponse |
/api/user/profile | PUT | 更新用户基础信息 | UserProfileUpdateRequest | UserInfoResponse |
/api/user/password | PUT | 修改密码 | UserPasswordChangeRequest | ApiResponse(通用) |
2. 文件模块 (File)
| 接口路径 | 方法 | 功能 | 请求 DTO | 响应 DTO |
|---|---|---|---|---|
/api/file/upload | POST | 上传文件 | FileUploadRequest | FileUploadResponse |
/api/file/list | GET | 获取文件列表 | - | FileListResponse |
/api/file/{file_id} | GET | 获取文件详情 | FileIdPath(路径参数) | FileDetailResponse |
/api/file/{file_id} | PUT | 更新文件信息 | FileUpdateRequest | FileUpdateResponse |
/api/file/{file_id} | DELETE | 删除文件 | FileIdPath | FileDeleteResponse |
/api/file/{file_id}/children | DELETE | 递归删除子文件 | FileIdPath | ApiResponse(通用) |
/api/file/download/{file_id} | GET | 下载文件 | FileIdPath | 二进制流 |
/api/file/preview/{file_id} | GET | 预览文件 | FileIdPath | 二进制流 |
3. 文件类型模块 (File Type)
| 接口路径 | 方法 | 功能 | 请求 DTO | 响应 DTO |
|---|---|---|---|---|
/api/file-types | GET | 列出文件类型 | - | FileTypeListResponse |
/api/file-types | POST | 创建文件类型 | FileTypeCreateRequest | FileTypeResponse |
/api/file-types/{file_type_id} | PUT | 更新文件类型 | FileTypeUpdateRequest | FileTypeResponse |
/api/file-types/{file_type_id} | DELETE | 删除文件类型 | - | ApiResponse(通用) |
4. 分析模块 (Analysis)
| 接口路径 | 方法 | 功能 | 请求 DTO | 响应 DTO |
|---|---|---|---|---|
/api/analysis/project/{projectId}/tree | GET | 获取项目分析流程树 | - | ProjectAnalysisTreeResponse |
/api/analysis/execution/{executionId} | GET | 获取执行记录详情 | - | ExecutionDetailsResponse |
/api/analysis/execution/{executionId}/status | PUT | 更新执行记录状态 | UpdateAlgorithmStatusRequest | UpdateAlgorithmStatusResponse |
/api/analysis/execution/{executionId} | DELETE | 删除执行记录 | - | ExecutionDeleteResponse |
/api/analysis/analyze | POST | 分析文件 | - | FileAnalysisTreeResponse |
5. 项目模块 (Project)
| 接口路径 | 方法 | 功能 | 请求 DTO | 响应 DTO |
|---|---|---|---|---|
/api/project/ | POST | 创建项目 | ProjectCreateRequest | ProjectResponse |
/api/project/list | GET | 获取项目列表 | - | ProjectListResponse |
/api/project/{project_id}/files-relations | GET | 获取文件关系 | - | ProjectAnalysisTreeResponse |
/api/project/{project_id}/files | GET | 获取项目文件列表 | - | FileListResponse |
/api/project/{project_id} | GET | 获取项目详情 | - | ProjectResponse |
/api/project/{project_id}/detail | GET | 获取项目详细信息(简版) | - | ProjectResponse |
/api/project/{project_id} | PUT | 更新项目信息 | ProjectUpdateRequest | ProjectResponse |
/api/project/{project_id} | DELETE | 删除项目 | - | ApiResponse(通用) |
/api/project/{project_id}/file | POST | 向项目添加文件 | AddFileToProjectRequest | ProjectResponse |
/api/project/{project_id}/file/{file_id} | DELETE | 从项目移除文件 | - | ProjectResponse |
/api/project/{project_id}/service-config | PUT | 更新服务配置 | ProjectServiceConfigRequest | ProjectResponse |
6. 服务模块 (Service)
| 接口路径 | 方法 | 功能 | 请求 DTO | 响应 DTO |
|---|---|---|---|---|
/api/service/ | POST | 创建 Service | ServiceCreateRequest | ServiceResponse |
/api/service/list | GET | 获取 Service 列表 | - | ServiceListResponse |
/api/service/{service_id} | PUT | 更新 Service | ServiceUpdateRequest | ServiceResponse |
/api/service/{service_id} | DELETE | 删除 Service | - | ApiResponse(通用) |
/api/service/{service_id} | GET | 获取 Service 信息 | - | ServiceResponse |
/api/service/queue/status | GET | 获取队列状态 | - | ApiResponse(通用) |
/api/service/{service_id}/execute | POST | 执行 Service | ServiceExecuteRequest | ServiceExecuteResponse |
/api/service/executions/{execution_id} | GET | 获取 Task 记录 | - | ServiceExecutionResponse |
/api/service/executions/ | GET | 获取 Task 记录列表 | - | ServiceExecutionListResponse |
7. 空间转录组模块 (Spatial) & 8. 可视化模块 (Visualization)
| 接口路径 | 方法 | 功能 | 请求 DTO | 响应 DTO |
|---|---|---|---|---|
/api/spatial/{file_id}/image | GET | 获取切片图像 | FileIdPath | GetSliceImageResponse |
/api/spatial/{file_id}/spots | GET | 获取 Spots 位置 | FileIdPath | GetSpotsResponse |
/api/spatial/{file_id}/gene/{gene_name} | GET | 获取基因表达值 | GeneNamePath | GeneExpressionItem |
/api/spatial/{file_id}/genes | GET | 获取基因列表 | SpatialGenesQuery | SpatialGenesResponse |
/api/visualization/{file_id}/types | GET | 获取支持的可视化类型 | - | VisualizationTypesResponse |
/api/visualization/{file_id}/spatial/slice-image | GET | 获取切片图像(通用) | - | SpatialSliceImageResponse |
/api/visualization/{file_id}/spatial/spots | GET | 获取 Spots 位置(通用) | - | SpatialSpotsResponse |
/api/visualization/{file_id}/spatial/gene/{gene_name}/expression | GET | 获取基因表达(通用) | - | SpatialGeneExpressionItem |
/api/visualization/{file_id}/spatial/genes | GET | 获取基因列表(通用) | - | SpatialGenesResponse |
/api/visualization/{file_id}/{visualization_type}/data | GET | 获取通用可视化数据 | VisualizationDataQuery | VisualizationDataResponse |
/api/visualization/query_h5ad_genes | POST | H5AD 原始 QC 预览 | - | ApiResponse(通用) |
/api/visualization/download_h5ad | GET | 下载 H5AD 子集 | - | 二进制流 |
二、DTO数据结构代码
由于代码实现比较简单，详情见gitee仓库，此处不详述了。
三、个人感悟
通过梳理路由接口与DTO的映射关系，我深刻认识到"契约先行"原则在复杂系统开发中的重要性。本次设计不仅完成了基本的CRUD映射，更实现了业务逻辑的系统性梳理和解耦。借助FastAPI等框架的强类型特性，我们将路由参数（如file_id）显式定义为FileIdPath等DTO，实现了参数校验的前置化，既有效拦截了非法请求，又减少了业务层的防御性代码，确保了数据传输安全。
在接口设计上，我们严格区分Request和Response的职责：文件上传请求仅包含必要参数，而响应则封装完整的元数据。这种设计既避免了数据冗余和泄露风险，又实现了逻辑解耦。通过采用通用响应体ApiResponse处理基础状态，同时为复杂业务（如分析流程树）定制专用结构，这种分层策略既保持了接口简洁性，又为未来扩展（如可视化模块）预留了灵活的data字段空间。
经过这次实践，我深刻体会到：通过严谨的数据模型定义来构建高内聚、低耦合的后端服务，是确保系统稳定性和可维护性的关键所在。
