通用平台 on Macula

统一认证

Mon, 01 Jan 0001 00:00:00 +0000

概览

基于spring-authorization-server开发的支持的FORM、OAUTH2、CAS、SAML等协议的统一认证平台。

组件坐标

IAM 为独立部署的平台服务。应用通过网关的 OAuth2 Resource Server 接入，配置方式见下节；不存在独立的 IAM Starter 坐标。

使用配置

spring:
	security:
 oauth2:
 resourceserver:
 opaquetoken:
 client-id: e4da4a32-592b-46f0-ae1d-784310e88423
 client-secret: secret
 introspection-uri: http://127.0.0.1:9010/oauth2/introspect  # 统一认证的endpoint

上述为资源服务器的配置，依赖spring-boot-starter-oauth2-resource-server。macula平台使用gateway作为资源服务器。

核心功能

服务端介绍

提供基于OAUTH/CAS/OIDC/SAML协议的统一认证服务，所有服务经过网站认证

认证方式

负责认证资源Owner方提供的认证凭据，为下层交互协议生成token或者ticket做准备

用户名密码认证

POST /login
username 用户名
password 密码
要带上openid/unionid可以绑定

短信认证(TODO)

POST /login/captcha
phone 手机号码
captcha 短信验证码
要带上openid/unionid可以绑定

微信授权手机号登录(TODO)

POST /login/weapp/phone
新版
code（后端通过code获取手机号），再根据手机号查询对应用户
旧版（加密数据，后端用session_key解密得到手机号）
encryptedData
iv
要带上openid/unionid可以绑定

已绑定小程序登录认证(TODO)

POST /login/weapp/code
code（后端调用code2session获取openid/unionid,如果没有绑定则调用不成功)

已绑定企微小程序登录认证(TODO)

POST /login/qyweapp/code
code（后端调用code2session获取userid，没有绑定登录不成功）

协议

协议层不负责用户身份认证，只按照协议生成对应的token或者ticket返回给客户端

系统管理

Mon, 01 Jan 0001 00:00:00 +0000

概览

macula-cloud-system主要提供系统管理、权限、角色等功能，并提供连接macula-cloud-system应用的能力，生成获取菜单、获取当前用户的Controller。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-system</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

macula:
 cloud:
 endpoint: http://127.0.0.1:9000					# 网关地址
 app-key: example
 secret-key: example

核心功能

对接macula-cloud-system

根据app-key对应的应用获取菜单和用户信息。SystemService是通过远程RPC访问macula-cloud-system。具体的controller如下：

@Tag(name = "system模块对接接口")
@RestController
@RequiredArgsConstructor
public class SystemController {

 private final SystemService systemService;

 @Operation(summary = "获取登录用户信息")
 @GetMapping("/api/v1/users/me")
 public UserLoginVO getLoginUserInfo() {
 // 从macula-cloud获取用户信息
 UserLoginVO userLoginVO = systemService.getUseInfo();
 userLoginVO.setRoles(SecurityUtils.getRoles());
 return userLoginVO;
 }

 @Operation(summary = "路由列表")
 @GetMapping("/api/v1/menus/routes")
 public List<RouteVO> listRoutes() {
 return systemService.listRoutes();
 }
}

提供按钮权限注解鉴权

@PreAuthorize("@pms.hasPermission('sys:user:del')")

服务端介绍

依赖引入

<dependencies>
 <dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-commons</artifactId>
 </dependency>
 <dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-security</artifactId>
 </dependency>
 <dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-springdoc</artifactId>
 </dependency>
 <dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-feign</artifactId>
 </dependency>
</dependencies>

版权说明

system模块代码参考了youlai-mall，https://github.com/youlaitech/youlai-mall/blob/master/LICENSE

ID生成

Mon, 01 Jan 0001 00:00:00 +0000

概览

macula-cloud-tinyid是用Java开发的一款分布式id生成系统，基于数据库号段算法实现，关于这个算法可以参考美团leaf或者tinyid原理介绍。Tinyid扩展了leaf-segment算法，支持了多db(master)，tinyid是服务端，同时我们提供了starter(Java SDK)，获得了更好的性能与可用性。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-tinyid</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

macula:
 cloud:
 tinyid:
 server: localhost:9000 # 可以通过逗号隔开多个服务端IP
 token: 0f673adf80504e2eaa552f5d791b644c
 connectTimeout: 5000
 readTimeout: 5000

