框架基础 on Macula

Macula Boot Commons

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

概览

提供公共返回结构、结果码、异常、常量及上下文工具，无独立 YAML 配置项。Jackson API 使用 tools.jackson.*，共享注解仍为 com.fasterxml.jackson.annotation.*；空值注解使用 JSpecify。

组件坐标

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

使用配置

Commons 提供公共数据结构与工具契约，无独立 YAML 配置项；按下文接口在业务代码中使用。

核心功能

统一的返回结构

Result<T> 包含 success、code、msg、cause 和 data。业务数据使用 data，失败原因使用 cause，不要混用。

Result<String> ok = Result.success("完成");
Result<Void> failed = Result.failed(ApiResultCode.BIZ_ERROR, "业务失败原因");
Result<Void> status = Result.judge(true);

业务可实现 ResultCode 定义自己的错误码。Web Starter 负责 Controller 响应包装，Commons 本身不注册 Web 处理器。

全局常量

类型	用途
`GlobalConstants`	请求 ID、租户、Token 和灰度标签；默认租户 ID 为 `1`
`SecurityConstants`	安全相关头、权限标识和默认白名单
`CacheConstants`	框架缓存键约定

跨线程传递 TenantContextHolder、GrayVersionContextHolder 时配合 Async Starter；业务手动设置上下文后应及时清理。

Macula Boot Starter Web

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

概览

该模块为 Web 开发所需的基本依赖包，是对 spring-boot-starter-web 的扩展。Macula Boot 6.1 随 Spring Boot 4 使用其默认的 Tomcat Web 服务器；Spring Boot 4 不再提供 Undertow Starter。有兴趣可以阅读优雅的写Controller。

组件坐标


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

使用配置

macula:
 web:
 exception-advice: true # 统一异常处理器，默认true
 response-advice: true # 统一响应处理器，默认true

属性	默认值	说明
`macula.web.exception-advice`	`true`	启用统一异常处理
`macula.web.response-advice`	`true`	启用统一响应包装
`macula.jackson.long-to-string`	`true`	将 Long、BigInteger、BigDecimal 序列化为字符串
`macula.jackson.null-to-empty`	`false`	按字段类型将 null 输出为空值
`macula.jackson.local-date-time-format`	未设置	自定义 LocalDateTime 格式
`macula.jackson.local-date-format`	未设置	自定义 LocalDate 格式
`macula.jackson.local-time-format`	未设置	自定义 LocalTime 格式

通用 Jackson 开关使用 spring.jackson.*。

Macula Boot Starter MapStruct

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

概览

开发JAVA应用程序时会进行逻辑分层，各层之间为了解耦，通常会定义不同的对象进行数据传递（如XXXVO、XXXDTO、XXXPO、XXXBO）。当在不同层之间进行数据传递时，需要将这些对象进行相互转换。通常有两种处理方式：一是直接使用Setter和Getter方法转换，二是使用一些工具类进行转换（如BeanUtil.copyProperties）。第一种方式如果对象属性比较多时，要写很多的Getter/Setter代码，很繁琐；第二种方式虽然比第一种方式要简单很多，但是因为使用了反射，性能不佳。故在此推荐，统一使用MapStruct（MapStructPlus），代码简洁且不存在性能问题。

组件坐标


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

使用配置

该组件在编译期生成转换代码，无独立运行时 YAML 配置。继承 Macula Boot 父 POM 的注解处理配置，并在 IDE 启用注解处理；具体写法见“核心功能”。

核心功能

基于MapStruct

MapStruct是一个类型转换工具，通过定义类型转换接口（如下所示），然后在编译的时候自动生成实现类来工作。

@Mapper(componentModel = MappingConstants.ComponentModel.DEFAULT)
public interface SourceTargetMapper {

 SourceTargetMapper MAPPER = Mappers.getMapper( SourceTargetMapper.class );

 @Mapping( source = "username", target = "user" )
 TargetDto toTarget( SourceDto s );
}

继承 macula-boot-parent 时已配置 Lombok、mapstruct-plus-processor、lombok-mapstruct-binding 和 -Amapstruct.defaultComponentModel=spring，不必重复复制编译插件配置。默认生成 Spring Bean，优先注入 Mapper；上面的 Mappers.getMapper 示例适用于显式使用默认组件模型且无 Spring 依赖的 Mapper。

