快速入门
<p>[TOC]</p>
<h2>初始化BEN数据库</h2>
<p>下载项目源码并解压，执行 "BEN数据库初始化SQL脚本"，正常情况下会自动创建数据库（<strong>cn-ben</strong>）以及生成<strong>7</strong>张表（两张核心表<strong>t_notify_record</strong>、<strong>t_notify_log</strong>，其他为管理后台所需的账号、资源、角色等基础信息表）。"BEN数据库初始化SQL脚本" 路径为:</p>
<pre><code>/cn-ben/sql/ben-init.sql</code></pre>
<h2>编译运行BEN</h2>
<h3>编译源码</h3>
<p>按照maven格式将源码导入IDE, 使用maven进行编译即可。</p>
<h4>Maven模块描述</h4>
<table>
<thead>
<tr>
<th>模块名称</th>
<th>描述</th>
</tr>
</thead>
<tbody>
<tr>
<td>ben-api</td>
<td>提供业务系统使用的Ben实体类等</td>
</tr>
<tr>
<td>ben-service-api</td>
<td>基础通知服务接口、系统工具类、实体类封装</td>
</tr>
<tr>
<td>ben-service</td>
<td>基础通知服务接口实现、通知管理子系统服务接口实现</td>
</tr>
<tr>
<td>ben-cms-api</td>
<td>通知管理子系统服务接口、实体类封装</td>
</tr>
<tr>
<td>ben-cms</td>
<td>通知管理子系统，提供通知记录、通知日志的管理后台</td>
</tr>
<tr>
<td>ben-dal</td>
<td>数据库访问层： sql语句</td>
</tr>
</tbody>
</table>
<hr />
<h3>ben-service配置、运行</h3>
<h4>配置ben-service</h4>
<p>配置文件路径：</p>
<pre><code>/cn-ben/ben-service/src/main/resources/application-dev.yaml</code></pre>
<p>配置文件说明：</p>
<pre><code class="language-yaml">spring:
# 数据库连接配置
datasource:
url: jdbc:mysql://127.0.0.1:3306/cn-ben?useUnicode=true&characterEncoding=utf-8
username: root
password: xxxx
driver-class-name: com.mysql.jdbc.Driver
hikari:
connection-test-query: SELECT 1
# ActiveMQ连接配置
activemq:
broker-url: tcp://127.0.0.1:61616
user: admin
password: admin
# 邮箱配置
mail:
host: smtp.163.com
username: xxxx@163.com
password: xxxx
# 收件人
receiver: xxxx@qq.com
properties:
mail:
smtp:
auth: true
starttls:
enable: true
required: true
# Dubbo配置
dubbo:
application:
name: ben-service
logger: slf4j
registry:
address: zookeeper://127.0.0.1:2181
protocol:
name: dubbo
port: 20881
scan:
base-packages: com.cn.ben.service.impl
# 通知任务处理器配置
task:
handler:
core-pool-size: 10
max-pool-size: 100
keep-alive-time: 60000
queue-capacity: 10
handler-executor-sleep: 5000
interval:
- 0
- 1
- 4
- 10
- 30
- 60
- 120
- 360
- 900
# 系统监控配置
monitor:
# 内存监控
memory:
less-percent: 15
sleep-time: 120000
# 通知监控
notify:
not-finish-count: 1000
add-rate: 20</code></pre>
<h5>基础配置说明</h5>
<table>
<thead>
<tr>
<th>配置项</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>datasource</td>
<td>数据库相关配置，地址、账号、密码等</td>
</tr>
<tr>
<td>activemq</td>
<td>ActiveMQ相关配置，地址、账号、密码等</td>
</tr>
<tr>
<td>mail</td>
<td>邮箱相关配置，地址、账号、密码、收件人等</td>
</tr>
<tr>
<td>dubbo</td>
<td>Dubbo服务相关配置，服务名称、注册中心地址、服务端口等</td>
</tr>
</tbody>
</table>
<h5>特殊配置说明</h5>
<table>
<thead>
<tr>
<th>配置项</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>core-pool-size</td>
<td>通知任务处理器-线程池最小线程数</td>
</tr>
<tr>
<td>max-pool-size</td>
<td>通知任务处理器-线程池最大线程数</td>
</tr>
<tr>
<td>keep-alive-time</td>
<td>通知任务处理器-线程运行的空闲时间（单位：毫秒）</td>
</tr>
<tr>
<td>queue-capacity</td>
<td>通知任务处理器-线程池缓存队列大小</td>
</tr>
<tr>
<td>handler-executor-sleep</td>
<td>处理器线程池睡眠时间（单位：毫秒） 当处理通知任务的线程池耗尽时，通知任务处理器将睡眠一段时间</td>
</tr>
<tr>
<td>interval</td>
<td>重复通知时间间隔（单位：分钟） 举例： [0, 1, 4, 10, 30, 60] 第一次立即通知，如果业务方没有返回成功，则1分钟后再次通知。如果业务方还是没有返回成功，则4分钟后再次通知。以此类推</td>
</tr>
<tr>
<td>less-percent</td>
<td>内存不足百分比 计算公式：(vmMax - vmTotal + vmFree) < (vmMax * Percent / 100)，即：剩余内存 < 最大内存 * Percent 内存不足时，系统有两个应对策略： 1、发送告警邮件。 2、通知任务在保存到数据库后，只执行一次通知, 无论通知成功或失败，更新通知结果到数据库，并将任务信息从内存中释放, 内存监听器将休眠一段时候后重新计算内存情况，直到内存足够后，从数据库中读取休眠期间未通知成功的通知记录，继续通知。</td>
</tr>
<tr>
<td>sleep-time</td>
<td>内存不足休眠时间（单位：毫秒）</td>
</tr>
<tr>
<td>not-finish-count</td>
<td>通知监听器会监控未完成（未通知、通知异常、业务方处理失败）的通知消息总数，当数量达到阈值则发送告警邮件</td>
</tr>
<tr>
<td>add-rate</td>
<td>未完成通知消息数的增长速率超过阈值则发送告警邮件</td>
</tr>
</tbody>
</table>
<h4>运行ben-service</h4>
<p>模块基于SpringBoot构建，可使用Maven命令(mvn package)打成jar包运行（java -jar）。
调试阶段可直接在IDE中运行ServiceApplication。文件路径为：</p>
<pre><code>/cn-ben/ben-service/src/main/java/com/cn/ben/service/ServiceApplication.java</code></pre>
<h4>集群（可选）</h4>
<p>由于项目基于Dubbo框架搭建，因此项目默认支持集群部署，只需将ben-service模块jar包运行在不同服务器上。即可完成ben-service集群搭建。</p>
<hr />
<h3>ben-cms配置、运行（可选）</h3>
<h4>配置ben-cms</h4>
<p>配置文件路径：</p>
<pre><code>/cn-ben/ben-cms/src/main/resources/application-dev.yaml</code></pre>
<p>配置文件说明：</p>
<pre><code class="language-yaml"># ben-cms运行端口和访问根路径，可根据自身情况配置
server:
port: 10081
servlet:
context-path: /ben-cms
# Dubbo配置
dubbo:
application:
name: ben-cms
logger: slf4j
registry:
address: zookeeper://127.0.0.1:2181
consumer:
check: false</code></pre>
<h4>运行ben-cms</h4>
<p>模块基于SpringBoot构建，可使用Maven命令(mvn package)打成jar包运行（java -jar）。
调试阶段可直接在IDE中运行CmsApplication。文件路径为：</p>
<pre><code>/cn-ben/ben-cms/src/main/java/com/cn/cms/service/CmsApplication.java</code></pre>
<h2>业务系统对接BEN</h2>
<h4>maven依赖</h4>
<p>在业务系统的pom文件中引入ben-api最新版本依赖：</p>
<pre><code># 中央仓库： https://search.maven.org/search?q=ben-api
<dependency>
<groupId>com.gitee.nuliing</groupId>
<artifactId>ben-api</artifactId>
<version>${最新稳定版本}</version>
</dependency></code></pre>
<h4>发送通知</h4>
<p>步骤：</p>
<ul>
<li>构造通知参数<strong>BenNotify</strong></li>
<li>往消息队列发送通知对象（队列名：<strong>notify.queue</strong>，已定义为静态变量<strong>BenNotify.QUEUE</strong>）</li>
</ul>
<p>SpringBoot示例代码：</p>
<pre><code>/cn-ben/ben-boot-sample/</code></pre>
<pre><code>import org.springframework.jms.core.JmsMessagingTemplate;
import com.cn.ben.api.model.BenNotify;
@Autowired
private JmsMessagingTemplate jmsMessagingTemplate;
public void sendNotify() {
// 构造通知参数
BenNotify notify = new BenNotify();
notify.setNotifyUrl("http://127.0.0.1:10081/sample/notify/post/form");
// 发送通知
jmsMessagingTemplate.convertAndSend(BenNotify.QUEUE, notify);
}</code></pre>
<h4>BenNotify参数说明</h4>
<table>
<thead>
<tr>
<th>参数</th>
<th>类型</th>
<th>说明</th>
<th>必须</th>
<th>默认值</th>
</tr>
</thead>
<tbody>
<tr>
<td>notifyUrl</td>
<td>String</td>
<td>通知-请求地址</td>
<td>是</td>
<td>无</td>
</tr>
<tr>
<td>notifyMethod</td>
<td>MethodEnum</td>
<td>通知-请求方式 0:GET, 1:POST, 2:HEAD, 3:OPTIONS, 4:PUT, 5:DELETE, 6:TRACE, 7:CONNECT, 8:PATCH</td>
<td>是</td>
<td>POST</td>
</tr>
<tr>
<td>notifyHeader</td>
<td>Map<String, String></td>
<td>通知-请求头</td>
<td>否</td>
<td>无</td>
</tr>
<tr>
<td>notifyParam</td>
<td>String</td>
<td>通知-请求参数</td>
<td>否</td>
<td>无</td>
</tr>
<tr>
<td>notifyParamType</td>
<td>ParamTypeEnum</td>
<td>通知-请求参数类型 0:FORM 1:BODY</td>
<td>是</td>
<td>FORM</td>
</tr>
<tr>
<td>notifyTimeout</td>
<td>Short</td>
<td>通知-请求超时时长，单位：毫秒</td>
<td>是</td>
<td>5000</td>
</tr>
<tr>
<td>successFlag</td>
<td>String</td>
<td>通知-成功响应标识（http请求响应包含此内容时即通知成功）（设为空或空字符串时，http响应码为2xx即通知成功）</td>
<td>否</td>
<td>无</td>
</tr>
<tr>
<td>businessFailContinue</td>
<td>Boolean</td>
<td>通知-Http请求成功但业务方未返回成功响应标识时（即业务方处理失败），是否继续通知</td>
<td>是</td>
<td>true</td>
</tr>
<tr>
<td>businessName</td>
<td>String</td>
<td>本次通知的业务名称，非必填，根据业务实际情况，用于后期流程跟踪或异常排查时使用</td>
<td>否</td>
<td>无</td>
</tr>
<tr>
<td>businessId</td>
<td>String</td>
<td>本次通知的业务方记录ID，非必填，根据业务实际情况，用于后期流程跟踪或异常排查时使用</td>
<td>否</td>
<td>无</td>
</tr>
</tbody>
</table>