跳到主要内容
版本：2.0.0

Database 数据库 API 文档

Database 是 EasyBot 提供的数据库操作 API，封装了 EF Core 操作，用于管理服务器、玩家、社交账号等核心数据。每次操作都会创建新的 ServiceScope 确保数据一致性。

数据类型​

ServerStateType 枚举​

服务器状态类型枚举，用于记录玩家行为：

enum ServerStateType {
    Unknown,      // 未知状态
    Join,         // 玩家加入
    Leave,        // 玩家离开
    Chat,         // 玩家聊天
    Death,        // 玩家死亡
    Achievement   // 玩家成就
}

核心接口​

  • ServerInfo: 服务器信息，包含 ID、名称、Token、创建时间和玩家列表
  • Player: 玩家信息，包含 ID、名称、UUID、IP、时间戳和关联数据
  • SocialAccount: 社交账号信息，包含平台、UUID、名称、头像等
  • ServerState: 服务器状态记录
  • PlayerRecord: 玩家行为记录
  • ServerGroup: 服务器组管理
  • Group: 群组信息管理

服务器管理​

GetServers()​

功能: 获取所有服务器信息

语法: function GetServers(): ServerInfo[]

示例:

const servers = db.GetServers();
logger.info(`共有 ${servers.length} 个服务器`);

GetServer()​

功能: 根据 Token 获取服务器信息

语法: function GetServer(token: string): ServerInfo | null

参数:

  • token (string): 服务器 Token

示例:

const server = db.GetServer("server-token-123");
if (server) {
    logger.info(`服务器名称: ${server.Name}`);
}

GetServerByName()​

功能: 根据名称获取服务器信息

语法: function GetServerByName(name: string): ServerInfo | null

参数:

  • name (string): 服务器名称

示例:

const server = db.GetServerByName("我的服务器");

CreateServer()​

功能: 创建新服务器

语法: function CreateServer(name: string, token: string): ServerInfo

参数:

  • name (string): 服务器名称
  • token (string): 服务器 Token

示例:

const newServer = db.CreateServer("新服务器", "unique-token");

DeleteServer()​

功能: 删除服务器

语法: function DeleteServer(token: string): boolean

参数:

  • token (string): 服务器 Token

示例:

const deleted = db.DeleteServer("server-token");

玩家管理​

GetPlayers()​

功能: 获取所有玩家

语法: function GetPlayers(): Player[]

示例:

const players = db.GetPlayers();

GetPlayerByName()​

功能: 根据名称获取玩家

语法: function GetPlayerByName(name: string): Player | null

参数:

  • name (string): 玩家名称

示例:

const player = db.GetPlayerByName("Steve");

GetPlayerByUuid()​

功能: 根据 UUID 获取玩家

语法: function GetPlayerByUuid(uuid: string): Player | null

参数:

  • uuid (string): 玩家 UUID

示例:

const player = db.GetPlayerByUuid("player-uuid");

GetServerPlayers()​

功能: 获取服务器中的所有玩家

语法: function GetServerPlayers(serverToken: string): Player[]

参数:

  • serverToken (string): 服务器 Token

示例:

const players = db.GetServerPlayers("server-token");

CreatePlayer()​

功能: 创建新玩家

语法: function CreatePlayer(name: string, uuid?: string, ip?: string): Player

参数:

  • name (string): 玩家名称
  • uuid (string, 可选): 玩家 UUID
  • ip (string, 可选): 玩家 IP

示例:

const player = db.CreatePlayer("Steve", "uuid-123", "192.168.1.1");

UpdatePlayer()​

功能: 更新玩家信息

语法: function UpdatePlayer(playerId: number, name?: string, uuid?: string, ip?: string): boolean

参数:

  • playerId (number): 玩家 ID
  • name (string, 可选): 玩家名称
  • uuid (string, 可选): 玩家 UUID
  • ip (string, 可选): 玩家 IP

示例:

const updated = db.UpdatePlayer(1, "NewName");

DeletePlayer()​

功能: 删除玩家

语法: function DeletePlayer(playerId: number): boolean

参数:

  • playerId (number): 玩家 ID

示例:

const deleted = db.DeletePlayer(1);

社交账号管理​