仅导入 BOM 不会继承构建插件，需在应用父 POM 中配置对应 annotation processor。此模块无运行时 YAML 属性；转换实现于编译期生成，IDE 也需启用注解处理。

Macula Boot Starter JPA

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

概览

该模块主要使用alibaba druid作为数据源工具，Spring Data JPA和Fenix作为数据库操作框架。 Fenix（菲尼克斯）是一个为了解决复杂动态 SQL (JPQL) 而生的 Spring Data JPA 扩展库，能辅助开发者更方便快捷的书写复杂、动态且易于维护的 SQL，支持 ActiveRecord 模式和多种查询方式。

组件坐标

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

使用配置

本模块没有自有配置前缀，使用 spring.datasource.*、spring.jpa.* 和 fenix.*。

属性	默认值 / 行为	说明
`spring.data.jpa.repositories.enabled`	`true`	控制本模块 Repository 自动配置
`spring.data.jpa.repositories.bootstrap-mode`	`default`	可选 `deferred` / `lazy`；异步初始化可使用应用提供的 AsyncTaskExecutor
`spring.jpa.hibernate.ddl-auto`	按环境决定	示例 `update` 仅供开发；生产使用 `none` 或按迁移方案选择 `validate`
`spring.jpa.show-sql`	`false`	输出 SQL，生产慎用
`fenix.debug`	`false`	实时读取 SQL XML，仅限开发环境

配置上没有太特殊的，主要是数据源配置以及fenix配置。

spring:
 datasource:
 driver-class-name: com.mysql.cj.jdbc.Driver
 url: jdbc:mysql://localhost:3306/xxx?serverTimezone=Asia/Shanghai&characterEncoding=utf-8
 username: xxx
 password: xxx
 jpa:
 show-sql: true # 默认false，在日志里显示执行的sql语句
 hibernate:
 # 指定为update，每次启动项目检测表结构有变化的时候会新增字段，表不存在时会 新建，如果指定create，
 # 则每次启动项目都会清空数据并删除表，再新建。生产要指定为none
 ddl-auto: update

# Fenix 的几个配置项、默认值及详细说明，通常情况下你不需要填写这些配置信息（下面的配置代码也都可以删掉）.
fenix:
 # v2.4.1 版本新增，表示是否开启 debug 调试模式，默认 false。
 # 当开启之后，对 XML 中的 SQL 会进行实时文件流的读取和解析，不需要重启服务。切记仅在开发环境中开启此功能.
 debug: true
 # 成功加载 Fenix 配置信息后，是否打印启动 banner，默认 true.
 print-banner: true
 # 是否打印 Fenix 生成的 SQL 信息，默认为空.
 # 当该值为空时，会读取 'spring.jpa.show-sql' 的值，为 true 就打印 SQL 信息，否则不打印.
 # 当该值为 true 时，就打印 SQL 信息，否则不打印. 生产环境不建议设置为 true.
 print-sql: true
 # 扫描 Fenix XML 文件的所在位置，默认是 fenix 目录及子目录，可以用 yaml 文件方式配置多个值.
 xml-locations: fenix
 # 扫描你自定义的 XML 标签处理器的位置，默认为空，可以是包路径，也可以是 Java 或 class 文件的全路径名
 # 可以配置多个值，不过一般情况下，你不自定义自己的 XML 标签和处理器的话，不需要配置这个值.
 handler-locations:
 # v2.2.0 新增的配置项，表示自定义的继承自 AbstractPredicateHandler 的子类的全路径名
 # 可以配置多个值，通常情况下，你也不需要配置这个值.
 predicate-handlers:
 # v2.7.0 新增的配置项，表示带前缀下划线转换时要移除的自定义前缀，多个值用英文逗号隔开，通常你不用配置这个值.
 underscore-transformer-prefix:

核心功能

阿里druid数据源配置

数据源的配置请参考druid-spring-boot-starter 官方文档

Macula Boot Starter MyBatis Plus

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

概览

