# Yggdrasil协议API

<cite>
**本文档引用的文件**   
- [routes.go](file://internal/handler/routes.go)
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go)
- [yggdrasil_repository.go](file://internal/repository/yggdrasil_repository.go)
- [yggdrasil.go](file://internal/model/yggdrasil.go)
- [token.go](file://internal/model/token.go)
- [user_service.go](file://internal/service/user_service.go)
- [profile_service.go](file://internal/service/profile_service.go)
- [profile_repository.go](file://internal/repository/profile_repository.go)
- [jwt.go](file://pkg/auth/jwt.go)
</cite>

## 目录
1. [简介](#简介)
2. [Yggdrasil路由结构](#yggdrasil路由结构)
3. [认证服务API](#认证服务api)
4. [会话服务API](#会话服务api)
5. [档案服务API](#档案服务api)
6. [与Minecraft客户端交互流程](#与minecraft客户端交互流程)
7. [内部用户系统集成](#内部用户系统集成)
8. [错误处理](#错误处理)
9. [元数据与证书](#元数据与证书)

## 简介
Yggdrasil协议是Minecraft客户端认证的核心接口，本系统实现了完整的Yggdrasil协议集成，为Minecraft玩家提供认证、会话管理和档案查询服务。该实现通过`/yggdrasil`路由组暴露标准API端点，与Minecraft客户端无缝对接，同时将Yggdrasil请求映射到系统的内部用户体系。

**Section sources**
- [routes.go](file://internal/handler/routes.go#L87-L111)

## Yggdrasil路由结构
系统在`/api/v1/yggdrasil`路径下提供了完整的Yggdrasil协议支持，包含三个主要子路由组：`authserver`、`sessionserver`和`profiles`，分别处理认证、会话和档案相关请求。

```mermaid
graph TB
Yggdrasil[Yggdrasil根路由 /yggdrasil]
subgraph AuthServer
Authenticate[POST /authserver/authenticate]
Validate[POST /authserver/validate]
Refresh[POST /authserver/refresh]
Invalidate[POST /authserver/invalidate]
SignOut[POST /authserver/signout]
end
subgraph SessionServer
GetProfile[GET /sessionserver/session/minecraft/profile/:uuid]
JoinServer[POST /sessionserver/session/minecraft/join]
HasJoined[GET /sessionserver/session/minecraft/hasJoined]
end
subgraph Profiles
GetProfilesByName[POST /api/profiles/minecraft]
end
Yggdrasil --> Authenticate
Yggdrasil --> Validate
Yggdrasil --> Refresh
Yggdrasil --> Invalidate
Yggdrasil --> SignOut
Yggdrasil --> GetProfile
Yggdrasil --> JoinServer
Yggdrasil --> HasJoined
Yggdrasil --> GetProfilesByName
```

**Diagram sources **
- [routes.go](file://internal/handler/routes.go#L87-L111)

**Section sources**
- [routes.go](file://internal/handler/routes.go#L87-L111)

## 认证服务API
认证服务API位于`/yggdrasil/authserver`路径下，提供用户认证和令牌管理功能。

### authenticate
用户认证端点，用于验证用户凭据并获取访问令牌。

- **方法**: POST
- **路径**: `/yggdrasil/authserver/authenticate`
- **请求体**:
  ```json
  {
    "username": "用户邮箱或用户名",
    "password": "密码",
    "clientToken": "客户端令牌"
  }
  ```
- **响应**:
  - 200: 返回包含`accessToken`、`availableProfiles`和`selectedProfile`的认证响应
  - 403: 认证失败

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L156-L246)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L204-L209)

### validate
验证访问令牌的有效性。

- **方法**: POST
- **路径**: `/yggdrasil/authserver/validate`
- **请求体**:
  ```json
  {
    "accessToken": "访问令牌"
  }
  ```
- **响应**:
  - 204: 令牌有效
  - 403: 令牌无效

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L248-L267)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L260-L261)

### refresh
刷新访问令牌，延长会话有效期。

- **方法**: POST
- **路径**: `/yggdrasil/authserver/refresh`
- **请求体**:
  ```json
  {
    "accessToken": "当前访问令牌",
    "clientToken": "客户端令牌",
    "selectedProfile": "选定的档案"
  }
  ```
- **响应**:
  - 200: 返回新的`accessToken`和`selectedProfile`
  - 400: 刷新失败

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L269-L361)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L341-L351)

### invalidate
使访问令牌失效。

- **方法**: POST
- **路径**: `/yggdrasil/authserver/invalidate`
- **请求体**:
  ```json
  {
    "accessToken": "要使失效的令牌"
  }
  ```
- **响应**:
  - 204: 成功使令牌失效

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L363-L378)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L375)

### signout
用户登出，使该用户的所有令牌失效。

- **方法**: POST
- **路径**: `/yggdrasil/authserver/signout`
- **请求体**:
  ```json
  {
    "username": "用户邮箱",
    "password": "密码"
  }
  ```
- **响应**:
  - 204: 登出成功

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L380-L425)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L422)

## 会话服务API
会话服务API位于`/yggdrasil/sessionserver`路径下，管理玩家与服务器的会话。

### JoinServer
记录玩家加入服务器的会话信息。

- **方法**: POST
- **路径**: `/yggdrasil/sessionserver/session/minecraft/join`
- **请求体**:
  ```json
  {
    "accessToken": "访问令牌",
    "selectedProfile": "选定的档案UUID",
    "serverId": "服务器ID"
  }
  ```
- **响应**:
  - 204: 加入成功
  - 500: 加入失败

```mermaid
sequenceDiagram
participant Client as "Minecraft客户端"
participant SessionServer as "会话服务"
participant Redis as "Redis存储"
Client->>SessionServer : POST /join
SessionServer->>SessionServer : 验证accessToken
SessionServer->>SessionServer : 验证selectedProfile
SessionServer->>Redis : 存储会话数据
Redis-->>SessionServer : 存储成功
SessionServer-->>Client : 204 No Content
```

**Diagram sources **
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L449-L496)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L81-L163)

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L449-L496)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L81-L163)

### HasJoinedServer
验证玩家是否已加入指定服务器。

- **方法**: GET
- **路径**: `/yggdrasil/sessionserver/session/minecraft/hasJoined`
- **查询参数**:
  - `serverId`: 服务器ID
  - `username`: 用户名
  - `ip`: IP地址（可选）
- **响应**:
  - 200: 返回玩家档案信息
  - 204: 未加入或验证失败

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L498-L552)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L165-L201)

## 档案服务API
档案服务API提供玩家档案查询功能。

### GetProfileByUUID
根据UUID获取玩家档案。

- **方法**: GET
- **路径**: `/yggdrasil/sessionserver/session/minecraft/profile/:uuid`
- **响应**:
  - 200: 返回玩家档案信息
  - 500: 获取失败

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L427-L447)
- [profile_service.go](file://internal/service/profile_service.go#L71-L80)

### GetProfilesByName
根据用户名批量获取玩家档案。

- **方法**: POST
- **路径**: `/yggdrasil/api/profiles/minecraft`
- **请求体**: 用户名数组
  ```json
  ["player1", "player2"]
  ```
- **响应**: 返回匹配的档案列表

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L554-L587)
- [profile_repository.go](file://internal/repository/profile_repository.go#L129-L137)

## 与Minecraft客户端交互流程
Minecraft客户端与Yggdrasil服务的完整交互流程如下：

```mermaid
sequenceDiagram
participant Client as "Minecraft客户端"
participant AuthServer as "认证服务"
participant SessionServer as "会话服务"
participant ProfileServer as "档案服务"
Client->>AuthServer : authenticate(邮箱/用户名, 密码)
AuthServer-->>Client : accessToken, availableProfiles
Client->>SessionServer : join(serverId, accessToken, selectedProfile)
SessionServer-->>Client : 204
Client->>ProfileServer : hasJoined(serverId, username)
ProfileServer-->>Client : 玩家档案
Client->>ProfileServer : getProfile(uuid)
ProfileServer-->>Client : 档案详情
```

**Diagram sources **
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go)

## 内部用户系统集成
Yggdrasil实现与系统内部用户体系的集成通过以下方式完成：

### 用户映射
系统通过`Yggdrasil`模型将Yggdrasil协议的密码认证与内部用户ID关联。当用户注册时，系统自动生成一个16位随机密码与用户ID绑定。

```mermaid
classDiagram
class User {
+int64 ID
+string Username
+string Email
+string Password
}
class Yggdrasil {
+int64 ID
+string Password
}
User --> Yggdrasil : "1对1关联"
```

**Diagram sources **
- [yggdrasil.go](file://internal/model/yggdrasil.go)
- [user_service.go](file://internal/service/user_service.go#L13-L67)

**Section sources**
- [yggdrasil.go](file://internal/model/yggdrasil.go#L13-L38)
- [user_service.go](file://internal/service/user_service.go#L13-L67)

### 令牌管理
系统使用`Token`模型管理访问令牌，将`accessToken`与`userID`、`profileId`关联，实现会话状态管理。

```mermaid
classDiagram
class Token {
+string AccessToken
+int64 UserID
+string ProfileId
+bool Usable
}
class Profile {
+string UUID
+int64 UserID
+string Name
}
Token --> Profile : "关联档案"
Token --> User : "关联用户"
```

**Diagram sources **
- [token.go](file://internal/model/token.go)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L211-L216)

**Section sources**
- [token.go](file://internal/model/token.go)
- [yggdrasil_service.go](file://internal/service/yggdrasil_service.go#L211-L216)

## 错误处理
系统实现了标准化的错误处理机制，所有Yggdrasil端点返回一致的错误响应格式。

### 常见错误代码
| HTTP状态码 | 错误类型 | 描述 |
|-----------|---------|------|
| 400 | Bad Request | 请求格式无效 |
| 403 | Forbidden | 认证失败或权限不足 |
| 404 | Not Found | 资源未找到 |
| 500 | Internal Server Error | 服务器内部错误 |

### 错误响应示例
```json
{
  "error": "密码错误"
}
```

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L19-L57)

## 元数据与证书
系统提供元数据和玩家证书服务，支持Minecraft客户端的高级功能。

### GetMetaData
获取服务元数据。

- **方法**: GET
- **路径**: `/yggdrasil`
- **响应**: 包含实现信息、链接和功能标志

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L589-L615)

### GetPlayerCertificates
获取玩家证书。

- **方法**: POST
- **路径**: `/yggdrasil/minecraftservices/player/certificates`
- **认证**: Bearer Token
- **响应**: 包含玩家公钥证书

**Section sources**
- [yggdrasil_handler.go](file://internal/handler/yggdrasil_handler.go#L618-L667)
- [profile_service.go](file://internal/service/profile_service.go#L44-L48)