云信目前提供好友关系、黑名单与免打扰三种内置用户关系。三种关系互相独立，互不影响。即任意两个用户之间可以同时存在这三种关系。

本文主要介绍好友关系的管理和维护。

技术原理

NIM SDK 支持添加/删除好友，设置好友信息，查询好友状态和信息等操作。

NIM SDK 添加好友的方式分为以下两种：

• 直接添加好友，不需要对方同意。该模式下，调用接口成功后，本端和对端（被添加的好友）都会收到添加好友成功的回调。

• 请求添加对方为好友，需要对方验证通过才能添加。该模式下，调用接口成功后，对端（被添加的好友）会收到好友申请的回调。

  • 对端可以接受好友申请，接受成功后，本端和对端都会收到添加好友成功的回调。
  • 对端也可以拒绝好友申请，拒绝成功后，发起好友申请的用户会收到拒绝好友申请的回调。

前提条件

已 登录 IM。

监听好友关系变更事件回调

在进行好友相关操作前，可以调用 observeFriendChangedNotify 提前注册好友关系变更事件的监听。注册成功后，当好友关系发生变更时，SDK 会触发对应回调通知。

示例代码如下：

javaNIMClient.getService(FriendServiceObserve.class).observeFriendChangedNotify(friendChangedNotifyObserver, true);
private Observer<FriendChangedNotify> friendChangedNotifyObserver = new Observer<FriendChangedNotify>() {
    @Override
    public void onEvent(FriendChangedNotify friendChangedNotify) {
        List<Friend> addedOrUpdatedFriends = friendChangedNotify.getAddedOrUpdatedFriends(); // 新增的好友
        List<String> deletedFriendAccounts = friendChangedNotify.getDeletedFriends(); // 删除好友或者被解除好友
        ...
    }
};

监听系统通知事件回调

云信 NIM SDK 支持接收和存储内置系统通知。

好友关系的相关操作执行后，会触发响应的系统通知 SystemMessage。好友相关的系统通知事件类型统一为 AddFriend。具体请参见 系统通知。

• 好友相关的系统通知 SystemMessage - getType() 字段值统一为 SystemMessageType.AddFriend。
• 通过 SystemMessage - getAttachObject() 获取到的 AddFriendNotify 类型对象的 getEvent() 来获取具体的操作事件。

AddFriendNotify.Event 属性说明：

AddFriendNotify.Event 属性	说明
RECV_ADD_FRIEND_DIRECT	对方直接加你为好友
RECV_ADD_FRIEND_VERIFY_REQUEST	对方发起好友验证请求
RECV_AGREE_ADD_FRIEND	对方同意加你为好友
RECV_REJECT_ADD_FRIEND	对方拒绝加你为好友

示例代码如下：

javaNIMClient.getService(SystemMessageObserver.class).observeReceiveSystemMsg(systemMessageObserver, register);

Observer<SystemMessage> systemMessageObserver = new Observer<SystemMessage>() {
    @Override
    public void onEvent(SystemMessage systemMessage) {
        if (systemMessage.getType() == SystemMessageType.AddFriend) {
            AddFriendNotify attachData = (AddFriendNotify) message.getAttachObject();
            if (attachData != null) {
            // 针对不同的事件做处理
                if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_DIRECT) {
                // 对方直接添加你为好友
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_AGREE_ADD_FRIEND) {
                // 对方通过了你的好友验证请求
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_REJECT_ADD_FRIEND) {
                // 对方拒绝了你的好友验证请求
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_VERIFY_REQUEST) {
                // 对方请求添加好友，一般场景会让用户选择同意或拒绝对方的好友请求。
                // 通过message.getContent()获取好友验证请求的附言
                }
            }
        }
    }
};

添加好友

调用 addFriend 方法添加好友。

NIM SDK 添加好友分为以下两种模式：

• 直接添加为好友（VerifyType = DIRECT_ADD）。

  该模式下，调用接口成功后，本端和对端（被添加的好友）都会收到好友关系变更的回调。

