批量删除好友（adminx）

1. 接口定位

• 接口名称: 批量删除好友
• 所属域: admin/friend
• 业务目标: 管理员按指定用户批量删除其好友关系

2. 请求定义

• Method: POST
• Path: /adminx/friend/delete/batch
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 非严格幂等；已删除好友再次删除时会返回失败结果项

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	管理员 token

Body 参数

字段	必填	类型	说明
userID	是	string	目标用户 ID（删除该用户与其好友的关系）
friendUserIDs	是	array<string>	待删除好友 userID 列表

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	object	业务数据

data 字段

字段	类型	说明
total	uint32	入参总条数
successCount	uint32	删除成功条数
failedCount	uint32	删除失败条数
successUserIDs	array<string>	删除成功的好友 userID
results	array<BatchDeleteFriendResult>	每条处理结果

BatchDeleteFriendResult 字段：

字段	类型	说明
friendUserID	string	好友 userID
success	bool	是否成功
reasonCode	string	失败原因码，成功时为空
reason	string	失败原因说明，成功时为空

reasonCode 可选值：

• INVALID_FRIEND_USER_ID: friendUserID 为空或仅空白字符
• DUPLICATE_FRIEND_USER_ID: 入参中出现重复 friendUserID
• DELETE_FAILED: 调用 OpenIM 删除接口失败

5. 业务规则

• 服务端会对 friendUserIDs 做 trim、去重校验。
• 无效 ID 与重复 ID 不会发起删除调用，直接按失败结果返回。
• 合法 ID 会逐条调用 OpenIM 删除好友接口。
• 单条失败不会中断后续条目，最终返回批量汇总结果。

6. 错误码与失败场景

错误码	场景	典型报错
1001	userID 为空	userID is empty
1001	friendUserIDs 为空数组	friendUserIDs is empty
-	鉴权失败	由管理员鉴权链路返回
-	OpenIM 删除失败	记录在 results.reason 中

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/friend/delete/batch", {
  method: "POST",
  headers: {
    operationID: "adminx-friend-delete-batch-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userID: "u1001",
    friendUserIDs: ["u2001", "u2002", "u2002", "   "],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 4,
    "successCount": 2,
    "failedCount": 2,
    "successUserIDs": ["u2001", "u2002"],
    "results": [
      {
        "friendUserID": "u2001",
        "success": true,
        "reasonCode": "",
        "reason": ""
      },
      {
        "friendUserID": "u2002",
        "success": true,
        "reasonCode": "",
        "reason": ""
      },
      {
        "friendUserID": "u2002",
        "success": false,
        "reasonCode": "DUPLICATE_FRIEND_USER_ID",
        "reason": "friendUserID duplicated"
      },
      {
        "friendUserID": "   ",
        "success": false,
        "reasonCode": "INVALID_FRIEND_USER_ID",
        "reason": "friendUserID is empty"
      }
    ]
  }
}

8. 变更记录

• 2026-09-03: 首版发布，新增 adminx 批量删除好友接口。