GongFuServer/webServer/serverListApi.md

服务器列表接口 API 文档

接口说明

getAllServerList 和 getLastServerList 接口已升级，支持查询玩家在各个服务器的角色信息。

---

1. 获取所有服务器列表

接口地址

• GET /getAllServerList
• POST /getAllServerList

请求参数

参数	类型	必填	说明
channel_id	number	否	渠道ID，默认为1
uid	string	否	玩家ID，提供时会查询角色信息。不提供时只返回基本服务器信息

请求示例

不查询角色信息

GET /getAllServerList?channel_id=11

查询角色信息

GET /getAllServerList?channel_id=11&uid=12345678

POST请求

POST /getAllServerList
Content-Type: application/json

{
  "channel_id": 11,
  "uid": "12345678"
}

响应参数

不提供uid时的响应

[
  {
    "id": 1,
    "name": "1区",
    "ip": "192.168.1.100",
    "port": 8080,
    "status": 0,
    "tips": "正常"
  }
]

提供uid时的响应

[
  {
    "id": 1,
    "name": "1区",
    "ip": "192.168.1.100",
    "port": 8080,
    "status": 0,
    "tips": "正常",
    "roleName": "玩家昵称",
    "roleLevel": 50,
    "head": "avatar_001.png",
    "hasRole": true
  },
  {
    "id": 2,
    "name": "2区",
    "ip": "192.168.1.101",
    "port": 8080,
    "status": 0,
    "tips": "正常",
    "roleName": null,
    "roleLevel": null,
    "head": null,
    "hasRole": false
  }
]

---

2. 获取最近登录服务器列表

接口地址

• POST /getLastServerList

请求参数

参数	类型	必填	说明
uid	string	否	玩家ID，用于查询角色信息。不提供时只返回基本服务器信息
channel_id	number	否	渠道ID，默认为1

请求示例

查询角色信息

POST /getLastServerList
Content-Type: application/json

{
  "uid": "12345678",
  "channel_id": 11
}

不查询角色信息

POST /getLastServerList
Content-Type: application/json

{
  "channel_id": 11
}

响应参数

[
  {
    "channel": "小程序",
    "minSid": 1,
    "maxSid": 10,
    "isNewAccount": 0,
    "sid": 1,
    "id": 1,
    "name": "1区",
    "tips": "正常",
    "server": "ws://192.168.1.100:8080",
    "status": 0,
    "roleName": "玩家昵称",
    "roleLevel": 50,
    "head": "avatar_001.png",
    "hasRole": true
  }
]

---

3. 角色信息字段说明

字段	类型	说明
roleName	string/null	角色名称，无角色时为null
roleLevel	number/null	角色等级，无角色时为null
head	string/null	角色头像，无角色时为null
hasRole	boolean	是否有角色，true表示有角色，false表示无角色

---

4. 数据库查询逻辑

数据库名称生成规则

数据库名称 = "ckwy_fy_S" + (350001 + 服务器ID).padStart(3, '0')

查询条件

• 集合名称：char
• 查询条件：{uid: 玩家ID}

返回字段

• name: 角色名称
• lv: 角色等级
• roleId: 角色ID
• head: 角色头像

---

5. 错误处理

• 如果查询角色信息失败，会记录错误日志，但不会影响服务器列表的返回
• 查询失败时，角色相关字段会设置为null或false
• 数据库连接失败时会返回默认值

---

6. 性能优化

• 使用 Promise.all 并行查询多个服务器的角色信息
• 查询失败时不会阻塞其他服务器的查询
• 只查询有玩家ID的请求，避免不必要的数据库查询

---

7. 使用示例

JavaScript示例

// 获取所有服务器列表（带角色信息）
const getAllServers = async (uid) => {
  const response = await fetch(`/getAllServerList?uid=${uid}&channel_id=11`);
  const servers = await response.json();
  
  servers.forEach(server => {
    if (server.hasRole) {
      console.log(`服务器${server.name}: ${server.roleName} (等级${server.roleLevel}) 头像: ${server.head}`);
    } else {
      console.log(`服务器${server.name}: 无角色`);
    }
  });
};

// 获取最近登录服务器列表
const getLastServers = async (uid) => {
  const response = await fetch('/getLastServerList', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ uid, channel_id: 11 })
  });
  const servers = await response.json();
  return servers;
};

---

8. 重要说明

• 向后兼容: 不提供uid时，接口行为与之前完全一致
• 性能考虑: 提供uid时会查询所有服务器的角色信息，可能影响响应时间
• 数据一致性: 角色信息来自MongoDB，与游戏服务器数据保持同步
• 错误容错: 单个服务器查询失败不会影响整体结果