# small-common

**Repository Path**: small-template/small-common

## Basic Information

- **Project Name**: small-common
- **Description**: 微服务通用服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-29
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# small-common

一个面向 Spring Boot 应用的通用二方包集合（Maven 多模块工程），提供：API 基础模型、国际化、线程池封装、缓存组件、事件（本地/分布式）以及 Dubbo 插件（Provider/Consumer）。

## 模块一览

| 模块 | 作用 | 自动装配入口/加载方式 |
|---|---|---|
| `api-common` | API 基础模型、返回体、异常码、链路上下文、序列化与工具 | 无自动装配（按需引用） |
| `i18n-common` | 国际化资源扫描、MessageSource、LocaleResolver、Header 语言切换 | Spring `@Configuration`（需被业务工程扫描/引入） |
| `thread-pool-common` | 统一线程池封装、任务提交前后扩展点、默认线程池工具 | `META-INF/spring.factories`: `com.zh.thread.config.ThreadPoolAutoConfiguration` |
| `cache-common` | 本地缓存（Guava）+ 分布式缓存（Redis）与二级缓存抽象 | `AutoConfiguration.imports`: `com.zh.cache.config.CacheAutoConfiguration` |
| `event-common` | 本地事件总线 + RocketMQ 分布式事件总线 | `AutoConfiguration.imports`: `com.zh.event.config.EventAutoConfiguration` |
| `lock-common` | 统一锁管理（本地锁 + Redisson 分布式锁） | 无自动装配（按需引用；业务侧提供 RedissonClient） |
| `dubbo-plugin-*` | Dubbo Provider/Consumer 插件与通用配置 | `AutoConfiguration.imports`: `DubboProviderAutoConfiguration` / `DubboConsumerAutoConfiguration` |
| `demo-common/*` | 演示工程（示例 Controller/Handler/启动类） | 仅用于演示，不建议依赖到业务 |

## 快速开始（依赖引入）

业务工程按需引入模块依赖（示例）：

```xml
<dependency>
  <groupId>com.zh</groupId>
  <artifactId>event-common</artifactId>
  <version>1.0-SNAPSHOT</version>
</dependency>
```

## api-common

**用途**
- API 基础 DTO：请求/响应抽象（REST/RPC）、分页参数、客户端信息等
- 通用异常与错误码：`ResponseCode`（支持国际化脚本）、通用枚举
- 线程链路上下文：`TraceContext`（ThreadLocal traceId）
- 序列化与工具：`ProtoStuffSerializerUtils`、日期工具等

