quan-chat

quan-chat 是一个基于 Netty 实现的服务端即时消息通讯组件，组件本身不具备业务处理能力，主要的作用是提供服务端消息中转； 通过实现组件中的接口可以完成与项目相关的业务功能， 例如：点对点消息收发、权限校验、聊天记录保存等。

quan-chat-bff 接入了 quan-chat 实现了一个聊天服务的雏形，仅实现比较简单的点对点消息发送与接收功能， 不具备正式使用能力，当前仅用于学习交流使用。 web 端采用了 layim 框架。

警告

本项目中应用的 layim 来源于互联网，仅用于学习交流使用。若您将其用于其它用途，必须取得原作者的授权: layui.dev 。否则产生的一切法律责任与 Quan 开发团队无关。

使用方法

配置好端口即可使用。当未配置端口时，组件不会执行初始化服务。

建议使用 Nginx 反向代理服务，通过 Nginx 完成SSL配置。这样 quan-chat 组件则不需要开启 SSL 配置。 否则若项目配置了 https 访问，quan-chat 服务必须开启 SSL。

引入工具依赖包。

gradle

dependencies {
    api project(':quan-tools:quan-chat')
}

yml配置：

quan:
  im:
    port: 10000
    websocket-path: /chat
    reader-idle-time: 1800 #允许连接空闲的时间，单位：秒。超时后强制下线
    ssl:
      enabled: true
      # /// 仅测试使用的SSL自签证书。正式使用时，请替换为自己的证书
      key-cert-chain-file-path: /quan/quan-app/quan-chat-bff/src/main/resources/test_cert.pem
      key-file-path: /quan/quan-app/quan-chat-bff/src/main/resources/test_private_pkcs8.pem

配置说明

port

• 类型：int
• 默认： null

配置 chat 服务的端口，只有配置了端口时，服务才会自动启动。

websocketPath

• 类型：string
• 默认： null

配置 websocket 访问的路径

readerIdleTime

• 类型：long
• 默认： 600

允许客户端连接空闲的最大时间，当空闲超过最大时间后，强制客户端下线。单位：秒

maxFrameSize

• 类型：int
• 默认： 65536

默认数据包最大长度，单位：字节

maxContentLength

• 类型：int
• 默认： 65536

消息体最大长度，单位：字节

---

SSL配置

enabled

• 类型：boolean
• 默认： false

是否开启SSL配置，当开启SSL配置时，将启动带有凭证的 chat 服务。此时要求必须配置 SSL证书。

keyCertChainFilePath

• 类型：string
• 默认： null

PEM格式的X.509证书链文件路径，当开启SSL配置时，必须。

keyFilePath

• 类型：string
• 默认： null

PEM格式的PKCS8私钥文件路径，当开启SSL配置时，必须。

启动的服务类说明

ChatServer

当未配置 SSL 时启动一个 chat 服务，该服务要求通过 ws 协议连接。

SecureChatServer

当配置 SSL 时启动一个加密的 chat 服务，该服务要求通过 wss 协议连接。

---

请求参数：

参数	类型	是否必须	说明
userId	String	是	用户唯一标识
authorization	String	是	用户的登录授权凭证

示例：

wss://localhost:10000/chat?userId=10000
ws://localhost:10000/chat?userId=10000

消息处理器说明-IMessageHandler

提供给业务端实现的消息处理器接口，必须按照 消息类型 实现相关的接口。 例如：消息类型为 friend ，则实现类应该命名为：FriendMessageHandler

当前系统默认定义的 消息类型（可以按照自己的需求扩展或修改）：

类型	说明
friend	好友消息
group	群组消息
admin	管理员消息
system	系统通知消息

处理客户端发送的消息-handler

当服务器接收到客户端的消息时，会根据消息类型调用 handler 方法。并传入处理好的消息模版，此时需要接口自行处理相关的业务逻辑。

示例：

/**
 * 实现一个好友消息处理器
 *
 * 命名格式：消息类型 + MessageHandler
 * 例如：消息类型为 friend ，则实现类应该命名为：FriendMessageHandler
 *
 * @author javaquan
 */
@Component
public class FriendMessageHandler extends AbstractMessageHandler implements IMessageHandler {
    @Override
    public void handler(ChannelHandlerContext ctx, MessageTemplate messageTemplate) {
        /// 通知发送者，接受者不在线，发送离线消息。
        if (!sendMessage(messageTemplate)) {
            sendMessage(ctx.channel(), ChatMessage.toSystemMessage("A100", "好友不在线"));
        }
        /// TODO 保存聊天记录。
        /// 过程省略...  请自行实现
    }
}

凭证处理器-AuthorizationProcessor

当客户端请求连接服务器时，会携带登录认证信息。默认 quan-chat 组件不处理该凭证，但提供了对应的接口。需要自行实现该接口，完成凭证校验规则。

当凭证校验成功时，将会与服务器建立连接通道。建立通道后，即可实现消息收发。

处理客户端发送的消息-checkAuth

请求参数：

参数	类型	是否必须	说明
authorization	String	是	用户的登录授权凭证

返回参数：

• true：凭证校验成功
• false：凭证校验失败

示例：

/**
 * 实现一个自定义登录凭证处理器
 *
 * @author javaquan
 */
@Component
public class CustomAuthorizationProcessor implements AuthorizationProcessor {

    /**
     * 检查客户端发起的连接是否合法
     * 
     * @param authorization 登录凭证
     * @return
     */
    @Override
    public boolean checkAuth(String authorization) {
        /// 校验登录凭证是否合法 过程省略...

        // 当凭证校验通过时，返回 true
        return true;
    }
}