CarrotSkin/backend
4
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6ddcf92ce3ed7c001b2f2ae3e15d38c6a65513a5
backend/.qoder/repowiki/zh/content/API参考/Yggdrasil协议API/档案查询服务.md

309 lines
9.5 KiB
Markdown
Raw Normal View History

chore(git): 更新.gitignore以忽略新的本地文件
2025-11-30 08:33:17 +08:00
# 档案查询服务
<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)
Reference in New Issue Copy Permalink