306 lines
13 KiB
Markdown
306 lines
13 KiB
Markdown
# 材质删除
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go)
|
||
- [internal/repository/texture_repository.go](file://internal/repository/texture_repository.go)
|
||
- [internal/model/texture.go](file://internal/model/texture.go)
|
||
- [internal/handler/texture_handler.go](file://internal/handler/texture_handler.go)
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go)
|
||
- [internal/service/texture_service_test.go](file://internal/service/texture_service_test.go)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
|
||
## 简介
|
||
本专项文档聚焦“材质删除”API，围绕删除操作的权限验证机制展开，结合服务层与仓储层的实现，说明删除流程、成功响应、错误场景，以及删除对数据库记录的影响（软删除）与关联数据处理（收藏关系）。同时基于测试用例，确认删除权限校验逻辑与行为一致性。
|
||
|
||
## 项目结构
|
||
与材质删除相关的代码分布在以下模块：
|
||
- 路由注册：定义DELETE /api/v1/texture/:id接口
|
||
- 处理器：解析参数、鉴权、调用服务层并返回响应
|
||
- 服务层：执行业务规则（权限校验、存在性校验）、调用仓储层
|
||
- 仓储层：执行数据库操作（软删除）
|
||
- 数据模型：定义材质实体、收藏关系、下载日志等
|
||
|
||
```mermaid
|
||
graph TB
|
||
Routes["路由注册<br/>routes.go"] --> Handler["处理器<br/>texture_handler.go"]
|
||
Handler --> Service["服务层<br/>texture_service.go"]
|
||
Service --> Repo["仓储层<br/>texture_repository.go"]
|
||
Repo --> Model["数据模型<br/>texture.go"]
|
||
```
|
||
|
||
图表来源
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L42-L61)
|
||
- [internal/handler/texture_handler.go](file://internal/handler/texture_handler.go#L371-L419)
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L143-L160)
|
||
- [internal/repository/texture_repository.go](file://internal/repository/texture_repository.go#L126-L130)
|
||
- [internal/model/texture.go](file://internal/model/texture.go#L16-L35)
|
||
|
||
章节来源
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L42-L61)
|
||
- [internal/handler/texture_handler.go](file://internal/handler/texture_handler.go#L371-L419)
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L143-L160)
|
||
- [internal/repository/texture_repository.go](file://internal/repository/texture_repository.go#L126-L130)
|
||
- [internal/model/texture.go](file://internal/model/texture.go#L16-L35)
|
||
|
||
## 核心组件
|
||
- 路由与鉴权
|
||
- DELETE /api/v1/texture/:id 由处理器绑定，使用鉴权中间件，要求携带有效令牌。
|
||
- 处理器
|
||
- 解析路径参数（材质ID），从上下文提取当前用户ID，调用服务层执行删除，并按错误码返回相应HTTP状态与响应体。
|
||
- 服务层
|
||
- 校验材质存在性；校验删除权限（仅上传者可删）；调用仓储层执行软删除。
|
||
- 仓储层
|
||
- 将材质记录的status字段置为-1，实现软删除。
|
||
- 数据模型
|
||
- 材质实体包含UploaderID、Status等字段；收藏关系通过user_texture_favorites表维护。
|
||
|
||
章节来源
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L42-L61)
|
||
- [internal/handler/texture_handler.go](file://internal/handler/texture_handler.go#L371-L419)
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L143-L160)
|
||
- [internal/repository/texture_repository.go](file://internal/repository/texture_repository.go#L126-L130)
|
||
- [internal/model/texture.go](file://internal/model/texture.go#L16-L35)
|
||
|
||
## 架构总览
|
||
下图展示从客户端到数据库的完整调用链路，包括鉴权、参数解析、权限校验、软删除与响应返回。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant R as "路由(routes.go)"
|
||
participant H as "处理器(texture_handler.go)"
|
||
participant S as "服务层(texture_service.go)"
|
||
participant P as "仓储层(texture_repository.go)"
|
||
participant D as "数据库"
|
||
C->>R : "DELETE /api/v1/texture/ : id"
|
||
R->>H : "进入处理器"
|
||
H->>H : "解析路径参数/校验JWT"
|
||
H->>S : "service.DeleteTexture(db, textureID, uploaderID)"
|
||
S->>P : "FindTextureByID(textureID)"
|
||
P-->>S : "返回材质或nil"
|
||
alt "材质不存在"
|
||
S-->>H : "返回错误：材质不存在"
|
||
H-->>C : "403 错误响应"
|
||
else "材质存在"
|
||
S->>S : "校验 uploaderID == 请求者ID"
|
||
alt "非上传者"
|
||
S-->>H : "返回错误：无权删除此材质"
|
||
H-->>C : "403 错误响应"
|
||
else "上传者本人"
|
||
S->>P : "DeleteTexture(textureID)"
|
||
P->>D : "UPDATE textures SET status=-1 WHERE id=..."
|
||
D-->>P : "OK"
|
||
P-->>S : "OK"
|
||
S-->>H : "OK"
|
||
H-->>C : "200 成功响应"
|
||
end
|
||
end
|
||
```
|
||
|
||
图表来源
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L42-L61)
|
||
- [internal/handler/texture_handler.go](file://internal/handler/texture_handler.go#L371-L419)
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L143-L160)
|
||
- [internal/repository/texture_repository.go](file://internal/repository/texture_repository.go#L126-L130)
|
||
|
||
## 详细组件分析
|
||
|
||
### 删除API请求流程与权限验证
|
||
- 路由与鉴权
|
||
- DELETE /api/v1/texture/:id 由处理器绑定，使用鉴权中间件，要求携带有效令牌。
|
||
- 参数解析与鉴权
|
||
- 处理器从路径参数解析材质ID，从上下文提取当前用户ID；若缺失则返回未授权。
|
||
- 权限验证
|
||
- 服务层先查询材质是否存在且未被软删除；
|
||
- 再校验请求者ID与材质的UploaderID一致，否则返回无权删除。
|
||
- 执行删除
|
||
- 通过仓储层将材质记录的status字段置为-1，完成软删除。
|
||
- 响应
|
||
- 成功返回200与通用成功响应体；错误返回403及错误信息。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始"]) --> Parse["解析路径参数<br/>获取材质ID"]
|
||
Parse --> Auth{"JWT鉴权通过？"}
|
||
Auth --> |否| Resp401["返回401 未授权"]
|
||
Auth --> |是| Load["查询材质记录"]
|
||
Load --> Exists{"是否存在且未软删除？"}
|
||
Exists --> |否| Resp403a["返回403 材质不存在/已删除"]
|
||
Exists --> |是| Perm{"请求者ID==上传者ID？"}
|
||
Perm --> |否| Resp403b["返回403 无权删除此材质"]
|
||
Perm --> |是| SoftDel["软删除：设置status=-1"]
|
||
SoftDel --> Resp200["返回200 成功"]
|
||
Resp401 --> End(["结束"])
|
||
Resp403a --> End
|
||
Resp403b --> End
|
||
Resp200 --> End
|
||
```
|
||
|
||
图表来源
|
||
- [internal/handler/texture_handler.go](file://internal/handler/texture_handler.go#L371-L419)
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L143-L160)
|
||
- [internal/repository/texture_repository.go](file://internal/repository/texture_repository.go#L126-L130)
|
||
|
||
章节来源
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L42-L61)
|
||
- [internal/handler/texture_handler.go](file://internal/handler/texture_handler.go#L371-L419)
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L143-L160)
|
||
- [internal/repository/texture_repository.go](file://internal/repository/texture_repository.go#L126-L130)
|
||
|
||
### 权限验证机制
|
||
- 上传者身份判定
|
||
- 服务层比较请求者的用户ID与材质记录中的UploaderID，仅当两者相等时才允许删除。
|
||
- 存在性与状态校验
|
||
- 查询材质时会忽略status=-1的记录（软删除），因此若返回nil，即视为“不存在”。
|
||
- 测试覆盖
|
||
- 单元测试包含“删除权限检查”的用例，验证相同ID允许删除、不同ID拒绝删除的行为。
|
||
|
||
章节来源
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L143-L160)
|
||
- [internal/service/texture_service_test.go](file://internal/service/texture_service_test.go#L315-L345)
|
||
|
||
### 删除API的成功响应与错误情况
|
||
- 成功响应
|
||
- HTTP 200，返回通用成功响应体（无额外数据）。
|
||
- 常见错误
|
||
- 401 未授权：缺少或无效的JWT令牌。
|
||
- 400 参数错误：材质ID格式非法。
|
||
- 403 无权删除：请求者非材质上传者。
|
||
- 403 材质不存在：目标材质不存在或已被软删除。
|
||
- 处理器侧错误分支
|
||
- 参数解析失败返回400；
|
||
- 服务层返回错误时统一转换为403（无权删除/不存在）。
|
||
|
||
章节来源
|
||
- [internal/handler/texture_handler.go](file://internal/handler/texture_handler.go#L371-L419)
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L143-L160)
|
||
|
||
### 数据库记录影响与关联数据处理
|
||
- 删除策略
|
||
- 采用软删除：将textures表的status字段置为-1，不物理移除记录。
|
||
- 影响范围
|
||
- 材质记录仍保留，便于审计与历史追踪；
|
||
- 查询接口（如获取详情、搜索、我的材质）均会忽略status=-1的记录。
|
||
- 关联数据
|
||
- 收藏关系：删除操作不直接清理user_texture_favorites表中的收藏记录；
|
||
- 若需清理收藏，应在业务层面另行设计或在仓储层扩展软删除时级联处理（当前实现未体现）。
|
||
- 下载日志
|
||
- 删除操作不涉及texture_download_logs表的清理。
|
||
|
||
章节来源
|
||
- [internal/repository/texture_repository.go](file://internal/repository/texture_repository.go#L126-L130)
|
||
- [internal/model/texture.go](file://internal/model/texture.go#L16-L35)
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L66-L79)
|
||
|
||
### 类图（代码级）
|
||
```mermaid
|
||
classDiagram
|
||
class Texture {
|
||
+int64 id
|
||
+int64 uploader_id
|
||
+string name
|
||
+string description
|
||
+TextureType type
|
||
+string url
|
||
+string hash
|
||
+int size
|
||
+bool is_public
|
||
+int download_count
|
||
+int favorite_count
|
||
+bool is_slim
|
||
+int16 status
|
||
+time created_at
|
||
+time updated_at
|
||
}
|
||
class UserTextureFavorite {
|
||
+int64 id
|
||
+int64 user_id
|
||
+int64 texture_id
|
||
+time created_at
|
||
}
|
||
class TextureDownloadLog {
|
||
+int64 id
|
||
+int64 texture_id
|
||
+*int64 user_id
|
||
+string ip_address
|
||
+string user_agent
|
||
+time created_at
|
||
}
|
||
Texture --> UserTextureFavorite : "收藏关系"
|
||
Texture --> TextureDownloadLog : "下载日志"
|
||
```
|
||
|
||
图表来源
|
||
- [internal/model/texture.go](file://internal/model/texture.go#L16-L35)
|
||
- [internal/model/texture.go](file://internal/model/texture.go#L42-L57)
|
||
- [internal/model/texture.go](file://internal/model/texture.go#L60-L71)
|
||
|
||
## 依赖分析
|
||
- 组件耦合
|
||
- 处理器依赖服务层；服务层依赖仓储层；仓储层依赖数据库访问工具。
|
||
- 关键依赖链
|
||
- 路由 -> 处理器 -> 服务层 -> 仓储层 -> 数据库
|
||
- 可能的循环依赖
|
||
- 当前文件间未发现循环导入；各层职责清晰，符合分层架构。
|
||
|
||
```mermaid
|
||
graph LR
|
||
Routes["routes.go"] --> Handler["texture_handler.go"]
|
||
Handler --> Service["texture_service.go"]
|
||
Service --> Repo["texture_repository.go"]
|
||
Repo --> DB["数据库"]
|
||
```
|
||
|
||
图表来源
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L42-L61)
|
||
- [internal/handler/texture_handler.go](file://internal/handler/texture_handler.go#L371-L419)
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L143-L160)
|
||
- [internal/repository/texture_repository.go](file://internal/repository/texture_repository.go#L126-L130)
|
||
|
||
章节来源
|
||
- [internal/handler/routes.go](file://internal/handler/routes.go#L42-L61)
|
||
- [internal/handler/texture_handler.go](file://internal/handler/texture_handler.go#L371-L419)
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L143-L160)
|
||
- [internal/repository/texture_repository.go](file://internal/repository/texture_repository.go#L126-L130)
|
||
|
||
## 性能考虑
|
||
- 查询与软删除
|
||
- 删除前的查询与软删除均为单记录操作，复杂度低。
|
||
- 索引与过滤
|
||
- 材质查询通常按UploaderID、状态、公开性等条件过滤，建议确保相关列具备索引以提升查询效率。
|
||
- 批量与事务
|
||
- 当前删除为单条记录操作，无需事务；若未来扩展批量删除，需评估事务边界与回滚策略。
|
||
|
||
## 故障排查指南
|
||
- 401 未授权
|
||
- 检查请求头Authorization是否携带有效JWT；确认中间件已正确注入user_id。
|
||
- 400 参数错误
|
||
- 检查路径参数id是否为合法整数。
|
||
- 403 无权删除
|
||
- 确认当前用户ID与材质记录的UploaderID一致；核对服务层权限校验逻辑。
|
||
- 403 材质不存在
|
||
- 确认材质ID有效且未被软删除；检查仓储层查询是否正确忽略status=-1。
|
||
- 日志定位
|
||
- 处理器与服务层均记录错误日志，可据此快速定位问题。
|
||
|
||
章节来源
|
||
- [internal/handler/texture_handler.go](file://internal/handler/texture_handler.go#L371-L419)
|
||
- [internal/service/texture_service.go](file://internal/service/texture_service.go#L143-L160)
|
||
|
||
## 结论
|
||
- 权限验证严格：仅上传者可删除材质，服务层明确校验请求者ID与UploaderID一致性。
|
||
- 删除策略为软删除：通过status字段标记删除，不破坏历史数据与关联完整性。
|
||
- 错误处理清晰：处理器将服务层错误映射为403，配合日志便于排障。
|
||
- 关联清理：当前实现未清理收藏关系，如需可在业务层补充或扩展仓储层软删除逻辑。 |