微服务 on Macula

Macula Boot Starter Dubbo

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

概览

引入基于Dubbo的微服务框架。

组件坐标

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

使用配置

基于springboot使用dubbo

本模块无自有配置前缀，常用配置由 Dubbo 绑定：

属性	说明
`dubbo.application.name`	Dubbo 应用名
`dubbo.registry.address`	注册中心地址，按所用注册中心协议填写
`dubbo.protocol.name` / `port`	服务协议 / 暴露端口
`dubbo.scan.base-packages`	Dubbo 服务实现扫描包
`dubbo.consumer.timeout` / `retries`	消费端调用超时（毫秒）/ 重试次数；非幂等操作慎用重试
`dubbo.provider.timeout`	提供端默认超时（毫秒）

请参考官方文档

核心功能

dubbo与spring cloud互通

本模块提供 Dubbo RPC 依赖，不会自动将 HTTP/Feign 接口转换为 Dubbo 接口。注册中心、协议及服务暴露使用 dubbo.* 配置；与 Spring Cloud 共用注册中心时，仍需分别配置两套服务发现与调用方式。

依赖引入


<dependencies>
 <dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-spring-boot-starter</artifactId>
 </dependency>
</dependencies>

版权说明

dubbo：https://github.com/apache/dubbo/blob/3.2/LICENSE

Macula Boot Starter Feign

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

概览

引入spring-cloud-openfeign并添加了HMAC拦截器、请求头传递等功能。

组件坐标


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

使用配置

HTTP 客户端配置使用 spring.cloud.openfeign.* 前缀，不再使用旧的 feign.*。

spring:
 cloud:
 openfeign:
 httpclient:
 hc5:
 enabled: false
 okhttp:
 read-timeout: 60s
 okhttp:
 enabled: true
macula:
 feign:
 header-relay:
 enabled: false
 headers: []

属性	默认值 / 示例	说明
`macula.feign.header-relay.enabled`	默认 `false`	开启额外请求头透传，不控制内置 Authorization、请求 ID 和灰度头
`macula.feign.header-relay.headers`	默认空列表	额外透传的头名称，只配置可信且必要的头
`spring.cloud.openfeign.okhttp.enabled`	示例 `true`	选择已引入的 OkHttp 客户端
`spring.cloud.openfeign.httpclient.hc5.enabled`	示例 `false`	使用 OkHttp 时禁用 HC5 客户端选择
`spring.cloud.openfeign.client.config.<客户端名>.connectTimeout`	按需设置	单客户端建连超时，单位毫秒；`default` 表示全局配置
`spring.cloud.openfeign.client.config.<客户端名>.readTimeout`	按需设置	单客户端读取超时，单位毫秒

核心功能

请求头传递

Servlet 应用默认注册 HeaderRelayInterceptor，传递请求 ID、Authorization 及灰度上下文；已有 Authorization 不会被自动覆盖。没有请求 ID 时会生成新值。额外请求头仅在 macula.feign.header-relay.enabled=true 时按 headers 白名单传递。

Gateway：路由、认证与接口保护

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

概览

Gateway 是应用的统一入口，基于 Spring Cloud Gateway WebFlux 提供路由转发、入口认证与授权、接口加解密和签名、调用链关联及灰度标签传递。它既承担安全控制，也承担网关的流量转发与集成职责。

能力	内容
路由	HTTP / WebSocket 转发、服务发现、路径过滤与 CORS
认证授权	Token、AK/SK、API Key，角色 / 菜单 / URL 规则
内部身份	签发内部 JWT，提供 JWK 公钥集供微服务验签
接口保护	CryptoService 扩展、SM2 / SM4、请求签名与 nonce 检查
运行支撑	网关与 System Redis、Token 缓存移除、Trace ID 响应头
灰度接入	接收并传递 grayversion 标签，配合云平台负载均衡

下游 BFF / Service 继续使用 Security Starter 做 JWT 验签与细粒度授权，整体分层见安全架构。本页保留 Gateway 完整能力的接入与使用说明。

组件坐标

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