该模块主要使用alibaba druid作为数据源工具，mybatis-plus作为数据库操作框架

组件坐标


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

使用配置

默认自动加载MyBatisPlusAutoConfiguration，已经开启了EnableTransactionManagement事务注解可配置属性：

macula:
 mybatis-plus:
 tenant-id: 1 # 默认租户 ID，YAML 使用整数，不加 L
 tenant-suffixes: [tenant, TENANT]  # 需要租户隔离的表名后缀
 audit:
 create-by-name: createBy  # 创建人，默认createBy
 create-time-name: createTime  # 创建时间，默认createTime
 last-update-by-name: lastUpdateBy  # 最后更新人，默认lastUpdateBy
 last-update-time-name: lastUpdateTime  # 最后更新时间，默认lastUpdateTime

配置前缀为 macula.mybatis-plus；数据库连接使用 spring.datasource.*，MyBatis-Plus 原生选项使用 mybatis-plus.*。

属性	默认值	说明
`tenant-enable`	`true`	开启租户拦截器
`tenant-id`	`1`	默认租户 ID
`tenant-suffixes`	`[tenant, TENANT]`	参与租户过滤的表名后缀
`data-permission-enable`	`true`	开启数据权限拦截器
`max-limit`	`1000`	分页单页记录数上限
`audit.create-by-name` / `audit.create-time-name`	`createBy` / `createTime`	创建人 / 创建时间的 Java 属性名
`audit.last-update-by-name` / `audit.last-update-time-name`	`lastUpdateBy` / `lastUpdateTime`	更新人 / 更新时间的 Java 属性名

核心功能

阿里druid数据源配置

数据源的配置请参考druid-spring-boot-starter 官方文档

Macula Boot Starter Redis

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

概览

该模块提供连接Redis的相关配置，使用了redisson库

组件坐标

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

使用配置

使用时有两种方式配置，一种是spring-boot默认的配置形式，另一种是redisson的配置形式。如下所示：

属性	默认值 / 行为	说明
`spring.data.redis.host` / `port`	`localhost` / `6379`	单机地址
`spring.data.redis.database`	`0`	数据库编号，Cluster 不支持切库
`spring.data.redis.username` / `password`	未设置	Redis 认证信息
`spring.data.redis.timeout`	未设置时本模块使用 `10000ms`	自动构造 Redisson 时用作建连超时
`spring.data.redis.ssl.enabled`	`false`	自动构造连接地址时启用 TLS
`spring.data.redis.sentinel.master` / `nodes`	未设置	Sentinel 主节点名称 / 哨兵地址列表
`spring.data.redis.cluster.nodes`	未设置	Cluster 节点地址列表
`spring.redis.redisson.config`	未设置	内嵌 Redisson YAML，优先于 `file`
`spring.redis.redisson.file`	未设置	Redisson YAML 资源路径

两种命名空间有意不同；显式 Redisson YAML 与 spring.data.redis.* 不会逐项合并。

Macula Boot Starter Cache

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

概览

本模块提供基于 Spring Cache 的两级缓存能力：一级缓存使用 Caffeine，二级缓存使用 Redis。读取时优先访问本地缓存，Redis 命中后回填本地缓存；写入、删除和清空时通过 Redis Pub/Sub 通知其他应用实例清理本地缓存。

Macula Boot 6.1 起，本模块不再依赖 Resilience4j。Redis 连接、资源或命令超时时采用 fail-open 策略，优先保证业务调用和当前实例的本地缓存可用。

组件坐标

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

使用配置

配置两级缓存

spring:
 data:
 redis:
 host: localhost
 port: 6379
 connect-timeout: 2s  # Redis 建连超时，生产环境应按网络条件设置
 timeout: 3s  # Redis 命令超时，决定故障时单次请求的最长等待时间
 cache:
 type: redis  # 必须选择 Redis，才会启用两级缓存自动配置
 cache-names:
 - user-service
 - tag-service
 two-level:
 default-time-to-live: 24h
 time-to-live:
 user-service: 24h
 tag-service: 12h
 use-key-prefix: true
 key-prefix: "macula:cache:"
 topic: "macula:cache:two-level:topic"
 local:
 max-size: 2000
 expiry-jitter: 50

