CarrotSkin/backend

Fork 0

Files

lan a4b6c5011e

SonarQube Analysis / sonarqube (push) Has been cancelled

Details

chore(git): 更新.gitignore以忽略新的本地文件

2025-11-30 08:33:17 +08:00

14 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) - [texture.go](file://internal/model/texture.go) - [response.go](file://internal/model/response.go) - [common.go](file://internal/types/common.go) - [postgres.go](file://pkg/database/postgres.go) - [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go)

简介

本文件面向“详情查询”API，聚焦 GET /api/v1/profile/:uuid 端点。该接口为公开路由，无需认证即可访问，用于根据Minecraft用户UUID获取档案的公开信息。响应体包含档案UUID、用户名、创建时间、最后使用时间、活跃状态，以及关联的皮肤和披风信息（若存在）。该接口在Minecraft客户端通过Yggdrasil协议连接服务器时，可被用于查询玩家档案信息，以支持皮肤/披风展示等场景。

项目结构

围绕“详情查询”API的关键文件组织如下：

路由注册：在路由层定义公开的 GET /api/v1/profile/:uuid，并将其挂载到 v1 分组下。
处理器：实现 GetProfile 处理函数，负责参数解析、调用服务层、构造统一响应。
服务层：封装业务逻辑，调用仓库层进行数据查询。
仓库层：基于GORM执行数据库查询，预加载皮肤/披风关联。
模型与类型：定义档案模型、响应结构、纹理类型等。
数据库：PostgreSQL驱动与连接池配置。

graph TB
subgraph "路由层"
R["routes.go<br/>注册 /api/v1/profile/:uuid"]
end
subgraph "处理器层"
H["profile_handler.go<br/>GetProfile 处理函数"]
end
subgraph "服务层"
S["profile_service.go<br/>GetProfileByUUID"]
end
subgraph "仓库层"
REPO["profile_repository.go<br/>FindProfileByUUID"]
end
subgraph "模型与类型"
M["profile.go<br/>Profile/ProfileResponse"]
T["texture.go<br/>Texture"]
RESP["response.go<br/>统一响应结构"]
TYPES["common.go<br/>ProfileInfo"]
end
subgraph "数据库"
DB["postgres.go<br/>PostgreSQL 连接与配置"]
end
R --> H
H --> S
S --> REPO
REPO --> DB
H --> RESP
S --> M
REPO --> M
M --> T
H --> TYPES

图表来源

章节来源

routes.go

核心组件

路由层：在 v1 分组下注册 GET /api/v1/profile/:uuid，明确该端点为公开路由，无需JWT认证。
处理器层：GetProfile 从路径参数读取 uuid，调用服务层查询档案，构造统一响应。
服务层：GetProfileByUUID 调用仓库层查询档案；若未找到返回“档案不存在”错误。
仓库层：FindProfileByUUID 使用 uuid 条件查询，并预加载 Skin 和 Cape 关联。
模型与类型：Profile 定义档案字段及关联；ProfileResponse 为对外响应结构；ProfileInfo 为处理器侧返回结构；Texture 定义材质模型及其索引字段。
统一响应：response.go 提供统一的 Response/Error 结构，便于前后端约定。

章节来源

架构总览

下面的序列图展示了客户端调用 GET /api/v1/profile/:uuid 的典型流程，以及与Yggdrasil协议的集成场景。

sequenceDiagram
participant Client as "客户端"
participant Router as "Gin 路由"
participant Handler as "GetProfile 处理器"
participant Service as "profile_service.GetProfileByUUID"
participant Repo as "profile_repository.FindProfileByUUID"
participant DB as "PostgreSQL"
Client->>Router : "GET /api/v1/profile/ : uuid"
Router->>Handler : "路由分发"
Handler->>Service : "GetProfileByUUID(uuid)"
Service->>Repo : "FindProfileByUUID(uuid)"
Repo->>DB : "SELECT ... WHERE uuid=?<br/>并预加载 Skin/Cape"
DB-->>Repo : "Profile 记录"
Repo-->>Service : "Profile 对象"
Service-->>Handler : "Profile 对象"
Handler-->>Client : "200 + 统一响应体"

图表来源

详细组件分析

接口定义与行为

路由：公开端点 GET /api/v1/profile/:uuid，无需认证。
请求参数：路径参数 uuid（Minecraft档案UUID）。
成功响应：返回统一响应结构，包含档案基本信息与关联皮肤/披风信息。
错误响应：当档案不存在时返回404。

章节来源

响应数据结构

响应体字段（对外）：
- uuid：档案UUID
- name：Minecraft角色名
- textures：包含皮肤与披风信息的对象
  - SKIN：皮肤信息（可选）
    - url：皮肤图片地址
    - metadata：元数据（可选）
      - model：皮肤模型（slim 或 classic）
  - CAPE：披风信息（可选）
    - url：披风图片地址
    - metadata：元数据（可选）
- is_active：是否为活跃档案
- last_used_at：最后使用时间（可选）
- created_at：创建时间
- updated_at：更新时间
处理器侧返回结构（ProfileInfo）：
- uuid、user_id、name、skin_id、cape_id、is_active、last_used_at、created_at、updated_at

章节来源

查询流程与错误码

正常流程：处理器读取 uuid -> 服务层查询 -> 仓库层查询并预加载关联 -> 返回统一响应。
错误码：
- 404：档案不存在
- 500：服务器内部错误（数据库异常、服务层错误等）

flowchart TD
Start(["进入 GetProfile"]) --> Parse["解析路径参数 uuid"]
Parse --> Query["调用服务层 GetProfileByUUID"]
Query --> RepoCall["仓库层 FindProfileByUUID(uuid)"]
RepoCall --> Found{"找到记录？"}
Found --> |是| BuildResp["组装响应含 textures"]
Found --> |否| NotFound["返回 404 档案不存在"]
BuildResp --> Ok["返回 200 + 统一响应"]
NotFound --> End(["结束"])
Ok --> End

图表来源

章节来源

与Yggdrasil协议的集成场景

在Minecraft客户端连接服务器时，可通过Yggdrasil的会话服务器端点获取玩家档案信息，从而展示皮肤/披风。
该端点与Yggdrasil的会话服务器端点存在语义上的互补：前者为公开档案详情查询，后者为认证后的会话信息查询。
典型调用链：客户端 -> 服务器（Yggdrasil）-> 本系统 GetProfileByUUID（公开详情查询）。

章节来源

yggdrasil_handler.go

依赖分析

路由层依赖 Gin 路由注册，将公开端点挂载至 v1 分组。
处理器层依赖服务层与统一响应结构。
服务层依赖仓库层与数据库连接。
仓库层依赖 GORM 与 PostgreSQL 驱动。
模型层定义档案与纹理的字段、索引与关联。

graph LR
Routes["routes.go"] --> Handler["profile_handler.go"]
Handler --> Service["profile_service.go"]
Service --> Repo["profile_repository.go"]
Repo --> DB["postgres.go"]
Handler --> Resp["response.go"]
Service --> Model["profile.go"]
Repo --> Model
Model --> Texture["texture.go"]
Handler --> Types["common.go"]

图表来源

章节来源

性能考量

数据库索引与查询优化
- Profile 表的 uuid 字段为主键，查询命中主键索引，具备高效率。
- Profile 表的 name 字段具有唯一索引，有助于去重与唯一性约束。
- Profile 表的 user_id 字段具有普通索引，有利于按用户维度查询。
- Profile 表的 is_active 字段具有索引，便于筛选活跃档案。
- Texture 表的 hash 字段具有唯一索引，有利于快速定位材质。
- Texture 表的 uploader_id、is_public、favorite_count、download_count 等字段具有索引，便于检索与排序。
关联预加载
- 仓库层在查询档案时使用预加载（Preload）加载 Skin 与 Cape，减少 N+1 查询风险，提升响应速度。
数据库连接池
- PostgreSQL 驱动初始化时配置了连接池参数（最大空闲连接、最大打开连接、连接最大生命周期），有助于并发场景下的稳定性与吞吐量。
缓存建议
- 对高频查询的档案详情可引入缓存（如Redis），以进一步降低数据库压力。
- 缓存键可采用 profile:{uuid}，并设置合理过期时间（如几分钟）。
日志与监控
- 处理器层记录错误日志，便于定位慢查询与异常。
- 建议增加指标埋点（如QPS、P95/P99延迟、错误率）以便持续优化。

章节来源

故障排查指南

404 档案不存在
- 现象：请求返回 404，消息提示“档案不存在”。
- 排查：确认 uuid 是否正确；检查数据库中是否存在该 uuid 的档案记录。
500 服务器内部错误
- 现象：请求返回 500，消息提示服务层或仓库层错误。
- 排查：查看处理器层日志；检查数据库连接与连接池配置；确认 GORM 查询是否报错。
响应缺少皮肤/披风信息
- 现象：textures 字段为空或部分缺失。
- 排查：确认档案是否绑定了皮肤/披风；检查关联表是否存在有效记录；确认仓库层预加载是否生效。
Yggdrasil集成问题
- 现象：客户端无法显示皮肤/披风。
- 排查：确认客户端调用的Yggdrasil端点与本系统公开详情查询端点是否一致；核对响应结构与字段命名是否匹配。

章节来源

结论

GET /api/v1/profile/:uuid 作为公开端点，提供了基于Minecraft档案UUID的详情查询能力。其架构清晰、职责分明：路由层公开、处理器层编排、服务层封装、仓库层持久化、模型层定义。响应体包含档案基础信息与皮肤/披风信息，满足客户端在Yggdrasil协议下的集成需求。通过合理的数据库索引、关联预加载与连接池配置，可在高并发场景下保持稳定与高效。建议结合缓存与监控体系，持续优化查询性能与用户体验。

14 KiB Raw Blame History Unescape Escape

详情查询

目录

简介

项目结构

核心组件

架构总览

详细组件分析

接口定义与行为

响应数据结构

查询流程与错误码

与Yggdrasil协议的集成场景

依赖分析

性能考量

故障排查指南

结论

14 KiB

Raw Blame History