上例选择 Alibaba / Nacos 网关；Tencent / Polaris 网关选择下面的组合，按实际云平台使用其中一种：

Macula Boot Starter Cloud Alibaba

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

概览

Alibaba 接入面向 Java 17、Spring Boot 4 与 Spring Cloud 2025.1，组合 Nacos 配置与服务发现、Sentinel、Feign 和灰度路由能力。业务服务与网关按各自角色选择 Starter。

基于 Nacos 实例元数据和 Spring Cloud LoadBalancer，按 grayversion 标签筛选实例，再在候选实例中轮询。适用于 Alibaba 服务调用和 Spring Cloud Gateway 的服务发现路由，不提供百分比放量、用户分群或强隔离策略。

基于Spring Cloud Alibaba 的微服务开源套件Nacos、Sentinel等搭建微服务平台。

组件坐标

业务服务选择 macula-boot-starter-cloud-alibaba，网关选择 macula-boot-starter-cloud-alibaba-scg。SCG 已包含共享 Gateway、Nacos、Sentinel Gateway 和灰度模块，无需再重复引入共享 Gateway；Web、持久化等业务能力按需组合。

macula-boot-starter-cloud 本身只是 packaging 为 pom 的聚合模块，不会自动启用全部云组件。子模块的 groupId 为 dev.macula.boot，版本由 Macula Boot Parent 管理；未采用统一版本管理时显式指定版本。

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

通常直接选择 Alibaba Starter 或 macula-boot-starter-cloud-alibaba-scg，二者已传递引入本模块，无需重复声明。单独引入时还需提供 Nacos Discovery、Spring Cloud LoadBalancer；它们在本模块 POM 中为 optional 依赖。

Macula Boot Starter Cloud Tencent

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

概览

Tencent 接入面向 Java 17、Spring Boot 4 与 Spring Cloud 2025.1，提供 Polaris 配置、服务发现与 Feign 调用能力；业务服务与网关按角色选择对应 Starter。

基于Spring Cloud Tencent 的微服务开源套件Polarismesh搭建微服务平台。

组件坐标

业务服务选择 macula-boot-starter-cloud-tencent，网关选择 macula-boot-starter-cloud-tencent-scg。SCG 已组合共享 macula-boot-starter-cloud-gateway，无需重复引入。通常按项目选择 Tencent 或 Alibaba 一套云平台。

macula-boot-starter-cloud 是聚合 POM，不是启用全部云能力的运行时 Starter。以下子模块均使用 dev.macula.boot 坐标，版本由 Macula Boot Parent 管理；未采用统一版本管理时显式指定版本。

<!-- 微服务模块依赖 -->
<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-cloud-tencent</artifactId>
 <version>${macula.version}</version>
</dependency>

 <!-- 网关模块依赖 -->
<dependency>
<groupId>dev.macula.boot</groupId>
<artifactId>macula-boot-starter-cloud-tencent-scg</artifactId>
<version>${macula.version}</version>
</dependency>

使用配置

以下按当前 Tencent Provider application.yml 精简；网关差异见 Tencent Gateway application.yml。

属性	示例值 / 说明
`spring.config.import`	`optional:polaris`，通过 Config Data 导入配置
`spring.profiles.group.docker`	`local`，Docker 复用本地默认配置
`spring.cloud.polaris.config.enabled` / `auto-refresh`	示例均为 `true`，启用配置中心和刷新
`spring.cloud.polaris.config.groups[].name`	应用名对应的配置组
`spring.cloud.polaris.discovery.enabled` / `register`	示例均为 `true`，启用发现和注册
`spring.cloud.polaris.address`	local：`grpc://127.0.0.1:38091`；docker：`grpc://polaris:8091`
`spring.cloud.polaris.namespace`	`POLARIS_NAMESPACE`，示例为 `macula-dev`
`spring.cloud.nacos.discovery.server-addr`	Polaris Nacos 兼容地址：local `127.0.0.1:38849`，docker `polaris:8848`

本模块无额外自有属性；表中地址和开关是 samples 配置，不是所有应用的默认值。