expiry-jitter 表示本地缓存过期时间的随机偏移百分比，用于避免大量缓存同时失效，取值必须大于等于 0 且小于 100。

Macula Boot Starter RocketMQ

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

概览

该模块主要依赖阿里开源的RocketMQ。RocketMQ 支持同步、异步发送消息，半事务消息等，具体可以参考官方文档。

组件坐标


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

使用配置

生产者配置建议

rocketmq:
 name-server: localhost:9876
 producer:
 namespace: ${spring.profiles.active} # 建议与环境保持一致${spring.profiles.active}
 group: ${spring.application.name}  # 建议采用${spring.application.name}
 sendMessageTimeout: 300000
 enableMsgTrace: true # 消息轨迹开启，根据需要来决定

demo:
 rocketmq:
 stringRequestTopic: stringRequestTopic:tagA

public class Test {
 @Resource
 private RocketMQTemplate rocketMQTemplate;
 @Value("${demo.rocketmq.stringRequestTopic}")
 private String stringRequestTopic; // 按照最佳实践，topic一个应用保持一个topic，topic:tag，通过tag区分业务

 SendResult sendResult = rocketMQTemplate.syncSend(stringRequestTopic, "hello world");
}

消费者配置建议

Push模式

Push的namespace、topic等都是配置在@RocketMQMessageListener注解里面的

Macula Boot Starter Kafka

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

概览

该模块依赖spring-kafka接入kafka服务。

组件坐标

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

使用配置

本模块沿用 spring.kafka.*，无自有配置前缀。下列为示例值，不是所有属性的默认值；生产环境需按吞吐、重试及重复消费要求选择。

spring:
 kafka:
 bootstrap-servers: 127.0.0.1:9092
 producer:
 batch-size: 16384
 buffer-memory: 33554432
 consumer:
 group-id: example-consumer
 auto-offset-reset: earliest
 max-poll-records: 500
 enable-auto-commit: false

属性（前缀 `spring.kafka`）	说明
`bootstrap-servers`	Broker 地址列表，多个地址以逗号分隔
`producer.batch-size` / `buffer-memory`	批次大小 / 缓冲区容量，单位字节，不是消息条数
`producer.retries` / `acks`	发送重试次数 / 确认策略
`producer.key-serializer` / `value-serializer`	与消息类型匹配的序列化器
`consumer.group-id`	消费者组标识
`consumer.auto-offset-reset`	无有效已提交位点时的起点策略；`earliest` 不代表每次从头消费
`consumer.max-poll-records`	每次 poll 最多返回的记录数
`consumer.enable-auto-commit` / `auto-commit-interval`	是否自动提交 / 自动提交间隔；关闭自动提交后由监听容器策略管理
`consumer.key-deserializer` / `value-deserializer`	与生产端匹配的反序列化器
`listener.type` / `concurrency` / `ack-mode`	单条或批量监听 / 并发数 / 提交模式

下面的字符串收发示例需配置 StringSerializer / StringDeserializer，或使用 Boot 对应默认配置。

Macula Boot Starter Crypto

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

概览

该模块提供数据加解密的能力。

组件坐标


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

使用配置

macula:
 crypto:
 enable: true # 显式启用；未配置时不创建 CryptoManager
 algorithm: AES  # BASE64, AES, RSA, SM2, SM4
 encode: HEX  # BASE64, HEX
 password: xxx  # 对称加密的密钥
 publicKey: xxx  # 非对称加密公钥
 privateKey: xxx # 非对称解密私钥

配置前缀为 macula.crypto，密钥应由部署环境注入，不要提交到仓库。

属性	默认值	说明
`enable`	未设置	必须为 `true` 才启用字段加解密自动配置
`algorithm`	未设置	默认算法：`BASE64`、`AES`、`RSA`、`SM2`、`SM4`
`encode`	未设置	密文编码：`BASE64` 或 `HEX`
`password`	未设置	对称加密密钥
`public-key` / `private-key`	未设置	非对称加密公钥 / 私钥
`key`	未设置	`mpw:` 配置解密密钥，与字段加密的 `password` 不同

核心功能

配置文件加密

