chore(git): 更新.gitignore以忽略新的本地文件
Some checks failed
SonarQube Analysis / sonarqube (push) Has been cancelled
Some checks failed
SonarQube Analysis / sonarqube (push) Has been cancelled
This commit is contained in:
lan
309
.qoder/repowiki/zh/content/API参考/Yggdrasil协议API/档案查询服务.md
Normal file
309
.qoder/repowiki/zh/content/API参考/Yggdrasil协议API/档案查询服务.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# 档案查询服务
|
||||
|
||||
<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
Block a user