azure-messaging-webpubsub-java

用途

Azure Web PubSub SDK for Java 用于构建实时 Web 应用程序，基于 WebSocket 实现消息传递。适用于实现 WebSocket 消息通信、实时更新、聊天应用等场景。

安装

通过 Maven 引入依赖：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-webpubsub</artifactId>
    <version>1.5.0</version>
</dependency>

核心概念

Hub：连接之间的逻辑隔离单元
Group：Hub 内连接的子集
Connection：单个 WebSocket 客户端连接
User：可拥有多个连接的实体

客户端创建

支持三种认证方式：连接字符串、访问密钥（AzureKeyCredential + endpoint）、DefaultAzureCredential。也可构建异步客户端 WebPubSubServiceAsyncClient。

WebPubSubServiceClient client = new WebPubSubServiceClientBuilder()
    .connectionString("<connection-string>")
    .hub("chat")
    .buildClient();

主要能力

消息发送

发送给所有连接：sendToAll，支持 TEXT_PLAIN 与 APPLICATION_JSON 内容类型
带过滤发送：sendToAllWithResponse，可通过 filter 查询参数按 userId 或 groups 过滤
发送给组：sendToGroup
发送给指定连接：sendToConnection
发送给用户：sendToUser

组管理

addConnectionToGroup / removeConnectionFromGroup
addUserToGroup / removeUserFromGroup
userExistsInGroup 检查用户是否在组内

连接管理

connectionExists 检查连接是否存在
closeConnection 关闭连接，可带原因
userExists 检查用户是否有连接
closeUserConnections 关闭用户所有连接
closeGroupConnections 关闭组内所有连接

客户端访问令牌

通过 getClientAccessToken 生成，可设置 userId、角色（addRole）、连接时加入的组（addGroup）以及过期时间（setExpiresAfter）。

权限管理

grantPermission 授予权限
revokePermission 撤销权限
checkPermission 检查权限

权限类型如 WebPubSubPermission.SEND_TO_GROUP，配合 targetName 查询参数指定目标。

异步操作

异步客户端返回响应式类型，可通过 subscribe、doOnSuccess、doOnError 处理结果与错误。

错误处理

捕获 HttpResponseException，可获取状态码与错误信息。

环境变量

WEB_PUBSUB_CONNECTION_STRING=Endpoint=https://<resource>.webpubsub.azure.com;AccessKey=...
WEB_PUBSUB_ENDPOINT=https://<resource>.webpubsub.azure.com
WEB_PUBSUB_ACCESS_KEY=<your-access-key>

客户端角色

角色	权限
webpubsub.joinLeaveGroup	加入/离开任意组
webpubsub.sendToGroup	发送到任意组
webpubsub.joinLeaveGroup.<group>	加入/离开指定组
webpubsub.sendToGroup.<group>	发送到指定组

最佳实践

使用组组织连接以实现定向消息
将连接与用户 ID 关联以支持用户级消息
设置合适的令牌过期时间
通过角色授予最小必要权限
为不同应用功能使用独立 Hub
清理不活跃连接

适用场景

聊天应用后端、实时推送通知、实时更新广播、WebSocket 消息通信等。

限制

仅在任务明确匹配上述范围时使用。输出不应替代针对具体环境的验证、测试或专家审查。若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。