配置文件加密只支持AES（AES/ECB/PKCS5Padding）方式加密，密钥只能通过命令行的方式设置

Security：方法授权与资源归属

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

概览

Security Starter 运行在 BFF 和业务微服务中：验证网关 JWT、建立 Spring Security 认证上下文，并在业务方法上执行细粒度授权。网关的认证与 URL 控制见 Gateway，整体分层见安全架构。

组件坐标

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

使用配置

JWT 验签配置

Samples 中，BFF、Service1、Basic、OpenAPI、Thirdparty 均指向本应用 Gateway 的公钥集：

spring:
 security:
 oauth2:
 resourceserver:
 jwt:
 jwk-set-uri: http://127.0.0.1:6000/oauth2/jwks
macula:
 security:
 ignore-urls: []

容器环境将 JWK 地址改为 http://macula-samples-gateway:6000/oauth2/jwks；其他应用按自己的网关地址配置。

配置	含义
`spring.security.oauth2.resourceserver.jwt.jwk-set-uri`	网关 JWK 公钥集，用于验证内部 JWT
`jwt.public-key-location`	同一 Spring Security JWT 前缀下的本地 RSA 公钥替代方式
`jwt.issuer-uri`	同一前缀下按 issuer 发现验签配置，目标必须与实际签发方式相符
`jwt.jws-algorithms`	JWK / 公钥方式允许的签名算法，Boot 默认 RS256
`macula.security.ignore-urls`	合并内置白名单和 Inner 路径的放行配置

明确选择与网关对应的验签方式，不混用不同密钥模式。模块保留无 JWK / issuer / 公钥且无自定义 JwtDecoder 时的对称 secret 兼容模式；接入网关时显式配置 JWK，不依赖公开默认值。

Macula Boot Starter SpringDoc

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

概览

该模块是基于 SpringDoc 3.x 的 OpenAPI V3 规范 API 接口文档生成工具，兼容 Spring Boot 4。

组件坐标


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

使用配置

无自有配置前缀；生产环境按需关闭文档入口或限制访问。

属性	默认值	说明
`springdoc.api-docs.enabled`	`true`	生成 OpenAPI 文档
`springdoc.api-docs.path`	`/v3/api-docs`	JSON 文档路径
`springdoc.swagger-ui.enabled`	`true`	启用 Swagger UI
`springdoc.swagger-ui.path`	`/swagger-ui.html`	UI 入口路径
`springdoc.packages-to-scan`	未设置	限定扫描包
`springdoc.paths-to-match`	未设置	限定文档接口路径

springdoc:
 api-docs:
 enabled: true # 默认是true，用于开关API文档
 swagger-ui:
 enabled: false # 默认是true，用于开关API UI

核心功能

示例

/**
 * 部门控制器
 *
 * @author haoxr
 * @since 2020/11/6
 */
@Tag(name = "部门接口", description = "部门接口")
@RestController
@RequestMapping("/api/v1/dept")
@RequiredArgsConstructor
public class SysDeptController {

 private final SysDeptService deptService;

 @Operation(summary = "获取部门列表")
 @GetMapping
 public List<DeptVO> listDepartments(DeptQuery queryParams) {
 List<DeptVO> list = deptService.listDepartments(queryParams);
 return list;
 }

 @Operation(summary = "获取部门下拉选项")
 @GetMapping("/options")
 public List<Option> listDeptOptions() {
 List<Option> list = deptService.listDeptOptions();
 return list;
 }

 @Operation(summary = "获取部门详情")
 @Parameter(name = "部门ID")
 @GetMapping("/{deptId}/form")
 public DeptForm getDeptForm(@PathVariable Long deptId) {
 DeptForm deptForm = deptService.getDeptForm(deptId);
 return deptForm;
 }

 @Operation(summary = "新增部门")
 @AuditLog(title = "新增部门")
 @PostMapping
 public Long saveDept(@Valid @RequestBody DeptForm formData) {
 Long id = deptService.saveDept(formData);
 return id;
 }

 @Operation(summary = "修改部门")
 @AuditLog(title = "修改部门")
 @PutMapping(value = "/{deptId}")
 public Long updateDept(@PathVariable Long deptId, @Valid @RequestBody DeptForm formData) {
 deptId = deptService.updateDept(deptId, formData);
 return deptId;
 }

