365 lines
15 KiB
Markdown
365 lines
15 KiB
Markdown
# 档案服务
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [profile_service.go](file://internal/service/profile_service.go)
|
||
- [profile_repository.go](file://internal/repository/profile_repository.go)
|
||
- [profile.go](file://internal/model/profile.go)
|
||
- [user.go](file://internal/model/user.go)
|
||
- [texture.go](file://internal/model/texture.go)
|
||
- [profile_handler.go](file://internal/handler/profile_handler.go)
|
||
- [common.go](file://internal/types/common.go)
|
||
- [profile_service_test.go](file://internal/service/profile_service_test.go)
|
||
- [profile_handler_test.go](file://internal/handler/profile_handler_test.go)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本档“档案服务”文档聚焦于 ProfileService 的职责、方法与内部逻辑，覆盖档案的创建、更新、删除与活跃状态管理；明确档案名称与用户ID的验证规则（名称非空且长度1-16，用户ID大于0），以及状态有效性判断（仅当状态为1时表示正常可用）；阐述新创建档案默认为活跃状态的业务规则，并说明多档案用户的活跃档案切换逻辑；解释档案与用户、材质之间的关联关系；最后提供常见错误场景的排查指南，帮助开发者快速定位问题。
|
||
|
||
## 项目结构
|
||
档案服务位于 internal/service 层，通过 internal/handler 接收HTTP请求，调用 ProfileService 完成业务逻辑，再由 ProfileService 调用 internal/repository 访问数据库；数据模型定义在 internal/model 中，类型定义在 internal/types 中。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "接口层"
|
||
H["profile_handler.go<br/>HTTP处理器"]
|
||
end
|
||
subgraph "服务层"
|
||
S["profile_service.go<br/>ProfileService"]
|
||
end
|
||
subgraph "仓储层"
|
||
R["profile_repository.go<br/>Profile仓储"]
|
||
end
|
||
subgraph "模型层"
|
||
M1["profile.go<br/>Profile模型"]
|
||
M2["user.go<br/>User模型"]
|
||
M3["texture.go<br/>Texture模型"]
|
||
end
|
||
subgraph "类型定义"
|
||
T["common.go<br/>CreateProfileRequest/UpdateProfileRequest/ProfileInfo"]
|
||
end
|
||
H --> S
|
||
S --> R
|
||
R --> M1
|
||
R --> M2
|
||
R --> M3
|
||
H --> T
|
||
```
|
||
|
||
图表来源
|
||
- [profile_handler.go](file://internal/handler/profile_handler.go#L1-L399)
|
||
- [profile_service.go](file://internal/service/profile_service.go#L1-L253)
|
||
- [profile_repository.go](file://internal/repository/profile_repository.go#L1-L200)
|
||
- [profile.go](file://internal/model/profile.go#L1-L64)
|
||
- [user.go](file://internal/model/user.go#L1-L71)
|
||
- [texture.go](file://internal/model/texture.go#L1-L77)
|
||
- [common.go](file://internal/types/common.go#L81-L207)
|
||
|
||
章节来源
|
||
- [profile_handler.go](file://internal/handler/profile_handler.go#L1-L399)
|
||
- [profile_service.go](file://internal/service/profile_service.go#L1-L253)
|
||
- [profile_repository.go](file://internal/repository/profile_repository.go#L1-L200)
|
||
- [profile.go](file://internal/model/profile.go#L1-L64)
|
||
- [user.go](file://internal/model/user.go#L1-L71)
|
||
- [texture.go](file://internal/model/texture.go#L1-L77)
|
||
- [common.go](file://internal/types/common.go#L81-L207)
|
||
|
||
## 核心组件
|
||
- ProfileService：负责档案的创建、查询、更新、删除、活跃状态设置与数量限制检查等核心业务逻辑。
|
||
- ProfileRepository：封装数据库访问，包括创建、查询、更新、删除、统计、设置活跃状态等。
|
||
- Profile 模型：定义档案的数据结构及与用户、材质的关联。
|
||
- Handler：接收HTTP请求，解析参数，调用服务层并返回统一响应。
|
||
- 类型定义：CreateProfileRequest、UpdateProfileRequest、ProfileInfo 等用于API契约与响应结构。
|
||
|
||
章节来源
|
||
- [profile_service.go](file://internal/service/profile_service.go#L1-L253)
|
||
- [profile_repository.go](file://internal/repository/profile_repository.go#L1-L200)
|
||
- [profile.go](file://internal/model/profile.go#L1-L64)
|
||
- [profile_handler.go](file://internal/handler/profile_handler.go#L1-L399)
|
||
- [common.go](file://internal/types/common.go#L81-L207)
|
||
|
||
## 架构总览
|
||
档案服务采用典型的三层架构：Handler 负责接口与参数校验，Service 负责业务规则与流程编排，Repository 负责数据持久化。ProfileService 在创建档案时会进行用户存在性与状态校验、角色名唯一性校验、生成UUID与RSA密钥、创建档案并将其设置为活跃状态；在设置活跃状态时，通过事务将该用户下的其他档案全部置为非活跃，确保同一时刻仅有一个活跃档案。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant H as "Handler"
|
||
participant S as "ProfileService"
|
||
participant R as "ProfileRepository"
|
||
participant DB as "数据库"
|
||
C->>H : "POST /api/v1/profile"
|
||
H->>H : "解析请求体(CreateProfileRequest)"
|
||
H->>S : "CheckProfileLimit(userID, maxProfiles)"
|
||
S->>R : "CountProfilesByUserID(userID)"
|
||
R-->>S : "count"
|
||
S-->>H : "通过/错误"
|
||
H->>S : "CreateProfile(userID, name)"
|
||
S->>R : "FindUserByID(userID)"
|
||
R-->>S : "User"
|
||
S->>R : "FindProfileByName(name)"
|
||
R-->>S : "Profile 或 NotFound"
|
||
S->>S : "生成UUID与RSA私钥"
|
||
S->>R : "CreateProfile(Profile)"
|
||
R->>DB : "INSERT"
|
||
DB-->>R : "OK"
|
||
S->>R : "SetActiveProfile(uuid, userID)"
|
||
R->>DB : "事务 : 先将用户其他档案置为非活跃，再将目标置为活跃"
|
||
DB-->>R : "OK"
|
||
R-->>S : "OK"
|
||
S-->>H : "Profile"
|
||
H-->>C : "200 成功响应"
|
||
```
|
||
|
||
图表来源
|
||
- [profile_handler.go](file://internal/handler/profile_handler.go#L28-L93)
|
||
- [profile_service.go](file://internal/service/profile_service.go#L17-L68)
|
||
- [profile_repository.go](file://internal/repository/profile_repository.go#L13-L109)
|
||
|
||
## 详细组件分析
|
||
|
||
### ProfileService 方法与职责
|
||
- 创建档案
|
||
- 输入：用户ID、档案名称
|
||
- 校验：用户存在且状态为1；档案名称唯一；名称长度1-16
|
||
- 生成：UUID、RSA私钥（PEM格式）
|
||
- 写入：创建档案记录，默认 IsActive=true
|
||
- 并发安全：通过事务将该用户下其他档案置为非活跃，确保仅一个活跃档案
|
||
- 获取档案详情
|
||
- 输入：档案UUID
|
||
- 输出：Profile（预加载Skin与Cape）
|
||
- 获取用户档案列表
|
||
- 输入：用户ID
|
||
- 输出：Profile 列表（按创建时间倒序）
|
||
- 更新档案
|
||
- 输入：UUID、用户ID、可选名称、可选SkinID、可选CapeID
|
||
- 校验：权限（档案属于当前用户）、名称唯一性（若更改）
|
||
- 更新：保存变更并重新加载以返回最新数据
|
||
- 删除档案
|
||
- 输入：UUID、用户ID
|
||
- 校验：权限
|
||
- 删除：物理删除档案
|
||
- 设置活跃档案
|
||
- 输入：UUID、用户ID
|
||
- 校验：权限
|
||
- 事务：将该用户下其他档案置为非活跃，再将目标置为活跃
|
||
- 同步：更新最后使用时间
|
||
- 档案数量限制
|
||
- 输入：用户ID、最大数量
|
||
- 校验：统计当前档案数是否达到上限
|
||
- 校验档案归属
|
||
- 输入：用户ID、档案UUID
|
||
- 校验：UUID存在且属于该用户
|
||
- 名称批量查询
|
||
- 输入：名称数组
|
||
- 输出：Profile 列表
|
||
- 密钥对查询
|
||
- 输入：档案ID
|
||
- 输出：KeyPair（私钥、公钥、过期时间等）
|
||
|
||
章节来源
|
||
- [profile_service.go](file://internal/service/profile_service.go#L17-L253)
|
||
- [profile_repository.go](file://internal/repository/profile_repository.go#L13-L177)
|
||
- [profile.go](file://internal/model/profile.go#L1-L64)
|
||
|
||
### 数据模型与关联关系
|
||
- Profile
|
||
- 字段：UUID、UserID、Name、SkinID、CapeID、RSAPrivateKey、IsActive、LastUsedAt、CreatedAt、UpdatedAt
|
||
- 关联：User（外键 UserID）、Texture（SkinID、CapeID）
|
||
- User
|
||
- 字段：ID、Username、Email、Role、Status（1: 正常, 0: 禁用, -1: 删除）
|
||
- Texture
|
||
- 字段：ID、UploaderID、Name、Type、URL、Hash、IsPublic、DownloadCount、FavoriteCount、IsSlim、Status（1: 正常, 0: 审核中, -1: 已删除）
|
||
|
||
```mermaid
|
||
erDiagram
|
||
USER {
|
||
bigint id PK
|
||
varchar username UK
|
||
varchar email UK
|
||
smallint status
|
||
}
|
||
PROFILE {
|
||
varchar uuid PK
|
||
bigint user_id FK
|
||
varchar name UK
|
||
bigint skin_id
|
||
bigint cape_id
|
||
boolean is_active
|
||
timestamp last_used_at
|
||
timestamp created_at
|
||
timestamp updated_at
|
||
}
|
||
TEXTURE {
|
||
bigint id PK
|
||
bigint uploader_id FK
|
||
varchar name
|
||
varchar type
|
||
varchar url
|
||
varchar hash UK
|
||
boolean is_public
|
||
integer download_count
|
||
integer favorite_count
|
||
boolean is_slim
|
||
smallint status
|
||
}
|
||
USER ||--o{ PROFILE : "拥有"
|
||
TEXTURE ||--o{ PROFILE : "被使用(Skin/Cape)"
|
||
```
|
||
|
||
图表来源
|
||
- [profile.go](file://internal/model/profile.go#L1-L64)
|
||
- [user.go](file://internal/model/user.go#L1-L71)
|
||
- [texture.go](file://internal/model/texture.go#L1-L77)
|
||
|
||
### 验证规则与状态判断
|
||
- 档案名称
|
||
- 非空且长度在1-16之间
|
||
- 更新时仅当名称发生变更才检查唯一性
|
||
- 用户ID
|
||
- 必须大于0
|
||
- 用户状态
|
||
- 仅当用户状态为1（正常）时允许创建档案
|
||
- 活跃状态
|
||
- 默认 IsActive=true
|
||
- 仅当状态为1时表示“正常可用”
|
||
- 设置活跃状态时，通过事务将该用户下其他档案置为非活跃
|
||
|
||
章节来源
|
||
- [profile_service.go](file://internal/service/profile_service.go#L17-L68)
|
||
- [profile_service_test.go](file://internal/service/profile_service_test.go#L1-L77)
|
||
- [common.go](file://internal/types/common.go#L81-L207)
|
||
- [user.go](file://internal/model/user.go#L1-L71)
|
||
|
||
### 活跃档案切换逻辑
|
||
- 设计目标：同一用户在同一时刻仅有一个活跃档案
|
||
- 实现方式：在设置活跃档案时，使用数据库事务
|
||
- 先将该用户下所有档案的 IsActive=false
|
||
- 再将目标档案 IsActive=true
|
||
- 最后更新最后使用时间
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始"]) --> Load["加载档案(uuid, userID)"]
|
||
Load --> CheckPerm{"权限校验通过？"}
|
||
CheckPerm --> |否| ErrPerm["返回无权操作"]
|
||
CheckPerm --> |是| Txn["开启事务"]
|
||
Txn --> SetAllFalse["将用户其他档案置为非活跃"]
|
||
SetAllFalse --> SetTargetTrue["将目标档案置为活跃"]
|
||
SetTargetTrue --> UpdateTime["更新最后使用时间"]
|
||
UpdateTime --> Commit["提交事务"]
|
||
Commit --> Done(["结束"])
|
||
ErrPerm --> Done
|
||
```
|
||
|
||
图表来源
|
||
- [profile_service.go](file://internal/service/profile_service.go#L161-L188)
|
||
- [profile_repository.go](file://internal/repository/profile_repository.go#L89-L109)
|
||
|
||
### API 与错误处理
|
||
- 创建档案
|
||
- 请求体：CreateProfileRequest（仅需 name，长度1-16）
|
||
- 成功：返回 ProfileInfo（含 UUID、UserID、Name、IsActive、时间戳等）
|
||
- 常见错误：未授权、参数错误、已达上限、服务器错误
|
||
- 获取档案列表/详情
|
||
- 成功：返回 ProfileInfo 列表/对象
|
||
- 常见错误：未授权、服务器错误、档案不存在
|
||
- 更新档案
|
||
- 请求体：UpdateProfileRequest（可选 name、skin_id、cape_id）
|
||
- 成功：返回更新后的 ProfileInfo
|
||
- 常见错误：未授权、参数错误、无权操作、档案不存在、服务器错误
|
||
- 删除档案
|
||
- 成功：返回“删除成功”
|
||
- 常见错误：未授权、无权操作、档案不存在、服务器错误
|
||
- 设置活跃档案
|
||
- 成功：返回“设置成功”
|
||
- 常见错误：未授权、无权操作、档案不存在、服务器错误
|
||
|
||
章节来源
|
||
- [profile_handler.go](file://internal/handler/profile_handler.go#L28-L399)
|
||
- [common.go](file://internal/types/common.go#L81-L207)
|
||
|
||
## 依赖关系分析
|
||
- Handler 依赖 Service
|
||
- Service 依赖 Repository
|
||
- Repository 依赖 Model 与数据库连接
|
||
- Model 间通过外键建立关联
|
||
|
||
```mermaid
|
||
graph LR
|
||
H["profile_handler.go"] --> S["profile_service.go"]
|
||
S --> R["profile_repository.go"]
|
||
R --> M1["profile.go"]
|
||
R --> M2["user.go"]
|
||
R --> M3["texture.go"]
|
||
```
|
||
|
||
图表来源
|
||
- [profile_handler.go](file://internal/handler/profile_handler.go#L1-L399)
|
||
- [profile_service.go](file://internal/service/profile_service.go#L1-L253)
|
||
- [profile_repository.go](file://internal/repository/profile_repository.go#L1-L200)
|
||
- [profile.go](file://internal/model/profile.go#L1-L64)
|
||
- [user.go](file://internal/model/user.go#L1-L71)
|
||
- [texture.go](file://internal/model/texture.go#L1-L77)
|
||
|
||
## 性能考量
|
||
- 查询预加载：获取档案详情与列表时预加载 Skin 与 Cape，减少 N+1 查询风险
|
||
- 事务一致性：设置活跃档案使用事务，保证原子性与一致性
|
||
- 唯一索引：Name 与 Hash 等字段具备唯一索引，降低重复写入成本
|
||
- 时间戳：LastUsedAt 便于后续统计与清理策略
|
||
|
||
[本节为通用建议，不涉及具体文件分析]
|
||
|
||
## 故障排查指南
|
||
- 创建失败
|
||
- 用户不存在或状态异常：检查用户是否存在且状态为1
|
||
- 角色名重复：确认名称唯一性
|
||
- 达到档案数量上限：检查当前用户档案数量与上限配置
|
||
- 数据库错误：查看事务提交与唯一约束冲突
|
||
- 更新失败
|
||
- 无权操作：确认请求用户ID与档案所属用户一致
|
||
- 名称重复：若修改了名称，需确保唯一性
|
||
- 删除失败
|
||
- 无权操作：确认请求用户ID与档案所属用户一致
|
||
- 设置活跃失败
|
||
- 无权操作：确认请求用户ID与档案所属用户一致
|
||
- 事务回滚：检查数据库事务日志
|
||
- 获取失败
|
||
- 档案不存在：确认UUID正确且未被删除
|
||
|
||
章节来源
|
||
- [profile_service.go](file://internal/service/profile_service.go#L17-L253)
|
||
- [profile_repository.go](file://internal/repository/profile_repository.go#L13-L177)
|
||
- [profile_handler.go](file://internal/handler/profile_handler.go#L153-L399)
|
||
|
||
## 结论
|
||
ProfileService 提供了完整的档案生命周期管理能力，涵盖创建、查询、更新、删除与活跃状态切换，并通过严格的验证规则与事务保障确保数据一致性。档案与用户、材质的关联清晰，便于扩展更多功能。建议在生产环境中结合日志与监控，持续优化性能与稳定性。
|
||
|
||
[本节为总结性内容，不涉及具体文件分析]
|
||
|
||
## 附录
|
||
- 关键方法路径参考
|
||
- 创建档案：[CreateProfile](file://internal/service/profile_service.go#L17-L68)
|
||
- 获取档案详情：[GetProfileByUUID](file://internal/service/profile_service.go#L71-L81)
|
||
- 获取用户档案列表：[GetUserProfiles](file://internal/service/profile_service.go#L83-L90)
|
||
- 更新档案：[UpdateProfile](file://internal/service/profile_service.go#L92-L135)
|
||
- 删除档案：[DeleteProfile](file://internal/service/profile_service.go#L137-L159)
|
||
- 设置活跃档案：[SetActiveProfile](file://internal/service/profile_service.go#L161-L188)
|
||
- 数量限制检查：[CheckProfileLimit](file://internal/service/profile_service.go#L190-L202)
|
||
- 校验档案归属：[ValidateProfileByUserID](file://internal/service/profile_service.go#L222-L235)
|
||
- 名称批量查询：[GetProfilesDataByNames](file://internal/service/profile_service.go#L237-L243)
|
||
- 密钥对查询：[GetProfileKeyPair](file://internal/service/profile_service.go#L245-L253)
|
||
- Handler 路由与错误映射
|
||
- 创建/获取/更新/删除/设置活跃：[profile_handler.go](file://internal/handler/profile_handler.go#L28-L399) |