GetSocialAccounts()​

功能: 获取所有社交账号

语法: function GetSocialAccounts(): SocialAccount[]

示例:

const accounts = db.GetSocialAccounts();

GetSocialAccount()​

功能: 根据平台和 UUID 获取社交账号

语法: function GetSocialAccount(platform: string, uuid: string): SocialAccount | null

参数:

  • platform (string): 平台名称
  • uuid (string): 平台用户 UUID

示例:

const account = db.GetSocialAccount("qq", "123456789");

CreateSocialAccount()​

功能: 创建社交账号

语法: function CreateSocialAccount(platform: string, uuid: string, name?: string, avatarUrl?: string): SocialAccount

参数:

  • platform (string): 平台名称
  • uuid (string): 平台用户 UUID
  • name (string, 可选): 用户名称
  • avatarUrl (string, 可选): 头像 URL

示例:

const account = db.CreateSocialAccount("qq", "123456789", "用户名");

UpdateSocialAccount()​

功能: 更新社交账号信息

语法: function UpdateSocialAccount(accountId: number, name?: string, avatarUrl?: string): boolean

参数:

  • accountId (number): 社交账号 ID
  • name (string, 可选): 用户名称
  • avatarUrl (string, 可选): 头像 URL

示例:

const updated = db.UpdateSocialAccount(1, "新名称");

DeleteSocialAccount()​

功能: 删除社交账号

语法: function DeleteSocialAccount(accountId: number): boolean

参数:

  • accountId (number): 社交账号 ID

示例:

const deleted = db.DeleteSocialAccount(1);

账号绑定管理​

BindPlayerToSocialAccount()​

功能: 绑定玩家和社交账号

语法: function BindPlayerToSocialAccount(playerId: number, socialAccountId: number): boolean

参数:

  • playerId (number): 玩家 ID
  • socialAccountId (number): 社交账号 ID

示例:

const bound = db.BindPlayerToSocialAccount(1, 2);

UnbindPlayerFromSocialAccount()​

功能: 解绑玩家和社交账号

语法: function UnbindPlayerFromSocialAccount(playerId: number): boolean

参数:

  • playerId (number): 玩家 ID

示例:

const unbound = db.UnbindPlayerFromSocialAccount(1);

AddPlayerToServer()​

功能: 绑定玩家到服务器

语法: function AddPlayerToServer(playerId: number, serverToken: string): boolean

参数:

  • playerId (number): 玩家 ID
  • serverToken (string): 服务器 Token

示例:

const added = db.AddPlayerToServer(1, "server-token");

RemovePlayerFromServer()​

功能: 从服务器移除玩家

语法: function RemovePlayerFromServer(playerId: number, serverToken: string): boolean

参数:

  • playerId (number): 玩家 ID
  • serverToken (string): 服务器 Token

示例:

const removed = db.RemovePlayerFromServer(1, "server-token");

状态和记录管理​

GetServerStates()​

功能: 获取服务器状态

语法: function GetServerStates(serverToken: string, limit?: number): ServerState[]

参数:

  • serverToken (string): 服务器 Token
  • limit (number, 可选): 限制数量，默认 10

示例:

const states = db.GetServerStates("server-token", 20);

AddServerState()​

功能: 添加服务器状态

语法: function AddServerState(serverToken: string, players: string): ServerState

参数:

  • serverToken (string): 服务器 Token
  • players (string): 玩家信息 JSON

示例:

const state = db.AddServerState("server-token", '{"online": 5}');

GetPlayerRecords()​

功能: 获取玩家记录

语法: function GetPlayerRecords(playerName: string, serverToken?: string, limit?: number): PlayerRecord[]

参数:

  • playerName (string): 玩家名称
  • serverToken (string, 可选): 服务器 Token
  • limit (number, 可选): 限制数量，默认 10

示例:

const records = db.GetPlayerRecords("Steve", "server-token", 50);

AddPlayerRecord()​

功能: 添加玩家记录

语法: function AddPlayerRecord(playerName: string, serverToken: string, type: ServerStateType, data: string): PlayerRecord

参数:

  • playerName (string): 玩家名称
  • serverToken (string): 服务器 Token
  • type (ServerStateType): 记录类型
  • data (string): 记录数据