**核心类**
- `TraceContext`：[TraceContext.java](file:///Users/zhanghang/code/gitee/small-template/small-common/api-common/src/main/java/com/zh/api/context/TraceContext.java)
- `ResponseCode`：[ResponseCode.java](file:///Users/zhanghang/code/gitee/small-template/small-common/api-common/src/main/java/com/zh/api/bean/ResponseCode.java)
- `RestResponse`：[RestResponse.java](file:///Users/zhanghang/code/gitee/small-template/small-common/api-common/src/main/java/com/zh/api/rest/dto/RestResponse.java)
- `RPCResponse`：[RPCResponse.java](file:///Users/zhanghang/code/gitee/small-template/small-common/api-common/src/main/java/com/zh/api/rpc/dto/RPCResponse.java)
- `ProtoStuffSerializerUtils`：[ProtoStuffSerializerUtils.java](file:///Users/zhanghang/code/gitee/small-template/small-common/api-common/src/main/java/com/zh/api/utils/serializer/ProtoStuffSerializerUtils.java)

**使用示例**

```java
import com.zh.api.context.TraceContext;
import com.zh.api.rest.dto.RestResponse;

public class Demo {
  public RestResponse<String> ping() {
    TraceContext.setTraceId("trace-xxx");
    return RestResponse.success("ok");
  }
}
```

## i18n-common

**用途**
- 统一国际化消息获取：扫描 classpath 下 `small-message-*.properties` 并构造 `MessageSource`
- 统一语言切换：基于 Header 的 `LocaleChangeInterceptor`（`Accept-Language` 或 `Lang`）
- 兼容错误码脚本模式：`ResponseCode` 使用 `|key|` 组合脚本取国际化文本

**关键实现**
- MVC 配置与拦截器注册：[I18nConfiguration.java](file:///Users/zhanghang/code/gitee/small-template/small-common/i18n-common/src/main/java/com/zh/i18n/config/I18nConfiguration.java)
- 国际化工具类（扫描资源、缓存、静态取值）：[I18nMessageUtil.java](file:///Users/zhanghang/code/gitee/small-template/small-common/i18n-common/src/main/java/com/zh/i18n/utils/I18nMessageUtil.java)
- Header 语言拦截器：[HeaderLocaleChangeInterceptor.java](file:///Users/zhanghang/code/gitee/small-template/small-common/i18n-common/src/main/java/com/zh/i18n/handler/HeaderLocaleChangeInterceptor.java)

**配置项**
- `i18n.default.language`：默认语言（默认 `zh`）

**使用方式**
- 方式 A：业务工程扫描到 `com.zh.i18n.config.I18nConfiguration`（例如主启动类 `@SpringBootApplication(scanBasePackages=...)` 覆盖到该包）
- 方式 B：业务工程显式 `@Import(I18nConfiguration.class)`

运行期从 Header 指定语言：
- `Accept-Language: en`
- 或 `Lang: en`

代码内获取消息：

```java
import com.zh.i18n.utils.I18nMessageUtil;

String msg = I18nMessageUtil.getMessage("test.welcome");
```

## thread-pool-common

**用途**
- 统一线程池封装：支持默认线程池、创建自定义线程池
- 任务上下文扩展点：提交前/执行前/完成后钩子（可用于 traceId、用户上下文透传等）

**自动装配入口**
- Spring Boot 通过 `spring.factories` 加载：[ThreadPoolAutoConfiguration.java](file:///Users/zhanghang/code/gitee/small-template/small-common/thread-pool-common/src/main/java/com/zh/thread/config/ThreadPoolAutoConfiguration.java)

**配置项（绑定到 `thread-pool.*`）**
- `thread-pool.corePoolSize`（默认 10）
- `thread-pool.maximumPoolSize`（默认 20）
- `thread-pool.keepAliveTime`（默认 60）
- `thread-pool.unit`（默认 `SECONDS`）
- `thread-pool.workQueueSize`（默认 100）
- `thread-pool.customName`（默认 `default-thread-pool`）

**使用示例**

使用默认线程池工具类提交任务：

```java
import com.zh.thread.pool.DefaultThreadPoolUtil;

DefaultThreadPoolUtil.execute(() -> {
  // do something
});
```

创建自定义线程池：

```java
import com.zh.thread.config.ThreadPoolConf;
import com.zh.thread.factory.ThreadPoolFactory;

ThreadPoolConf conf = new ThreadPoolConf();
conf.setCorePoolSize(4);
conf.setMaximumPoolSize(8);
conf.setCustomName("biz-pool");

ThreadPoolFactory.create(conf).executeTask(() -> {});
```

扩展点（线程包装器）：
- 抽象定义：[AbstractThreadWrapper.java](file:///Users/zhanghang/code/gitee/small-template/small-common/thread-pool-common/src/main/java/com/zh/thread/wrapper/AbstractThreadWrapper.java)
- 通过 SPI 文件 `META-INF/services/com.zh.thread.wrapper.AbstractThreadWrapper` 注册实现类后，执行任务会自动触发包装器生命周期。

## cache-common

**用途**
- 本地缓存（Guava）：`LocalCacheService`
- 分布式缓存（Redis）：`DistributedCacheService`（默认实现 `RedisCacheService`）
- 二级缓存抽象：`AbstractCacheService` 统一“本地 -> 分布式 -> 回源 -> 回写”的读路径

**自动装配入口**
- [CacheAutoConfiguration.java](file:///Users/zhanghang/code/gitee/small-template/small-common/cache-common/src/main/java/com/zh/cache/config/CacheAutoConfiguration.java)
- 默认配置文件会被加载：`classpath:cache-application.properties`

**配置项（常用）**
- 本地缓存
  - `local.cache.type`：本地缓存实现（默认 `guava`）
  - `local.cache.maxSize`：最大缓存数量（默认 1000）
  - `local.cache.expire`：过期时间（默认 30）
  - `local.cache.expireUnit`：过期单位（默认 `SECONDS`）
  - `local.cache.enable`：是否开启本地二级缓存（`AbstractCacheService` 使用，默认 `false`）
- 分布式缓存
  - `distributed.cache.type`：分布式缓存实现（默认 `redis`）
  - `distributed.cache.timeout`：分布式缓存 TTL（`AbstractCacheService` 使用，默认 3600 秒）
- Redis 连接（默认值在 `cache-application.properties`，生产请覆盖）
  - `spring.redis.host` / `spring.redis.port` / `spring.redis.password` / `spring.redis.database` 等

**使用建议**
- 直接注入 `DistributedCacheService` / `LocalCacheService` 作为通用能力
- 业务侧建议继承 `AbstractCacheService`，只关注 key 规划与回源逻辑

## event-common

**用途**
- 本地事件：进程内发布订阅（同步/异步），用于同进程解耦
- 分布式事件：基于 RocketMQ 发布/消费，跨服务传播领域事件

**自动装配入口**
- [EventAutoConfiguration.java](file:///Users/zhanghang/code/gitee/small-template/small-common/event-common/src/main/java/com/zh/event/config/EventAutoConfiguration.java)
- 默认配置文件会被加载：`classpath:event-application.properties`

### 本地事件（Local）

核心组件：
- 本地事件总线与管理器：[LocalEventBus.java](file:///Users/zhanghang/code/gitee/small-template/small-common/event-common/src/main/java/com/zh/event/local/LocalEventBus.java)、[LocalEventBusManager.java](file:///Users/zhanghang/code/gitee/small-template/small-common/event-common/src/main/java/com/zh/event/local/LocalEventBusManager.java)
- 自动装配：[LocalEventAutoConfiguration.java](file:///Users/zhanghang/code/gitee/small-template/small-common/event-common/src/main/java/com/zh/event/config/LocalEventAutoConfiguration.java)

接入方式：
- 定义事件模型（继承 `LocalDomainEvent`）
- 实现 `LocalEventHandler`（Spring Bean），会自动注册到 `LocalEventHub`
- 通过 `LocalEventBusManager` 发送（同步/异步/返回结果）

### 分布式事件（Distribute / RocketMQ）

核心组件：
- 事件总线（发送）：[DistributeEventBus.java](file:///Users/zhanghang/code/gitee/small-template/small-common/event-common/src/main/java/com/zh/event/distribute/DistributeEventBus.java)
- 消费者（默认）：[DistributeDomainEventConsumer.java](file:///Users/zhanghang/code/gitee/small-template/small-common/event-common/src/main/java/com/zh/event/distribute/consumer/DistributeDomainEventConsumer.java)
- 处理器接口与分发中心：[DistributeEventHandler.java](file:///Users/zhanghang/code/gitee/small-template/small-common/event-common/src/main/java/com/zh/event/distribute/handler/DistributeEventHandler.java)、[DistributeEventHub.java](file:///Users/zhanghang/code/gitee/small-template/small-common/event-common/src/main/java/com/zh/event/distribute/DistributeEventHub.java)
- 自动装配：[DistributeEventAutoConfiguration.java](file:///Users/zhanghang/code/gitee/small-template/small-common/event-common/src/main/java/com/zh/event/config/DistributeEventAutoConfiguration.java)

外部依赖与版本要求：
- 使用 `org.apache.rocketmq:rocketmq-spring-boot-starter` 作为客户端封装，当前版本在 [`event-common/pom.xml`](file:///Users/zhanghang/code/gitee/small-template/small-common/event-common/pom.xml#L14-L34) 中定义为 `2.2.2`，对应 RocketMQ 4.x 客户端。
- 建议安装/使用 RocketMQ 4.x 系列服务端（如 4.9.x）；若使用 RocketMQ 5.x，请确保以兼容 4.x 协议的方式部署（保留 NameServer + Broker），本组件暂未启用 `rocketmq-v5-client-spring-boot-starter`。
- 若业务工程已直接依赖 RocketMQ 相关 starter/client，请通过 Maven `dependencyManagement` 统一版本，避免 `rocketmq-spring-boot-starter` 版本不一致导致的类冲突。
- 运行分布式事件至少需要可用的 NameServer 与 Broker（默认 NameServer 端口 9876）；`rocketmq.name-server` 必须能被业务应用访问到。

**配置项（常用）**
- `rocketmq.name-server`：RocketMQ NameServer 地址（默认 `localhost:9876`，生产需覆盖）
- `rocketmq.producer.group`：Producer Group（业务侧建议显式配置，用于发送端实例化与链路追踪等能力）
- `domain.event.topic`：分布式事件 topic（默认 `domain_event_topic`）
- `domain.event.tags`：消费者 tag 过滤（默认 `*`）
- `domain.event.groupId`：消费者组（默认 `${spring.application.name}`；未读取到默认配置时会回退到 `default_event_group`）
- `domain.event.consumer`：是否启用默认消费者 Bean（默认 `true`）
- `domain.event.bus`：是否启用发送（当前实现未按该开关做条件化，业务可自行控制是否调用总线）

**使用示例（生产侧建议）**
1) 定义事件（继承 `DistributeDomainEvent`）
2) 编写处理器（实现 `DistributeEventHandler<T>`，交给 Spring 管理）
3) 注入 `DistributeEventBus` 并发布事件

演示代码可参考：
- 发布：[DistributeEventController.java](file:///Users/zhanghang/code/gitee/small-template/small-common/demo-common/event-demo-common/src/main/java/com/zh/event/controller/DistributeEventController.java)
- 处理器：[DistributeUserEventHandler.java](file:///Users/zhanghang/code/gitee/small-template/small-common/demo-common/event-demo-common/src/main/java/com/zh/event/handler/DistributeUserEventHandler.java)

## dubbo-plugin（provider / consumer / common）

**用途**
- Provider：扫描接口/服务并发布到注册中心
- Consumer：按接口生成 Dubbo 代理并注入到 Spring
- common：统一 Dubbo 配置绑定与上下文持有（如 trace/locale）

**自动装配入口**
- Consumer：[DubboConsumerAutoConfiguration.java](file:///Users/zhanghang/code/gitee/small-template/small-common/dubbo-plugin/dubbo-plugin-consumer/src/main/java/com/zh/dubbo/consumer/DubboConsumerAutoConfiguration.java)
- Provider：[DubboProviderAutoConfiguration.java](file:///Users/zhanghang/code/gitee/small-template/small-common/dubbo-plugin/dubbo-plugin-provider/src/main/java/com/zh/dubbo/config/DubboProviderAutoConfiguration.java)
- 配置绑定：[DubboProperties.java](file:///Users/zhanghang/code/gitee/small-template/small-common/dubbo-plugin/dubbo-plugin-common/src/main/java/com/zh/dubbo/common/DubboProperties.java)（`dubbo.*`）

**默认配置文件**
- Consumer：`classpath:dubbo-consumer-application.properties`（配置了 `dubbo.registry.address=nacos://localhost:8848` 等）
- Provider：`classpath:dubbo-provider-application.properties`（配置了 `dubbo.provider.scan-packages`、协议端口等）

**Consumer 使用示例（推荐：注册为 Spring Bean）**

```java
import com.zh.dubbo.consumer.ServiceSubscriber;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class DubboConsumerConfig {
  private final ServiceSubscriber subscriber;

  public DubboConsumerConfig(ServiceSubscriber subscriber) {
    this.subscriber = subscriber;
  }

  @Bean
  public com.zh.api.facade.ProviderDemoService providerDemoService() {
    return subscriber.consumer(com.zh.api.facade.ProviderDemoService.class)
        .group("DEFAULT_GROUP")
        .version("1.0.0")
        .subscribe();
  }
}
```

**Provider 侧说明**
- Provider 侧会读取 `dubbo.provider.scan-packages` 扫描要发布的接口包，并由发布器在 Spring 上下文刷新后发布服务。

更完整的设计说明可参考仓库内文档：
- [dubbo-设计文档.md](file:///Users/zhanghang/code/gitee/small-template/small-common/dubbo-plugin/dubbo-设计文档.md)

## lock-common

**用途**
- 本地锁：进程内互斥，适用于单实例或单 JVM 场景
- 分布式锁：基于 Redisson（Redis）实现跨实例互斥

外部依赖与接入要求：
- 分布式锁提供通用接口：[DistributedLockClient.java](file:///Users/zhanghang/code/gitee/small-template/small-common/lock-common/src/main/java/com/zh/lock/distribute/DistributedLockClient.java)、[DistributedLock.java](file:///Users/zhanghang/code/gitee/small-template/small-common/lock-common/src/main/java/com/zh/lock/distribute/DistributedLock.java)
- Redisson 为默认实现：[RedissonLockUtil.java](file:///Users/zhanghang/code/gitee/small-template/small-common/lock-common/src/main/java/com/zh/lock/distribute/RedissonLockUtil.java)，业务侧需提供 `org.redisson.api.RedissonClient`；本模块不主动自动装配 RedissonClient。
- `lock-common` 内置 Redisson 依赖版本：`3.17.6`（如业务侧已引入 Redisson，请统一版本，避免冲突）

**本地锁（local）**
- 锁工厂：[LocalLockFactory.java](file:///Users/zhanghang/code/gitee/small-template/small-common/lock-common/src/main/java/com/zh/lock/local/LocalLockFactory.java)

使用示例：

```java
import com.zh.lock.local.LocalLockFactory;

import java.util.concurrent.locks.Lock;

LocalLockFactory factory = new LocalLockFactory();
Lock lock = factory.getLock("order:123");
lock.lock();
try {
  // critical section
} finally {
  lock.unlock();
}
```

**分布式锁（distribute）**
- 通用接口：[DistributedLockClient.java](file:///Users/zhanghang/code/gitee/small-template/small-common/lock-common/src/main/java/com/zh/lock/distribute/DistributedLockClient.java)
- Redisson 实现：[RedissonLockUtil.java](file:///Users/zhanghang/code/gitee/small-template/small-common/lock-common/src/main/java/com/zh/lock/distribute/RedissonLockUtil.java)

使用示例（业务侧需自行提供 `RedissonClient`）： 

```java
import com.zh.lock.distribute.RedissonLockUtil;
import org.redisson.api.RedissonClient;

import java.util.concurrent.TimeUnit;

RedissonClient redissonClient = null;
RedissonLockUtil lockUtil = new RedissonLockUtil(redissonClient);
lockUtil.runWithLock("order:123", 1, 10, TimeUnit.SECONDS, () -> {
  // critical section
});
```