CarrotSkin/backend
4
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a4b6c5011e1c196b6b1095b6f9e0bcd9fe15722b
backend/.qoder/repowiki/zh/content/API参考/档案API/创建与列表.md
lan a4b6c5011e
Some checks failed
SonarQube Analysis / sonarqube (push) Has been cancelled
Details
chore(git): 更新.gitignore以忽略新的本地文件
2025-11-30 08:33:17 +08:00

16 KiB
Raw Blame History

创建与列表

**本文引用的文件** - [routes.go](file://internal/handler/routes.go) - [profile_handler.go](file://internal/handler/profile_handler.go) - [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) - [common.go](file://internal/types/common.go) - [response.go](file://internal/model/response.go) - [texture.go](file://internal/model/texture.go) - [profile_handler_test.go](file://internal/handler/profile_handler_test.go) - [common_test.go](file://internal/types/common_test.go)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件面向开发者与集成方，系统性梳理“创建与列表”相关接口的实现与使用规范，重点覆盖：

  • 通过 POST /api/v1/profile/ 创建新档案，请求体中必须包含 1-16 字符的角色名；可选皮肤ID与披风ID。
  • 系统在创建时自动将该档案设为用户活跃档案，并将该用户其他档案置为非活跃。
  • 通过 GET /api/v1/profile/ 获取当前用户所有档案列表，响应包含档案UUID、名称、活跃状态、关联材质等信息。
  • 结合 profile_service.go 中的 CheckProfileLimit 逻辑说明用户档案数量上限（默认5个）的控制机制。

项目结构

围绕档案模块的路由、处理器、服务层、仓储层与模型如下所示：

graph TB
subgraph "路由层"
R["routes.go<br/>注册 /api/v1/profile/* 路由"]
end
subgraph "处理器层"
H["profile_handler.go<br/>CreateProfile / GetProfiles / SetActiveProfile 等"]
end
subgraph "服务层"
S["profile_service.go<br/>CreateProfile / GetUserProfiles / CheckProfileLimit 等"]
end
subgraph "仓储层"
RP["profile_repository.go<br/>CreateProfile / FindProfilesByUserID / SetActiveProfile 等"]
end
subgraph "模型与类型"
M["profile.go<br/>Profile / ProfileResponse / ProfileTexturesData 等"]
T["texture.go<br/>Texture 类型"]
C["common.go<br/>CreateProfileRequest / ProfileInfo / UpdateProfileRequest 等"]
RESP["response.go<br/>统一响应结构"]
end
R --> H
H --> S
S --> RP
RP --> M
S --> M
H --> RESP
H --> C
M --> T

图表来源

章节来源

核心组件

  • 路由注册：在路由层为档案模块注册了认证中间件保护的 POST / GET / PUT / DELETE / POST activate 等路径。
  • 处理器：负责解析请求、鉴权、调用服务层并返回统一响应。
  • 服务层：封装业务规则，如创建档案时的用户存在性校验、角色名唯一性校验、活跃状态设置、档案数量上限检查等。
  • 仓储层：封装数据库访问，如创建档案、查询用户档案列表、批量设置活跃状态等。
  • 模型与类型：定义档案实体、响应结构、请求体结构以及材质类型。

章节来源

架构总览

下图展示从客户端到数据库的调用链路与关键步骤。

sequenceDiagram
participant Client as "客户端"
participant Router as "路由层(routes.go)"
participant Handler as "处理器(profile_handler.go)"
participant Service as "服务层(profile_service.go)"
participant Repo as "仓储层(profile_repository.go)"
participant DB as "数据库"
Client->>Router : "POST /api/v1/profile"
Router->>Handler : "CreateProfile"
Handler->>Handler : "解析请求体(CreateProfileRequest)"
Handler->>Handler : "读取用户ID(鉴权)"
Handler->>Service : "CheckProfileLimit(userID, 5)"
Service->>Repo : "CountProfilesByUserID(userID)"
Repo->>DB : "统计数量"
DB-->>Repo : "count"
Repo-->>Service : "返回count"
Service-->>Handler : "通过/错误"
alt "未达上限"
Handler->>Service : "CreateProfile(userID, name)"
Service->>Repo : "FindUserByID(userID)"
Repo->>DB : "查询用户"
DB-->>Repo : "用户"
Repo-->>Service : "返回用户"
Service->>Repo : "FindProfileByName(name)"
Repo->>DB : "查询角色名"
DB-->>Repo : "结果"
Service->>Repo : "CreateProfile(Profile)"
Repo->>DB : "插入档案"
Service->>Repo : "SetActiveProfile(uuid, userID)"
Repo->>DB : "事务 : 将其他档案置为非活跃<br/>并将当前档案置为活跃"
DB-->>Repo : "提交"
Repo-->>Service : "返回Profile"
Service-->>Handler : "返回Profile"
Handler-->>Client : "200 成功(统一响应)"
else "已达上限"
Handler-->>Client : "400 参数错误(已达上限)"
end

图表来源

详细组件分析

POST /api/v1/profile/ 创建档案

  • 功能概述：创建新的Minecraft角色档案，系统自动生成UUID并默认设为活跃状态，同时将该用户其他档案置为非活跃。
  • 请求体
    • 必填：name（字符串，1-16字符）
    • 可选：skin_id（整数，材质ID）、cape_id（整数，材质ID）
  • 响应
    • 成功：返回统一响应结构，data为 ProfileInfo 对象，包含 uuid、user_id、name、skin_id、cape_id、is_active、last_used_at、created_at、updated_at。
    • 失败：根据错误类型返回 400（参数错误/已达上限）、401（未授权）、500（服务器错误）。
  • 关键业务逻辑
    • 用户存在性与状态校验
    • 角色名唯一性校验
    • 档案数量上限检查（默认5个）
    • 创建成功后自动设置活跃状态，并将其他档案置为非活跃
  • 请求示例
    • 方法：POST
    • URL：/api/v1/profile
    • 请求头：Authorization: Bearer
    • 请求体：
      • name: "PlayerName"
      • skin_id: 123（可选）
      • cape_id: 456（可选）
  • 响应示例
    • 成功：
      • code: 200
      • message: "操作成功"
      • data: { uuid: "550e8400-e29b-41d4-a716-446655440000" user_id: 1 name: "PlayerName" skin_id: 123 cape_id: 456 is_active: true last_used_at: "2025-10-01T12:00:00Z" created_at: "2025-10-01T10:00:00Z" updated_at: "2025-10-01T10:00:00Z" }
    • 达到上限：
      • code: 400
      • message: "已达到档案数量上限（5个）"
flowchart TD
Start(["进入 CreateProfile"]) --> Bind["绑定请求体(CreateProfileRequest)"]
Bind --> CheckAuth{"鉴权通过？"}
CheckAuth --> |否| Resp401["返回 401 未授权"]
CheckAuth --> |是| Limit["CheckProfileLimit(userID, 5)"]
Limit --> Over{"超过上限？"}
Over --> |是| Resp400["返回 400 已达上限"]
Over --> |否| Create["CreateProfile(userID, name)"]
Create --> Exists{"用户存在且状态正常？"}
Exists --> |否| Resp500["返回 500 用户异常"]
Exists --> |是| Unique{"角色名唯一？"}
Unique --> |否| Resp400["返回 400 角色名冲突"]
Unique --> |是| Insert["插入档案记录"]
Insert --> SetActive["SetActiveProfile(uuid, userID)<br/>将其他档案置为非活跃，当前置为活跃"]
SetActive --> Done(["返回 200 成功"])

图表来源

章节来源

GET /api/v1/profile/ 获取档案列表

  • 功能概述：返回当前用户的所有档案列表，包含每个档案的UUID、名称、活跃状态、关联材质等。
  • 请求
    • 方法：GET
    • URL：/api/v1/profile
    • 请求头：Authorization: Bearer
  • 响应
    • 成功：返回统一响应结构，data为 ProfileInfo 数组。
    • 失败：401（未授权）、500（服务器错误）。
  • 关键逻辑
    • 服务层查询用户所有档案并预加载关联材质（Skin/Cape）
    • 处理器将模型转换为 ProfileInfo 并返回
sequenceDiagram
participant Client as "客户端"
participant Router as "路由层(routes.go)"
participant Handler as "处理器(profile_handler.go)"
participant Service as "服务层(profile_service.go)"
participant Repo as "仓储层(profile_repository.go)"
participant DB as "数据库"
Client->>Router : "GET /api/v1/profile"
Router->>Handler : "GetProfiles"
Handler->>Handler : "读取用户ID(鉴权)"
Handler->>Service : "GetUserProfiles(userID)"
Service->>Repo : "FindProfilesByUserID(userID)"
Repo->>DB : "查询档案列表并预加载 Skin/Cape"
DB-->>Repo : "返回 profiles"
Repo-->>Service : "返回 profiles"
Service-->>Handler : "返回 profiles"
Handler->>Handler : "转换为 ProfileInfo 列表"
Handler-->>Client : "200 成功(统一响应)"

图表来源

章节来源

档案数量上限与活跃状态控制

  • 档案数量上限
    • 默认上限为5个，来源于系统配置与处理器中的硬编码值。
    • 服务层提供 CheckProfileLimit(userID, maxProfiles) 进行检查。
  • 活跃状态控制
    • 创建新档案时，服务层会将该档案设为活跃，并通过仓储层的事务将该用户其他档案置为非活跃。
    • 提供 SetActiveProfile 接口用于手动切换活跃档案。
flowchart TD
A["创建/切换活跃"] --> B["CheckProfileLimit(userID, 5)"]
B --> C{"未超限？"}
C --> |是| D["CreateProfile 或 SetActiveProfile"]
D --> E["SetActiveProfile(uuid, userID) 事务"]
E --> F["将其他档案 is_active=false"]
E --> G["将当前档案 is_active=true"]
C --> |否| H["返回 400 达到上限"]

图表来源

章节来源

依赖分析

  • 路由层依赖处理器层，处理器层依赖服务层，服务层依赖仓储层，仓储层依赖数据库与模型。
  • 处理器层与服务层均依赖统一响应结构与请求/响应类型定义。
  • 档案模型与材质模型存在外键关联，查询时进行预加载以减少N+1问题。
graph LR
Routes["routes.go"] --> Handler["profile_handler.go"]
Handler --> Service["profile_service.go"]
Service --> Repo["profile_repository.go"]
Repo --> Model["profile.go"]
Model --> Texture["texture.go"]
Handler --> Types["common.go"]
Handler --> Resp["response.go"]

图表来源

章节来源

性能考虑

  • 预加载关联材质：仓储层在查询用户档案列表时预加载 Skin 与 Cape，避免多次查询。
  • 事务一致性：设置活跃状态采用数据库事务，确保原子性与一致性。
  • 唯一性约束：角色名在模型层定义唯一索引，查询时可快速判定冲突。
  • 响应结构：统一响应结构便于前端处理与日志记录。

[本节为通用建议，不涉及具体文件分析]

故障排查指南

  • 400 参数错误
    • 角色名为空或长度不在1-16范围内
    • 已达到档案数量上限（默认5个）
  • 401 未授权
    • 缺少或无效的认证令牌
  • 403 权限不足
    • 操作他人档案（如更新/删除/设置活跃）
  • 404 资源不存在
    • 档案UUID不存在
  • 500 服务器错误
    • 数据库查询失败、事务提交失败、用户状态异常等

章节来源

结论

  • 创建档案接口严格遵循请求体校验与业务规则，确保角色名唯一与数量上限控制。
  • 活跃状态切换通过事务保障一致性，避免并发场景下的状态不一致。
  • 档案列表接口提供完整档案信息与关联材质，满足前端展示需求。
  • 建议在生产环境中将上限值从硬编码迁移到系统配置中心，以便动态调整。

[本节为总结性内容，不涉及具体文件分析]

附录

API 定义与数据结构

  • POST /api/v1/profile

    • 请求体：CreateProfileRequest
      • name: string (必填，1-16字符)
      • skin_id: int64 (可选)
      • cape_id: int64 (可选)
    • 响应体：统一响应结构，data 为 ProfileInfo
      • uuid: string
      • user_id: int64
      • name: string
      • skin_id: int64 (可选)
      • cape_id: int64 (可选)
      • is_active: bool
      • last_used_at: datetime (可选)
      • created_at: datetime
      • updated_at: datetime

  • GET /api/v1/profile

    • 响应体：统一响应结构，data 为 ProfileInfo 数组

章节来源