示例:

const record = db.AddPlayerRecord("Steve", "server-token", db.ServerStateType.Join, "加入游戏");

服务器组管理​

GetServerGroups()​

功能: 获取所有服务器组

语法: function GetServerGroups(): ServerGroup[]

示例:

const groups = db.GetServerGroups();

GetServerGroupByName()​

功能: 根据名称获取服务器组

语法: function GetServerGroupByName(name: string): ServerGroup | null

参数:

  • name (string): 服务器组名称

示例:

const group = db.GetServerGroupByName("生存服务器组");

CreateServerGroup()​

功能: 创建服务器组

语法: function CreateServerGroup(name: string, serverTokens: string[]): ServerGroup

参数:

  • name (string): 服务器组名称
  • serverTokens (string[]): 服务器 Token 数组

示例:

const group = db.CreateServerGroup("新组", ["token1", "token2"]);

UpdateServerGroup()​

功能: 更新服务器组

语法: function UpdateServerGroup(groupId: number, name?: string, serverTokens?: string[]): boolean

参数:

  • groupId (number): 服务器组 ID
  • name (string, 可选): 服务器组名称
  • serverTokens (string[], 可选): 服务器 Token 数组

示例:

const updated = db.UpdateServerGroup(1, "新名称");

DeleteServerGroup()​

功能: 删除服务器组

语法: function DeleteServerGroup(groupId: number): boolean

参数:

  • groupId (number): 服务器组 ID

示例:

const deleted = db.DeleteServerGroup(1);

群组管理​

GetGroups()​

功能: 获取所有群组

语法: function GetGroups(): Group[]

示例:

const groups = db.GetGroups();

GetGroup()​

功能: 根据平台和群 ID 获取群组

语法: function GetGroup(platform: string, groupId: string): Group | null

参数:

  • platform (string): 平台名称
  • groupId (string): 群组 ID

示例:

const group = db.GetGroup("qq", "123456789");

CreateGroup()​

功能: 创建群组

语法: function CreateGroup(platform: string, groupId: string, name: string, enabled?: boolean): Group

参数:

  • platform (string): 平台名称
  • groupId (string): 群组 ID
  • name (string): 群组名称
  • enabled (boolean, 可选): 是否启用，默认 true

示例:

const group = db.CreateGroup("qq", "123456789", "我的群组");

UpdateGroup()​

功能: 更新群组信息

语法: function UpdateGroup(platform: string, groupId: string, name?: string, enabled?: boolean, memberCount?: number, maxMemberCount?: number, groupAvatar?: string): boolean

参数:

  • platform (string): 平台名称
  • groupId (string): 群组 ID
  • name (string, 可选): 群组名称
  • enabled (boolean, 可选): 是否启用
  • memberCount (number, 可选): 成员数量
  • maxMemberCount (number, 可选): 最大成员数量
  • groupAvatar (string, 可选): 群头像

示例:

const updated = db.UpdateGroup("qq", "123456789", "新群名");

DeleteGroup()​

功能: 删除群组

语法: function DeleteGroup(platform: string, groupId: string): boolean

参数:

  • platform (string): 平台名称
  • groupId (string): 群组 ID

示例:

const deleted = db.DeleteGroup("qq", "123456789");

使用注意事项​

  1. 数据一致性: 每次操作都会创建新的 ServiceScope，确保数据一致性
  2. 错误处理: 建议对所有数据库操作进行适当的错误处理
  3. 性能考虑: 避免频繁的数据库操作，考虑批量处理
  4. 数据验证: 在操作前验证输入参数的有效性
  5. 权限控制: 确保只有授权的操作才能访问敏感数据

简单使用示例​

// 创建服务器和玩家
const server = db.CreateServer("测试服务器", "test-token");
const player = db.CreatePlayer("Steve", "uuid-123");

// 绑定玩家到服务器
db.AddPlayerToServer(player.Id, server.Token);

// 记录玩家行为
db.AddPlayerRecord("Steve", "test-token", db.ServerStateType.Join, "玩家加入");

// 查询玩家记录
const records = db.GetPlayerRecords("Steve", "test-token", 10);
Copyright © 2024-2025 易栈