核心功能

性能与可用性

性能

http方式访问，性能取决于http server的能力，网络传输速度
java-client方式，id为本地生成，号段长度(step)越长，qps越大，如果将号段设置足够大，则qps可达1000w+

可用性

依赖db，当db不可用时，因为server有缓存，所以还可以使用一段时间，如果配置了多个db，则只要有1个db存活，则服务可用
使用tiny-client，只要server有一台存活，则理论上可用，server全挂，因为client有缓存，也可以继续使用一段时间

服务端介绍

Tinyid的特性

全局唯一的long型id
趋势递增的id，即不保证下一个id一定比上一个大
非连续性
提供http和java client方式接入
支持批量获取id
支持生成1,3,5,7,9…序列的id
支持多个db的配置，无单点

提示

适用场景:只关心id是数字，趋势递增的系统，可以容忍id不连续，有浪费的场景不适用场景:类似订单id的业务(因为生成的id大部分是连续的，容易被扫库、或者测算出订单量)

Tinyid的原理

tinyid是基于数据库发号算法实现的，简单来说是数据库中保存了可用的id号段，tinyid会将可用号段加载到内存中，之后生成id会直接内存中产生。
可用号段在第一次获取id时加载，如当前号段使用达到一定量时，会异步加载下一可用号段，保证内存中始终有可用号段。
(如可用号段11000被加载到内存，则获取id时，会从1开始递增获取，当使用到一定百分比时，如20%(默认)，即200时，会异步加载下一可用号段到内存，假设新加载的号段是10012000,则此时内存中可用号段为200~~1000,1001~~2000)，当id递增到1000时，当前号段使用完毕，下一号段会替换为当前号段。依次类推。

tinyid系统架构图

任务调度

Mon, 01 Jan 0001 00:00:00 +0000

概览

定时任务接入模块，支持下列定义的定时任务：

xxljob任务
PowerJob任务
Spring注解任务
TODO，统一的macula task定义

组件坐标


<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-task</artifactId>
</dependency>

使用配置

接入xxljob的配置如下：

xxl:
 job:
 enabled: true # 打开xxljob支持，默认是true 
 accessToken: default_token
 admin:
 # addresses: http://127.0.0.1:8080/xxl-job-admin # 调度中心部署跟地址 [选填]：如调度中心集群部署存在多个地址则用逗号分隔。 执行器将会使用该地址进行"执行器心跳注册"和"任务结果回调"；为空则关闭自动注册；
 name: macula-cloud-xxljob  # 注册到注册中心的Admin的服务名称[选填]，默认是xxl-job-admin，和addresses二选一
 executor:
 appname: ${spring.application.name}  # 执行器AppName [选填]：执行器心跳注册分组依据；为空则关闭自动注册
 # address: # 服务注册地址,优先使用该配置作为注册地址 为空时使用内嵌服务 ”IP:PORT“ 作为注册地址 从而更灵活的支持容器类型执行器动态IP和动态映射端口问题
 # ip: # 执行器IP [选填]：默认为空表示自动获取IP，多网卡时可手动设置指定IP ，该IP不会绑定Host仅作为通讯实用；地址信息用于 "执行器注册" 和 "调度中心请求并触发任务"
 # port: 9999 # 执行器端口号 [选填]：小于等于0则自动获取；默认端口为9099，单机部署多个执行器时，注意要配置不同执行器端口；
 logpath: ${user.home}/logs/${spring.application.name}  # 执行器运行日志文件存储磁盘路径 [选填] ：需要对该路径拥有读写权限；为空则使用默认路径；
 logretentiondays: 30 # 执行器日志保存天数 [选填] ：值大于3时生效，启用执行器Log文件定期清理功能，否则不生效；

接入PowerJob的配置如下：

