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

# 档案查询服务

<cite>
**本文档引用文件**   
- [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)
</cite>

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

## 简介

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

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L1-L667)
- [profile_handler.go](file://internal/handler/profile_handler.go#L1-L399)

## 核心功能

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

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

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

**Diagram sources **
- [routes.go](file://internal/handler/routes.go#L108-L109)
- [profile_handler.go](file://internal/handler/profile_handler.go#L164-L195)

## /api/profiles/minecraft 端点详解

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

### 功能说明

该端点允许客户端一次性查询多个玩家的档案信息，主要用于：
- 游戏登录时预加载玩家数据
- 聊天系统中显示玩家名称和头像
- 服务器列表中显示在线玩家信息

### 实现流程

```mermaid
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](file://internal/handler/yggdrasil_handler.go#L553-L587)
- [profile_service.go](file://internal/service/profile_service.go#L237-L243)
- [profile_repository.go](file://internal/repository/profile_repository.go#L129-L137)

### 请求参数

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

### 错误处理

该端点会处理以下错误情况：
- 请求体格式无效
- 用户名数组为空
- 数据库查询失败

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L553-L587)
- [profile_service.go](file://internal/service/profile_service.go#L237-L253)
- [profile_repository.go](file://internal/repository/profile_repository.go#L129-L137)

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

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

### 功能对比

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

### 数据结构差异

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

```mermaid
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](file://internal/model/profile.go#L31-L57)
- [profile_handler.go](file://internal/handler/profile_handler.go#L164-L195)

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

**Section sources**
- [profile.go](file://internal/model/profile.go#L31-L57)
- [profile_handler.go](file://internal/handler/profile_handler.go#L164-L195)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L553-L587)

## 皮肤与披风类型标识

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

### 常量定义

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

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

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

### 测试验证

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

```mermaid
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](file://internal/handler/yggdrasil_handler_test.go#L142-L156)
- [texture.go](file://internal/model/texture.go#L10-L13)

### 数据模型

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

```go
type TextureType string

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

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

**Section sources**
- [yggdrasil_handler_test.go](file://internal/handler/yggdrasil_handler_test.go#L142-L156)
- [texture.go](file://internal/model/texture.go#L8-L13)

## 请求与响应示例

### 请求示例

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

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

### 响应示例

```json
[
    {
        "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](file://internal/handler/yggdrasil_handler.go#L586)
- [profile.go](file://internal/model/profile.go#L8-L24)

## 应用场景

### 游戏登录

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

```mermaid
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](file://internal/handler/yggdrasil_handler.go#L553-L587)
- [routes.go](file://internal/handler/routes.go#L108-L109)

### 聊天显示

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

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

### 服务器列表

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

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

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

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L553-L587)
- [profile_service.go](file://internal/service/profile_service.go#L237-L243)