通用平台 on Macula

统一认证

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

概览

本章沿用 5.x 的文档内容，尚未按 latest（当前）分支核对。涉及依赖、配置或 API 时，请以 main 分支源码为准。

基于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 的客户端集成，提供菜单、当前用户查询及按钮权限校验，不包含系统管理服务端。

组件坐标

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

使用配置

属性	默认值	说明
`macula.cloud.endpoint`	无，必填	网关基础 URL，客户端自动追加 `/system`
`macula.cloud.app-key`	无，必填	在平台登记的应用标识
`macula.cloud.secret-key`	无，必填	HMAC 签名密钥，部署时注入

请求超时通过 spring.cloud.openfeign.client.config.systemFeignClient.* 配置，参见 Feign。

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')")

服务端介绍

macula-cloud-system 需独立部署，并通过网关暴露 /system 路由；应用标识、密钥及用户权限由服务端维护。

ID生成

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

概览

通过 Feign 经 Macula Cloud 网关申请号段，在本地缓存、预加载并生成 ID，支持单个和批量取号。

组件坐标

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

使用配置

与 system starter 共用网关配置：

macula:
 cloud:
 endpoint: ${MACULA_CLOUD_ENDPOINT} # 网关基础地址，含 http(s)://
 app-key: ${MACULA_CLOUD_APP_KEY}
 secret-key: ${MACULA_CLOUD_SECRET_KEY}

服务端需预先配置 bizType，应用需具有号段接口访问权限。无需 TinyID 专用 token 或超时配置。

升级说明

移除旧 macula.cloud.tinyid.server/token/connect-timeout/read-timeout，改用统一网关配置。
网关将 /tinyid/api/v1/id/nextSegmentIdSimple 经 StripPrefix=1 转发；Server 不设 /tinyid 上下文，该接口使用 JWT 认证。
新号段接口使用网关应用权限，不再校验旧 Token 与 bizType 的绑定。客户端、Server 和路由需协调升级。

核心功能

单个与批量取号

注入 IdGeneratorFactory 后按业务类型取号：

IdGenerator generator = idGeneratorFactory.getIdGenerator("order");
Long id = generator.nextId();
List<Long> ids = generator.nextId(10);

ID 趋势递增、不保证连续；网关或服务端短暂不可用时，仍可使用尚未耗尽的本地号段。提供自定义 SegmentIdService 时，远程客户端自动退让，无需配置网关凭据；IdGeneratorFactory 也可自定义。

任务调度

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

概览

该模块只连接 SnailJob Server，同时演示原生 SnailJob Handler 与保持源码不变的 @XxlJob Handler。macula-boot-starter-task 会自动启用 SnailJob，启动类不需要 @EnableSnailJob，模块也不直接依赖 SnailJob 或官方 XXL-JOB 客户端。

macula-boot-starter-task 以 SnailJob Server 作为唯一调度服务端，同时支持两种客户端写法：SnailJob 原生 @JobExecutor / @Retryable，以及历史 XXL-JOB Bean Handler 的 @XxlJob。旧 Handler 由兼容桥注册为 SnailJob executor，不需要 XXL-JOB Admin，也不会启动 XXL executor、回调或日志拉取通信。

当前固定使用 SnailJob 1.9.0，保持 Java 17 兼容。SnailJob 2.x 要求更高 JDK，本 Starter 不升级到 2.x。

组件坐标

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

Starter 会传递提供 SnailJob starter、Job Core、Retry Core，以及旧 Handler 编译所需的最小 XXL 兼容 API。应用不要再引入 com.xuxueli:xxl-job-core；检测到官方客户端的 XxlJobExecutor 时，应用会启动失败并提示移除冲突依赖。

使用配置

前置条件

JDK 17。
Nacos，默认 127.0.0.1:38848。
SnailJob 1.9 Server，默认通信地址 127.0.0.1:17888。

不需要部署 XXL-JOB Admin。

Macula Boot Starter Seata

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

概览

本模块是 Seata 客户端 Starter，补充 RestTemplate、Feign 和 Web 请求的事务上下文传播，不包含 Seata Server。下文服务端章节说明独立部署配套。

组件坐标

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

使用配置

本模块不增加独立的配置前缀，客户端沿用 seata.*；示例使用 Nacos，须先部署对应服务。

属性	配置说明
`seata.enabled`	Seata 客户端开关
`seata.application-id`	应用标识，通常使用 `spring.application.name`
`seata.tx-service-group`	事务组，须与服务端 `service.vgroupMapping.*` 映射一致
`seata.enable-auto-data-source-proxy`	是否自动代理数据源，按所用事务模式选择
`seata.saga.enabled`	仅使用 Saga 状态机时开启
`seata.config.type` / `seata.registry.type`	配置中心 / 注册中心类型
`seata.config.nacos.` / `seata.registry.nacos.`	对应 Nacos 地址、命名空间和认证信息

AT 模式还需在业务库准备与 Seata 版本对应的 undo_log 表；引入 Starter 不代表服务端或业务表已就绪。

客户端加入如下配置

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

概览

Sentinel 能力由 macula-boot-starter-cloud-alibaba 及 Alibaba SCG 组合提供。业务服务、网关和 Nacos 配置导入方式见 Alibaba 接入。

组件坐标

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

使用配置

当前分支的主要配置项为：

配置	用途
`spring.cloud.sentinel.transport.dashboard`	Sentinel 控制台地址
`spring.cloud.sentinel.transport.port`	Sentinel 客户端通信端口
`spring.cloud.sentinel.datasource.<名称>.nacos.*`	动态规则的 Nacos 地址、Data ID、namespace、data-type 和 rule-type

配置值应由应用环境提供；完整示例见 Alibaba README。

核心功能

云接入方式

main 的云接入模块包括 Alibaba/Nacos、Tencent/Polaris 和共享 Gateway。Tencent 应用的接入方式见 Tencent。

平台部署见部署 Macula 平台，历史 TSF 说明保存在 5.x 文档。

依赖引入

以下为对应分支 POM 的直接依赖（不含测试依赖）；版本由父 POM / BOM 管理。

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

<dependency>
 <groupId>org.springframework.cloud</groupId>
 <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-web-server</artifactId>
</dependency>

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-cloud-alibaba-gray</artifactId>
</dependency>

<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>

<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>

<dependency>
 <groupId>com.alibaba.cloud</groupId>
 <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
</dependency>

<dependency>
 <groupId>com.alibaba.csp</groupId>
 <artifactId>sentinel-datasource-nacos</artifactId>
</dependency>

<dependency>
 <groupId>org.apache.commons</groupId>
 <artifactId>commons-pool2</artifactId>
</dependency>

版权说明

Macula Boot 使用 Apache License 2.0。第三方组件遵循各自许可证。