powerjob:
 worker:
 enabled: true # 打开PowerJob支持，默认是false
 akka-port: 27777 # akka 工作端口，可选，默认 27777
 app-name: ${spring.application.name}  # 接入应用名称，用于分组隔离，推荐填写 本 Java 项目名称
 server-address: 127.0.0.1:7700 # 调度服务器地址，IP:Port 或 域名，多值逗号分隔
 protocol: http  # 通讯协议，4.3.0 开始支持 HTTP 和 AKKA 两种协议，官方推荐使用 HTTP 协议（注意 server 和 worker 都要开放相应端口）
 store-strategy: disk  # 持久化方式，可选，默认 disk
 max-result-length: 4096 # 任务返回结果信息的最大长度，超过这个长度的信息会被截断，默认值 8192
 max-appended-wf-context-length: 4096 # 单个任务追加的工作流上下文最大长度，超过这个长度的会被直接丢弃，默认值 8192
 max-lightweight-task-num: 1024 # 同时运行的轻量级任务数量上限
 max-heavy-task-num: 64 # 同时运行的重量级任务数量上限

核心功能

使用@XxlJob注解定义任务

/**
 * XxlJob开发示例（Bean模式）
 *
 * 开发步骤： 1、任务开发：在Spring Bean实例中，开发Job方法； 2、注解配置：为Job方法添加注解 "@XxlJob(value="自定义jobhandler名称", init = "JobHandler初始化方法",
 * destroy = "JobHandler销毁方法")"，注解value值对应的是调度中心新建任务的JobHandler属性的值。 3、执行日志：需要通过 "XxlJobHelper.log" 打印执行日志；
 * 4、任务结果：默认任务结果为 "成功" 状态，不需要主动设置；如有诉求，比如设置任务结果为失败，可以通过 "XxlJobHelper.handleFail/handleSuccess" 自主设置任务结果；
 *
 * @author xuxueli 2019-12-11 21:52:51
 */
@Component
public class XxlJobDemoHandler {
 /**
 * 1、简单任务示例（Bean模式）
 */
 @XxlJob("demoJobHandler")
 public void demoJobHandler() throws Exception {
 XxlJobHelper.log("XXL-JOB, Hello World.");

 for (int i = 0; i < 5; i++) {
 XxlJobHelper.log("beat at:" + i);
 TimeUnit.SECONDS.sleep(2);
 }
 // default success
 }

 /**
 * 3、命令行任务
 */
 @XxlJob("commandJobHandler")
 public void commandJobHandler() throws Exception {
 String command = XxlJobHelper.getJobParam();
 int exitValue = -1;

 BufferedReader bufferedReader = null;
 try {
 // command process
 ProcessBuilder processBuilder = new ProcessBuilder();
 processBuilder.command(command);
 processBuilder.redirectErrorStream(true);

 Process process = processBuilder.start();
 // Process process = Runtime.getRuntime().exec(command);

 BufferedInputStream bufferedInputStream = new BufferedInputStream(process.getInputStream());
 bufferedReader = new BufferedReader(new InputStreamReader(bufferedInputStream));

 // command log
 String line;
 while ((line = bufferedReader.readLine()) != null) {
 XxlJobHelper.log(line);
 }

 // command exit
 process.waitFor();
 exitValue = process.exitValue();
 } catch (Exception e) {
 XxlJobHelper.log(e);
 } finally {
 if (bufferedReader != null) {
 bufferedReader.close();
 }
 }

 if (exitValue == 0) {
 // default success
 } else {
 XxlJobHelper.handleFail("command exit value(" + exitValue + ") is failed");
 }
 }
}

使用PowerJob定义任务

public class PowerJobDemoProcessor implements BasicProcessor {
 @Override
 public ProcessResult process(TaskContext taskContext) throws Exception {
 // 在线日志功能，可以直接在控制台查看任务日志，非常便捷
 OmsLogger omsLogger = taskContext.getOmsLogger();
 omsLogger.info("BasicProcessorDemo start to process, current JobParams is {}.", taskContext.getJobParams());

 // TaskContext为任务的上下文信息，包含了在控制台录入的任务元数据，常用字段为
 // jobParams（任务参数，在控制台录入），instanceParams（任务实例参数，通过 OpenAPI 触发的任务实例才可能存在该参数）

 // 进行实际处理...
 // mysteryService.hasaki();

 // 返回结果，该结果会被持久化到数据库，在前端页面直接查看，极为方便
 return new ProcessResult(true, "result is xxx");
 }
}

服务端介绍

xxl-job

请参考xxljob官网。由于服务端需要回调客户端，建议各平台拷贝macula-cloud-xxjob部署到自己的集群中。

Macula Boot Starter Seata

Mon, 01 Jan 0001 00:00:00 +0000

概览

