lxy/z-docs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

完善：zhub快速上手页面

Browse Source
This commit is contained in:
绝尘
2023-11-28 20:24:54 +08:00
parent 5fbc3082c7
commit 4c55967ce2
30 changed files with 245 additions and 11771 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
docs/intro.md
View File

@@ -2,47 +2,75 @@
sidebar_position: 1
---
# 快速开始
# ZHub 快速上手
让我们在 **5分钟内完成 zhub 组件安装**.
## 概述
> zhub是⼀个⾼性能事件发布订阅服务组件，功能丰富，包含发布-订阅、⼴播消息、延时消息、
Rpc调⽤、分布式定时调度、分布式锁，运⾏包仅有1M+；低服务资源消费，初始启动内存 10M-。
## 开始
![zhub-fun.png](https://img.1216.top/docs/zhub/zhub-fun.png)
从零开始 **搭建 zhub 服务**.
---
## 开始 搭建 zhub 服务
> 让我们在 **5到10分钟内完成 zhub 中间件安装、集成、测试**.
### 下载软件包
- [zhub.zip](https://baidu.com) 包含以下内容:
- 绿色版本 Window 和 Linux 运行包
- 配置文件: app.ini
- java连接驱动：zhub-clien.jar
![zhub-zip.png](https://img.1216.top/docs/zhub-zip.png)
- [zhub.zip (点击下载)](https://img.1216.top/docs/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` 配置文件
![zhub-zip.png](https://img.1216.top/docs/zhub/dist-zip.png)
### 配置 app.ini
```bash
# app.ini
[log]
handlers=console # console|file
level=debug # info|debug|error
file=zhub.log
[service]
watch=0.0.0.0:711
addr=0.0.0.0:1216
auth=1 # 是否开启连接授权
watch=0.0.0.0:711 # 服务管理端口
addr=0.0.0.0:1216 # 服务端口
auth=0 # 是否开启连接授权 0不开启、1开启
[data]
dir=D:/data # 数据目录
dir=./data # 数据目录
[ztimer] # timer 使用的数据库配置
db.addr=47.111.150.118:6063
db.user=root
db.password=*Zhong@0510!
db.database=zhub
[log]
handlers=console # console|file
level=debug # info|debug|error
file=zhub.log
[auth]
admin=123456 # 授权连接账号 admin@123456
lxy=123456
[ztimer] # ztimer 配置 (可选，如果不使用定时调度则可不配置)
# db.addr=127.0.0.1:3306 # timer 使用的MySql数据库配置
# db.user=root
# db.password=123456
# db.database=zhub
```
---
### 初始化 ztimer 数据库 (可选，如果不使用定时调度则不需要配置)
```sql
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);
```
### 启动服务
@@ -50,21 +78,196 @@ lxy=123456
```bash
# window
./zhub.exe
# linux
# linux (添加执行权限 chmod +x ./zhub.sh)
./zhub.sh
```
---
## 使用
## 连接使用
### 导入连接驱动 (根据不同的项目选择不同的导入方式)
### Java 客户端连接
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```java
ZhubClient zhub = new ZhubClient("", "");
zhub.subscribe("topic-x", x -> {
// do something.
});
<Tabs>
<TabItem value="apple" label="普通Java项目" default>
```xml
<!-- 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>
```
</TabItem>
<TabItem value="orange" label="SpringBoot 项目">
```xml
<!-- 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>
```
</TabItem>
<TabItem value="banana" label="Redkale项目">
```xml
<!-- 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>
```
</TabItem>
</Tabs>
### 配置初始化
<Tabs>
<TabItem value="apple" label="普通Java项目" default>
```
// 参数说明：①连接地址ip+端口， ②消费者组名称，③连接APPID (接入的多个客户端使用不同的连接APPID)
ZHubClient zhub = new ZHubClient("127.0.0.1:1216", "groupid-x", "appid-x");
```
### Java 客户端连接
</TabItem>
<TabItem value="orange" label="SpringBoot 项目">
```yml
# application.yml
zhub:
addr: 47.107.112.45:1216
groupid: groupid-x
appid: zhub_demo_1
# auth: token-12345 # 启用 auth情况下接入验权配置
```
```java
// 自动注入连接对象
@Autowired
protected ZHubClient zhub;
```
</TabItem>
<TabItem value="banana" label="Redkale项目">
```yaml
# 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)
```
```java
// 自动注入连接对象
@Resource(name = "zhub")
protected ZHubClient zhub;
```
</TabItem>
</Tabs>
---
### 使用 zhub 收发消息
> 通过上面的操作，我们已经得到了一个 zhub 的连接实例，下面来看看具体的使用
>
1、消息的发布-订阅
```java
zhub.subscribe("topic-a", x -> {
System.out.println("接收到 a 事件：" + x);
});
```
```java
zhub.publish("topic-a", "123");
```
2、rpc的订阅-调用
```java
zhub.rpcSubscribe("rpc-b", IType.STRING, r -> {
String str = r.getValue();
System.out.println("接收到 b 事件：" + str);
return r.render("接收到 b 事件：" + str);
});
```
```java
RpcResult<String> rpcResult = zhub.rpc("rpc-b", "hello rpc", IType.STRING);
String result = rpcResult.getResult();
System.out.println("rpc result:" + result);
```
3、广播消息
```java
zhub.broadcast("topic-a", "123");
```
4、延时消息
```java
zhub.delay("topic-a", "123", 1000 * 60 * 5);
```
5、定时调度
```java
zhub.timer("T:A", () -> {
System.out.println("收到定时调度事件：T:A");
});
```
6、分布式锁
```java
// 获取锁，直到索取到锁后返回
Lock lock = zhub.lock("lock-a", 5);
try {
System.out.println("获取到锁");
} finally {
lock.unLock();
}
```
```java
// 尝试获取锁，立即返回
Lock lock = zhub.tryLock("lock-a", 5);
if (!lock.success()) {
System.out.println("未获取到锁");
return;
}
// 获取到锁
try {
System.out.println("获取到锁");
} finally {
lock.unLock();
}
```

7
docs/oth/_category_.json
View File

@@ -1,7 +0,0 @@
{
"label": "其他常用",
"position": 5,
"link": {
"type": "generated-index"
}
}

18
docs/oth/a.md
View File

@@ -1,18 +0,0 @@
---
sidebar_position: 1
---
# 一些命令
```shell title='在 Windows 环境下，项目打包成 zip 文件：'
# rem 请将“my-site”替换为您想要命名的 zip 文件名称,这将创建一个名为 "my-site.zip" 的 zip 文件。
powershell Compress-Archive -Path build -DestinationPath my-site.zip
```
```shell title='docusaurus 常用命令'
pnpm run build # 构建
pnpm run start # 启动
pnpm run serve # 启动（服务模式）
```

7
docs/redkale/_category_.json
View File

@@ -1,7 +0,0 @@
{
"label": "Redkale",
"position": 4,
"link": {
"type": "generated-index"
}
}

5
docs/redkale/advanced-features.md
View File

@@ -1,5 +0,0 @@
---
sidebar_position: 3
---
# 进阶功能

7
docs/redkale/advanced-features/_category_.json
View File

@@ -1,7 +0,0 @@
{
"label": "进阶功能",
"position": 3,
"link": {
"type": "generated-index"
}
}

6
docs/redkale/core-features.md
View File

@@ -1,6 +0,0 @@
---
sidebar_position: 2
---
# 核心功能

7
docs/redkale/core-features/_category_.json
View File

@@ -1,7 +0,0 @@
{
"label": "核心功能",
"position": 2,
"link": {
"type": "generated-index"
}
}

77
docs/redkale/getting-started.md
View File

@@ -1,77 +0,0 @@
---
sidebar_position: 1
---
# 快速开始
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="apple" label="Apple" default>
This is an apple 🍎
</TabItem>
<TabItem value="orange" label="Orange">
This is an orange 🍊
</TabItem>
<TabItem value="banana" label="Banana">
This is a banana 🍌
</TabItem>
</Tabs>
好的，以下是对应的文件名和目录结构：
- 1.md : 入门指南
- 1.1 安装和配置.md
- 1.2 Hello World.md
- 1.3 架构概述.md
- 2.md : 核心功能
- 2.1 控制器.md
- 2.2 过滤器.md
- 2.3 模板引擎.md
- 2.4 数据库访问.md
- 2.5 缓存.md
- 2.6 安全.md
- 2.7 日志.md
- 2.8 监控.md
- 3.md : 进阶功能
- 3.1 异步处理.md
- 3.2 高并发支持.md
- 3.3 集群部署.md
- 3.4 扩展机制.md
- 4.md : 工具支持
- 4.1 IDEA 插件.md
- 4.2 Maven 插件.md
- 4.3 工具集成.md
----
好的，以下是使用英文文件名的 Redkale 文档目录结构：
- getting-started: Getting Started
- 1-installation-and-configuration.md: Installation and Configuration
- 2-hello-world.md: Hello World
- 3-architecture-overview.md: Architecture Overview
- core-features: Core Features
- 1-controller.md: Controller
- 2-filter.md: Filter
- 3-template-engine.md: Template Engine
- 4-database-access.md: Database Access
- 5-cache.md: Cache
- 6-security.md: Security
- 7-logging.md: Logging
- 8-monitoring.md: Monitoring
- advanced-features.md: Advanced Features
- 1-asynchronous-processing.md: Asynchronous Processing
- 2-high-concurrency-support.md: High Concurrency Support
- 3-clustering-deployment.md: Clustering Deployment
- 4-extension-mechanism.md: Extension Mechanism
- tool-support.md: Tool Support
- 1-idea-plugin.md: IDEA Plugin
- 2-maven-plugin.md: Maven Plugin
- 3-tool-integration.md: Tool Integration
请注意，文件名以及目录结构只是一种规范，您可以根据实际需求进行修改和扩展。同时编写文档时要尽可能地清晰简洁、易于阅读和理解，并且遵循文档写作的标准规范和最佳实践。
请注意，本程序只能进行文档基础目录结构的整理，具体内容需要您自己针对 Redkale 进行整理编写。另外，如有需要，您还可以进一步细分和拓展目录结构，以适应实际需求。

7
docs/redkale/getting-started/_category_.json
View File

@@ -1,7 +0,0 @@
{
"label": "快速开始",
"position": 1,
"link": {
"type": "generated-index"
}
}

5
docs/redkale/getting-started/architecture-overview.md
View File

@@ -1,5 +0,0 @@
---
sidebar_position: 3
---
# 架构概述

5
docs/redkale/getting-started/hello-world.md
View File

@@ -1,5 +0,0 @@
---
sidebar_position: 2
---
# 第一个程序

5
docs/redkale/getting-started/installation-and-configuration.md
View File

@@ -1,5 +0,0 @@
---
sidebar_position: 1
---
# 安装配置

5
docs/redkale/tool-support.md
View File

@@ -1,5 +0,0 @@
---
sidebar_position: 4
---
# 工具支持

7
docs/redkale/tool-support/_category_.json
View File

@@ -1,7 +0,0 @@
{
"label": "工具支持",
"position": 4,
"link": {
"type": "generated-index"
}
}

8
docs/tutorial-basics/_category_.json
View File

@@ -1,8 +0,0 @@
{
"label": "基础使用",
"position": 2,
"link": {
"type": "generated-index",
"description": "完成 ZHub 服务安装后，来看看一遍就会的基础使用文档~"
}
}

32
docs/tutorial-basics/broadcast.md
View File

@@ -1,32 +0,0 @@
---
sidebar_position: 3
title: 广播消息
description: 发送、接收广播消息
---
:::tip
消息接收
广播消息的消息接收，与主题消息、延时消息 api一致，且使用了相同 topic 命名空间
- 消息接收
- 广播消息发送
:::
## 消息接收
> [广播消息接收](publish-subscribe.md#订阅主题消息)
## 广播消息发送
> 和发布订阅消息基本差不多
```java
private ZHubClient zhub;
@RestMapping(name = "publish_test", auth = false, comment = "发送广播消息测试")
public String publishTest(String value) {
zhub.broadcast("topic-a", value);
return "send ok!";
}
```

60
docs/tutorial-basics/create-connection.md
View File

@@ -1,60 +0,0 @@
---
sidebar_position: 0
title: 创建连接
description: 初始化客户端连接对象
---
:::tip
目前已提供三种客户端连接使用
- Java 项目
- [普通 Java 项目](#java通用)
- [使用 Redkale 的 Java 项目](#redkale框架-项目里面使用)
- [Golang 项目](#golang-项目中使用)
:::
---
## Java通用
> 在Java 项目中引入 zhub-client.jar
```java
private ZHubClient zhub;
@Before
public void init() {
// 参数说明：① ip:端⼝， ②消费者组名称， ③项⽬实例名（名称需全局唯⼀）④授权码
zhub = new ZHubClient("127.0.0.1:6066", "test-hub", "DEV-LOCAL", "user@pwd123");
}
```
---
## Redkale框架 项目里面使用
> 在Java的redkale 项目中引入 zhub-rekale.jar
> 在配置文件中配置zhub组件
```
# source.properties 中配置
############ ClusterSource @Resource(name="hub") ############
redkale.cluster.zhub[hub].addr = 127.0.0.1:6066
redkale.cluster.zhub[hub].auth = user@pwd123
redkale.cluster.zhub[hub].groupid = test-hub
```
> 在 service 中注入组件
>
```java
@Resource(name = "hub")
protected ZHubClient zhub;
```
## Golang 项目中使用
> 待补充
---

35
docs/tutorial-basics/delay.md
View File

@@ -1,35 +0,0 @@
---
sidebar_position: 2
title: 延时消息
description: zhub 的延时消息使用
---
:::tip
首先完成 **[连接创建](create-connection.md)** ，便可进行**延时消息**的发送和接收，
- [订阅主题消息](#订阅主题消息)
- [发送延时消息](#发送延时消息)
:::
## 订阅主题消息
> 见 [主题的订阅](publish-subscribe.md#订阅主题消息)
## 发送延时消息
> 参数说明：①主题名称 ②消息内容 ③延时多久，单位ms
> zhub.delay("topic-delay-a", "delay-value", 1000);
>
示例代码：
```java
private ZHubClient zhub;
@RestMapping(name = "delay_test", auth = false, comment = "发送延时主题消息测试")
public String delayTest(String value) {
zhub.delay("topic-delay-a", "delay-value", 1000);
return "send ok!";
}
```

41
docs/tutorial-basics/publish-subscribe.md
View File

@@ -1,41 +0,0 @@
---
sidebar_position: 1
title: 订阅&发布
description: zhub 创建客户端连接、订阅主题、发送主题消息
---
:::tip
发布-订阅（Publish-Subscribe）：消息中间件可以用于实现发布-订阅模式。发布者将消息发布到一个或多个主题（Topic），而订阅者订阅感兴趣的主题。当有新的消息发布到主题时，所有订阅了该主题的订阅者都会接收到消息。这样可以实现一对多的消息传递，降低发送方和接收方之间的耦合性。
首先完成 **[连接创建](create-connection.md)** ，便可进行消息的发送和接收，
- [订阅主题消息](#订阅主题消息)
- [发送主题消息](#发送主题消息)
:::
## 订阅主题消息
```java
// 事件订阅
zhub.subscribe("topic-a", x -> {
System.out.println("接收到主题 topic-a 事件，消息内容：" + x);
});
```
## 发送主题消息
测试发送主题消息
```java
private ZHubClient zhub;
@RestMapping(name = "publish_test", auth = false, comment = "发送主题消息测试")
public String publishTest(String value) {
zhub.publish("topic-a", value);
return "send ok!";
}
```
这个时候，将会在订阅端收到主题订阅消息，并在控制台输出： `接收到主题 topic-a 事件，消息内容：xx` 的消息内容

7
docs/tutorial-extras/_category_.json
View File

@@ -1,7 +0,0 @@
{
"label": "其他组件",
"position": 3,
"link": {
"type": "generated-index"
}
}

BIN
docs/tutorial-extras/img/docsVersionDropdown.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 25 KiB

BIN
docs/tutorial-extras/img/localeDropdown.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 27 KiB

5
docs/tutorial-extras/lock.md
View File

@@ -1,5 +0,0 @@
---
sidebar_position: 2
---
# 分布式锁

7
docs/tutorial-extras/rpc.md
View File

@@ -1,7 +0,0 @@
---
sidebar_position: 1
---
# RPC远程调用
#

5
docs/tutorial-extras/timer.md
View File

@@ -1,5 +0,0 @@
---
sidebar_position: 2
---
# 定时调度