• 请求添加对方为好友，需要对方验证通过才能添加（VerifyType = VERIFY_REQUEST）。

  该模式下，调用接口成功后，即向对方发送添加好友的申请，对端（被添加的好友）会收到好友申请。对端可以选择接受或拒绝好友申请。

添加好友时需要构造 AddFriendData，需要填入包括对方帐号，好友验证类型及附言（可选）。

示例代码如下：

javafinal VerifyType verifyType = VerifyType.VERIFY_REQUEST; // 发起好友验证请求
String msg = "好友请求附言";
NIMClient.getService(FriendService.class).addFriend(new AddFriendData(account, verifyType, msg))
	.setCallback(new RequestCallback<Void>() { ... });

回应好友申请

当收到他人的好友申请后，可以调用 ackAddFriendRequest 方法接受或拒绝该请求。

示例代码如下：

java// 以通过对方好友请求为例
NIMClient.getService(FriendService.class).ackAddFriendRequest(account, true).setCallback(...);

删除好友

调用 deleteFriend 方法删除好友。

删除好友后，将自动解除双方的好友关系，双方的好友列表中均不存在对方。删除好友后，默认情况下双方依然可以聊天。

示例代码如下：

javaNIMClient.getService(FriendService.class).deleteFriend(account,true)
	.setCallback(new RequestCallback<Void>() { ... });

查询好友关系

调用 isMyFriend 方法可以查询指定用户是否为我的好友。

示例代码如下：

javaboolean isMyFriend = NIMClient.getService(FriendService.class).isMyFriend(account);

修改好友备注

目前云信支持通过 updateFriendFields 方法更新好友的备注名和好友关系扩展字段。

入参 fields 传入待更新的所有字段集合，目前支持更新备注名和扩展字段。

备注名最长 128 个字符，扩展字段需要传入 Map，key 为 String，Value 为 Object，SDK 负责转成 Json String，最大长度 256 字符。

示例代码如下：

java// 更新备注名
Map<FriendFieldEnum, Object> map = new HashMap<>();
map.put(FriendFieldEnum.ALIAS, content);
NIMClient.getService(FriendService.class).updateFriendFields(data, map).setCallback(callback);

// 更新扩展字段
Map<FriendFieldEnum, Object> map = new HashMap<>();
Map<String, Object> exts = new HashMap<>();
exts.put("ext", "ext");
map.put(FriendFieldEnum.EXTENSION, exts);
NIMClient.getService(FriendService.class).updateFriendFields(data, map).setCallback(callback);

获取好友信息

获取所有好友账号

调用 getFriendAccounts 方法获取所有好友账号。

该方法是同步方法，返回我的好友帐号集合。

示例代码如下：

javaList<String> friends = NIMClient.getService(FriendService.class).getFriendAccounts();

获取所有好友信息

调用 getFriends 方法获取所有好友信息。

javaList<Friend> friends = NIMClient.getService(FriendService.class).getFriends();

根据账号获取好友信息

调用 getFriendByAccount 方法根据用户账号获取好友信息。

示例代码如下：

javaFriend friend = NIMClient.getService(FriendService.class).getFriendByAccount("account");

好友搜索

根据备注名搜索好友列表

调用 searchAccountByAlias 方法从本地数据库搜索具有指定备注名的好友列表。

示例代码如下：

javaNIMClient.getService(FriendService.class).searchAccountByAlias("alias").setCallback(new RequestCallbackWrapper<List<String>>() {
    @Override
    public void onResult(int code, List<String> result, Throwable exception) {
        if (code == ResponseCode.RES_SUCCESS) {
            // 成功
        } else {
            // 失败，错误码见code
        }

        if (exception != null) {
            // error
        }
    }
});

根据备注名关键字搜索好友列表

调用 searchFriendsByKeyword 方法搜索与备注名的关键字匹配的所有好友列表。

java/**
 * 搜索与备注名的关键字匹配的所有好友
 *
 * @param keyword 关键字
 * @return 好友集合
 */
InvocationFuture<java.util.List<Friend>> searchFriendsByKeyword(java.lang.String keyword);