macula-cloud-seata是基于seata-server的服务端实现，以nacos作为注册和配置中心。同时提供starter，默认支持RestTemplate、FeignClient的分布式事务支持。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-seata</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

客户端加入如下配置

seata:
 enabled: true
 application-id: ${spring.application.name}
 tx-service-group: ${spring.application.name}-tx-group
 enable-auto-data-source-proxy: true			# 开启自动数据源代理，如果不使用AT模式，不要开启，默认为true
 saga:
 	enabled: true													# 开启saga自动配置，默认是false
 config:
 type: nacos
 nacos:
 serverAddr: 127.0.0.1:8848
 dataId: "seata.properties"					# 默认是seata.properties
 username: 'nacos'
 password: 'nacos'
 registry:
 type: nacos
 nacos:
 application: seata-server						# seata服务器的ID
 server-addr: 127.0.0.1:8848
 username: 'nacos'
 password: 'nacos'

在nacos的seata.properties中增加需要的如下事务群组配置

服务治理(Sentinel)

Mon, 01 Jan 0001 00:00:00 +0000

概览

macula-cloud-sentinel基于官方的sentinel-dashboard并引入nacos作为数据源的服务治理管理平台。在macula-boot-starter-cloud-alibaba中已经引入了sentinel依赖包。只需通过配置打开即可。

基于macula-boot-starter-cloud-alibaba微服务应用才可以使用该服务。

基于macula-boot-starter-cloud-tencent的微服务应用可以使用polarismesh服务治理平台。

基于macula-boot-starter-cloud-tsf的微服务应用可以直接使用腾讯云的TSF平台。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-cloud-alibaba</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

macula平台默认基于nacos数据源承接Sentinel的动态配置

spring:
	cloud:
		sentinel:
 #启动后马上初始化，而不是等有流量有再初始化。否则会提示：Runtime port not initialized, won't send heartbeat
 eager: true
 transport:
 # 控制台地址
 dashboard: localhost:8080
 # 客户端监控API的端口，默认8719，与Sentinel控制台做交互。有规则变化会把规则数据push给这个Http Server接收,然后注册到sentinel中
 port: 8719
 # Sentinel Nacos数据源配置，Nacos中的规则会⾃动同步到sentinel控制台的流控规则中
 # com.alibaba.cloud.sentinel.SentinelProperties.datasource
 # 配置了数据源后，在nacos修改中会自动同步到sentinel
 # ⾃定义数据源名,随意不重复即可；可多个
 # The following values are valid:
 # AUTHORITY,DEGRADE,FLOW,GW_API_GROUP,GW_FLOW,PARAM_FLOW,SYSTEM
 datasource:
 flow:
 # 指定数据源类型，要与服务端使用的nacos保持一致
 nacos:
 server-addr: 127.0.0.1:8848
 data-id: ${spring.application.name}-flow-rules
 namespace: SENTINEL
 # 默认分组：DEFAULT_GROUP
 # group-id: SENTINEL_GROUP
 data-type: json
 # 限流规则类型
 rule-type: flow
 degrade:
 nacos:
 server-addr: 127.0.0.1:8848
 data-id: ${spring.application.name}-degrade-rules
 namespace: SENTINEL
 # 默认分组：DEFAULT_GROUP
 # group-id: SENTINEL_GROUP
 data-type: json
 # 降级规则类型
 rule-type: degrade

更多配置项见：官网

通用平台 on Macula

统一认证

概览

组件坐标

使用配置

核心功能

服务端介绍

认证方式

用户名密码认证

短信认证(TODO)

微信授权手机号登录(TODO)

已绑定小程序登录认证(TODO)

已绑定企微小程序登录认证(TODO)

协议

系统管理

概览

组件坐标

使用配置

核心功能

对接macula-cloud-system

提供按钮权限注解鉴权

服务端介绍

依赖引入

版权说明

ID生成

概览

组件坐标

使用配置

核心功能

性能与可用性

性能

可用性

服务端介绍

Tinyid的特性

推荐使用方式

Tinyid的原理

tinyid系统架构图

任务调度

概览

组件坐标

使用配置

接入xxljob的配置如下：

接入PowerJob的配置如下：

核心功能

使用@XxlJob注解定义任务

使用PowerJob定义任务

服务端介绍

xxl-job

Macula Boot Starter Seata

概览

组件坐标

使用配置

服务治理(Sentinel)

概览

组件坐标

使用配置