z-docs/docs/intro.md

sidebar_position
1

ZHub 快速上手

概述

zhub是⼀个⾼性能事件发布订阅服务组件，功能丰富，包含发布-订阅、⼴播消息、延时消息、 Rpc调⽤、分布式定时调度、分布式锁，运⾏包仅有1M+；低服务资源消费，初始启动内存 10M-。

---

开始 搭建 zhub 服务

让我们在 5到10分钟内完成 zhub 中间件安装、集成、测试.

下载软件包

• zhub.zip (点击下载) 包含以下内容:
  • zhub-client-0.1.1.dev.jar 常规Java 项目驱动包
  • zhub-client-spring-0.1.1.jar springboot 项目驱动包
  • zhub.exe Window 运行包
  • zhub.sh Linux 运行包
  • zhub Mac 运行包
  • app.ini 配置文件

配置 app.ini

# app.ini
[service]
watch=0.0.0.0:711           # 服务管理端口
addr=0.0.0.0:1216           # 服务端口
auth=0                      # 是否开启连接授权 0不开启、1开启

[data]
dir=./data                  # 数据目录

[log]
handlers=console            # console|file
level=debug                 # info|debug|error
file=zhub.log

[ztimer]                    # ztimer 配置 (可选，如果不使用定时调度则可不配置)
# db.addr=127.0.0.1:3306    # timer 使用的MySql数据库配置
# db.user=root
# db.password=123456
# db.database=zhub

---

初始化 ztimer 数据库 (可选，如果不使用定时调度则不需要配置)

CREATE DATABASE zhub;
CREATE TABLE `zhub`.`tasktimer` (
  `timerid` varchar(64) NOT NULL DEFAULT '' COMMENT '[主键]UUID',
  `name` varchar(32) NOT NULL DEFAULT '' COMMENT '[任务名称]',
  `expr` varchar(32) NOT NULL DEFAULT '' COMMENT '[时间表达式]',
  `single` int NOT NULL DEFAULT '1' COMMENT '[单实例消费]1单对象，0不限',
  `remark` varchar(128) NOT NULL DEFAULT '' COMMENT '[备注]',
  `status` smallint NOT NULL DEFAULT '10' COMMENT '[状态]10启用,60停用',
  PRIMARY KEY (`timerid`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
# 初始化 四个定时任务配置, 订阅名称分别为 T:A、T:B、T:C、T:D 
INSERT INTO `zhub`.`tasktimer` (`timerid`, `name`, `expr`, `single`, `remark`, `status`) VALUES 
  ('T1', 'T:A', '*/5 * * * * ?', 1, '每5秒执行一次', 10),
  ('T2', 'T:B', '15s', 1, '每15秒执行一次', 10),
  ('T3', 'T:C', '0 0 0 * * 1', 0, '每周一00:00执行', 10),
  ('T4', 'T:D', '0 0 24 * * ?', 1, '每天00:00执行', 10);

启动服务

# window 
./zhub.exe
# linux (添加执行权限 chmod +x ./zhub.sh)
./zhub.sh

---

连接使用

导入连接驱动 (根据不同的项目选择不同的导入方式)

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

<!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-0.1.1.dev.jar ） -->
<repositories>
    <repository>
        <id>maven-nexus</id>
        <name>maven-nexus</name>
        <url>https://nexus.1216.top/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
<!-- 常规Java项目 -->
<dependency>
    <groupId>net.tccn</groupId>
    <artifactId>zhub-client</artifactId>
    <version>0.1.1.dev</version>
</dependency>
</dependencies>

<!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-spring-0.1.1.jar ） -->
<repositories>
    <repository>
        <id>maven-nexus</id>
        <name>maven-nexus</name>
        <url>https://nexus.1216.top/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
<!-- 常规Java项目 -->
<dependency>
    <groupId>net.tccn</groupId>
    <artifactId>zhub-client-spring</artifactId>
    <version>0.1.1.dev</version>
</dependency>
</dependencies>

<!-- maven 导入依赖 （或直接导入下载包中的 zhub-client-redkale-0.1.1.jar ） -->
<repositories>
    <repository>
        <id>maven-nexus</id>
        <name>maven-nexus</name>
        <url>https://nexus.1216.top/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
<!-- 常规Java项目 -->
<dependency>
    <groupId>net.tccn</groupId>
    <artifactId>zhub-client-redkale</artifactId>
    <version>0.1.1.dev</version>
</dependency>
</dependencies>

配置初始化

  // 参数说明：①连接地址ip+端口， ②消费者组名称，③连接APPID (接入的多个客户端使用不同的连接APPID)
  ZHubClient zhub = new ZHubClient("127.0.0.1:1216", "groupid-x", "appid-x");

# application.yml
zhub:
  addr: 47.107.112.45:1216
  groupid: groupid-x
  appid: zhub_demo_1
  # auth: token-12345 # 启用 auth情况下接入验权配置

  // 自动注入连接对象
  @Autowired
  protected ZHubClient zhub;

# source.properties
redkale.cluster.zhub[zhub].addr = 127.0.0.1:1216
redkale.cluster.zhub[zhub].auth = token-12345
redkale.cluster.zhub[zhub].groupid = zcore-zhub
# redkale.cluster.zhub[zhub].appid = zhub_demo_1 # (无需配置，取 redklae 配置的 appname)

  // 自动注入连接对象
  @Resource(name = "zhub")
  protected ZHubClient zhub;

---

使用 zhub 收发消息

通过上面的操作，我们已经得到了一个 zhub 的连接实例，下面来看看具体的使用

1、消息的发布-订阅

  zhub.subscribe("topic-a", x -> {
      System.out.println("接收到 a 事件：" + x);
  });

  zhub.publish("topic-a", "123");

2、rpc的订阅-调用

  zhub.rpcSubscribe("rpc-b", IType.STRING, r -> {
      String str = r.getValue();
      System.out.println("接收到 b 事件：" + str);
      return r.render("接收到 b 事件：" + str);
  });

  RpcResult<String> rpcResult = zhub.rpc("rpc-b", "hello rpc", IType.STRING);
  String result = rpcResult.getResult();
  System.out.println("rpc result:" + result);

3、广播消息

  zhub.broadcast("topic-a", "123");

4、延时消息

  zhub.delay("topic-a", "123", 1000 * 60 * 5);

5、定时调度

  zhub.timer("T:A", () -> {
      System.out.println("收到定时调度事件：T:A");
  });

6、分布式锁

  // 获取锁，直到索取到锁后返回
  Lock lock = zhub.lock("lock-a", 5);
  try {
      System.out.println("获取到锁");
  } finally {
      lock.unLock();
  }

  // 尝试获取锁，立即返回
  Lock lock = zhub.tryLock("lock-a", 5);
  if (!lock.success()) {
    System.out.println("未获取到锁");
    return;
  }
  
  // 获取到锁
  try {
      System.out.println("获取到锁");
  } finally {
      lock.unLock();
  }