backend/.qoder/repowiki/zh/content/API参考/Yggdrasil协议API/档案查询服务.md

档案查询服务

**本文档引用文件** - [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go) - [profile_handler.go](file://internal/handler/profile_handler.go) - [profile.go](file://internal/model/profile.go) - [profile_repository.go](file://internal/repository/profile_repository.go) - [profile_service.go](file://internal/service/profile_service.go) - [yggdrasil_handler_test.go](file://internal/handler/yggdrasil_handler_test.go) - [texture.go](file://internal/model/texture.go) - [routes.go](file://internal/handler/routes.go)

目录

1. 简介
2. 核心功能
3. /api/profiles/minecraft 端点详解
4. /profile/:uuid 与 /api/profiles/minecraft 的区别
5. 皮肤与披风类型标识
6. 请求与响应示例
7. 应用场景

简介

本服务为Minecraft Yggdrasil认证系统的一部分，提供档案（Profile）查询功能。核心功能包括根据用户名批量查询UUID和档案信息，以及根据UUID获取单个档案的完整详情。该服务支持Minecraft客户端在登录和聊天时加载玩家数据。

Section sources

• yggdrasil_handler.go
• profile_handler.go

核心功能

档案查询服务主要提供两种查询方式：

1. 批量查询：通过用户名列表获取对应的UUID和基础档案信息
2. 详情查询：通过UUID获取单个档案的完整信息，包括皮肤和披风等纹理数据

这些功能通过Yggdrasil API的特定端点实现，支持Minecraft客户端的数据加载需求。

graph TD
A[客户端请求] --> B{请求类型}
B --> |批量查询| C[/api/profiles/minecraft]
B --> |详情查询| D[/profile/:uuid]
C --> E[返回UUID和基础信息]
D --> F[返回完整档案信息]

**Diagram sources **

• routes.go
• profile_handler.go

/api/profiles/minecraft 端点详解

/api/profiles/minecraft 端点用于根据玩家用户名列表批量查询对应的UUID和公开档案信息。

功能说明

该端点允许客户端一次性查询多个玩家的档案信息，主要用于：

• 游戏登录时预加载玩家数据
• 聊天系统中显示玩家名称和头像
• 服务器列表中显示在线玩家信息

实现流程

sequenceDiagram
participant Client as 客户端
participant Handler as yggdrasil_handler
participant Service as profile_service
participant Repository as profile_repository
participant DB as 数据库
Client->>Handler : POST /api/profiles/minecraft
Handler->>Handler : 解析用户名数组
Handler->>Service : GetProfilesDataByNames(names)
Service->>Repository : GetProfilesByNames(names)
Repository->>DB : SELECT * FROM profiles WHERE name IN (?)
DB-->>Repository : 返回档案列表
Repository-->>Service : 返回档案列表
Service-->>Handler : 返回档案列表
Handler-->>Client : 返回JSON响应

**Diagram sources **

• yggdrasil_handler.go
• profile_service.go
• profile_repository.go

请求参数

• 方法: POST
• 路径: /api/profiles/minecraft
• 内容类型: application/json
• 请求体: 包含用户名字符串数组

错误处理

该端点会处理以下错误情况：

• 请求体格式无效
• 用户名数组为空
• 数据库查询失败

Section sources

• yggdrasil_handler.go
• profile_service.go
• profile_repository.go

/profile/:uuid 与 /api/profiles/minecraft 的区别

这两个端点虽然都用于查询玩家档案，但功能和用途有明显区别：

功能对比

特性	/profile/:uuid	/api/profiles/minecraft
查询方式	单个UUID查询	批量用户名查询
主要用途	获取完整档案信息	批量映射用户名到UUID
返回数据	包含纹理数据的完整信息	基础档案信息
使用场景	登录验证、档案详情展示	玩家列表、聊天显示

数据结构差异

/profile/:uuid 返回的数据包含完整的纹理信息：

classDiagram
class ProfileResponse {
+string uuid
+string name
+ProfileTexturesData textures
+bool is_active
+time.Time last_used_at
+time.Time created_at
}
class ProfileTexturesData {
+ProfileTexture SKIN
+ProfileTexture CAPE
}
class ProfileTexture {
+string url
+ProfileTextureMetadata metadata
}
class ProfileTextureMetadata {
+string model
}
ProfileResponse --> ProfileTexturesData : "包含"
ProfileTexturesData --> ProfileTexture : "包含"
ProfileTexture --> ProfileTextureMetadata : "包含"

**Diagram sources **

• profile.go
• profile_handler.go

而 /api/profiles/minecraft 返回的是基础档案信息，主要用于名称到UUID的映射。

Section sources

• profile.go
• profile_handler.go
• yggdrasil_handler.go

皮肤与披风类型标识

在档案系统中，皮肤和披风的类型通过特定常量进行标识。

常量定义

根据 yggdrasil_handler_test.go 中的测试代码，皮肤和披风类型的常量定义如下：

const (
    TextureTypeSkin = "SKIN"
    TextureTypeCape = "CAPE"
)

这些常量在多个地方被使用和测试，确保系统的一致性。

测试验证

yggdrasil_handler_test.go 文件中的测试函数验证了这些常量的正确性：

flowchart TD
Start([开始测试常量]) --> TestSkin["验证TextureTypeSkin = 'SKIN'"]
TestSkin --> TestCape["验证TextureTypeCape = 'CAPE'"]
TestCape --> CheckSkin["检查Skin常量值"]
CheckSkin --> CheckCape["检查Cape常量值"]
CheckCape --> End{测试结果}
End --> |通过| Success["测试成功"]
End --> |失败| Failure["测试失败"]

**Diagram sources **

• yggdrasil_handler_test.go
• texture.go

数据模型

在 texture.go 文件中，这些类型被定义为枚举类型：

type TextureType string

const (
    TextureTypeSkin TextureType = "SKIN"
    TextureTypeCape TextureType = "CAPE"
)

这种设计确保了类型安全和代码可读性。

Section sources

• yggdrasil_handler_test.go
• texture.go

请求与响应示例

请求示例

POST /api/profiles/minecraft
Content-Type: application/json

[
    "Player1",
    "Player2",
    "Player3"
]

响应示例

[
    {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "userId": 1,
        "name": "Player1",
        "skinId": 1,
        "capeId": null,
        "isActive": true,
        "lastUsedAt": "2025-10-01T12:00:00Z",
        "createdAt": "2025-10-01T10:00:00Z",
        "updatedAt": "2025-10-01T10:00:00Z"
    },
    {
        "uuid": "550e8400-e29b-41d4-a716-446655440001",
        "userId": 2,
        "name": "Player2",
        "skinId": 2,
        "capeId": 3,
        "isActive": true,
        "lastUsedAt": "2025-10-01T11:00:00Z",
        "createdAt": "2025-09-30T09:00:00Z",
        "updatedAt": "2025-09-30T09:00:00Z"
    }
]

响应包含每个玩家的UUID、用户ID、名称、皮肤ID、披风ID等信息。

Section sources

• yggdrasil_handler.go
• profile.go

应用场景

游戏登录

当玩家登录游戏时，客户端会使用此服务来验证和获取玩家信息：

sequenceDiagram
participant Client as Minecraft客户端
participant Auth as 认证服务器
participant Profile as 档案服务
Client->>Auth : 发送登录凭证
Auth->>Profile : 查询玩家档案
Profile->>Profile : 批量查询用户名对应的UUID
Profile-->>Auth : 返回UUID和基础信息
Auth->>Client : 返回登录结果和玩家信息

**Diagram sources **

• yggdrasil_handler.go
• routes.go

聊天显示

在聊天系统中，当玩家发送消息时，需要显示其名称和头像：

1. 客户端获取消息中的玩家用户名
2. 调用 /api/profiles/minecraft 端点批量查询这些玩家的UUID
3. 使用UUID获取玩家的皮肤信息并显示头像

服务器列表

在多人游戏服务器列表中，需要显示在线玩家的信息：

• 使用批量查询端点获取所有在线玩家的UUID
• 根据UUID获取玩家的皮肤和披风信息
• 在服务器列表中显示玩家头像和名称

这些应用场景都依赖于高效的批量查询能力，/api/profiles/minecraft 端点正是为此设计。

Section sources

• yggdrasil_handler.go
• profile_service.go