 @Operation(summary = "删除部门")
 @AuditLog(title = "删除部门")
 @Parameter(name = "部门ID，多个以英文逗号(,)分割")
 @DeleteMapping("/{ids}")
 public boolean deleteDepartments(@PathVariable("ids") String ids) {
 boolean result = deptService.deleteByIds(ids);
 return result;
 }
}


@Schema(description = "部门表单对象")
@Data
public class DeptForm {

 @Schema(description = "部门名称")
 private String name;

 @Schema(description = "父部门ID")
 @NotNull(message = "父部门ID不能为空")
 private Long parentId;

 @Schema(description = "状态")
 private Integer status;

 @Schema(description = "排序")
 private Integer sort;
}

官方文档

Swagger UI： http://xxx/context-path/swagger-ui/index.html
API Docs： http://xxx/context-path/v3/api-docs

Macula Boot Starter Async

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

概览

本模块提供 Spring 异步任务与定时任务的基础配置，并基于 Micrometer Context Propagation 在 Spring 托管线程池之间传播调用上下文。

主要功能包括：

启用 Spring @Async 和 @Scheduled 能力
为 Spring 托管 Executor 提供 ContextPropagatingTaskDecorator
传播 Observation、Trace、MDC、Tenant 和 GrayVersion 上下文
在任务执行结束后恢复工作线程原状态，避免线程复用造成上下文污染
支持与用户自定义的有序 TaskDecorator 组合使用

Macula Boot 6.1 已移除 Alibaba TTL、TtlRunnable、TtlCallable 和 TtlWrappers，统一使用 Micrometer Context Propagation。

组件坐标

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

使用配置

本模块没有独立的 macula.async.* 配置。Spring Boot 自动创建的线程池使用以下属性；自行声明 Executor 时需自行应用配置与 TaskDecorator。

属性	说明
`spring.task.execution.pool.core-size` / `max-size`	异步线程池核心 / 最大线程数
`spring.task.execution.pool.queue-capacity`	异步队列容量，影响扩容与拒绝行为
`spring.task.execution.thread-name-prefix`	异步线程名前缀
`spring.task.scheduling.pool.size`	定时任务线程池大小
`spring.task.scheduling.thread-name-prefix`	定时任务线程名前缀
`spring.reactor.context-propagation`	Reactor 传播模式，WebFlux/Gateway 按下文设为 `auto`

核心功能

`@Async` 上下文传播

引入组件后，Spring Boot 管理的异步执行器会使用 maculaContextPropagatingTaskDecorator。调用 @Async 方法时，提交线程中的 Observation、Trace、 MDC、Tenant 和 GrayVersion 会传播到异步线程，并在任务完成后自动清理。

框架基础 on Macula

Macula Boot Commons

概览

组件坐标

使用配置

核心功能

统一的返回结构

全局常量

Macula Boot Starter Web

概览

组件坐标

使用配置

Macula Boot Starter MapStruct

概览

组件坐标

使用配置

核心功能

基于MapStruct

Macula Boot Starter JPA

概览

组件坐标

使用配置

核心功能

阿里druid数据源配置

Macula Boot Starter MyBatis Plus

概览

组件坐标

使用配置

核心功能

阿里druid数据源配置

Macula Boot Starter Redis

概览

组件坐标

使用配置

Macula Boot Starter Cache

概览

组件坐标

使用配置

配置两级缓存

Macula Boot Starter RocketMQ

概览

组件坐标

使用配置

生产者配置建议

消费者配置建议

Push模式

Macula Boot Starter Kafka

概览

组件坐标

使用配置

Macula Boot Starter Crypto

概览

组件坐标

使用配置

核心功能

配置文件加密

Security：方法授权与资源归属

概览

组件坐标

使用配置

JWT 验签配置

Macula Boot Starter SpringDoc

概览

组件坐标

使用配置

核心功能

示例

官方文档

Macula Boot Starter Async

概览

组件坐标

使用配置

核心功能

@Async 上下文传播

`@Async` 上下文传播