# compents

**Repository Path**: cc-projects/compents

## Basic Information

- **Project Name**: compents
- **Description**: 组件库
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# compents

> Spring Boot Starter 组件库 — 多模块 Maven 工程

基于 Spring Boot 3.2.x / JDK 17（**同时支持 Spring Boot 2.7**），遵循 Spring Boot 官方 Starter 规范编写的自定义组件库。每个组件按官方约定拆分为 **autoconfigure** + **starter** 两个模块，支持按需引入、独立发布。

## Spring Boot 版本兼容

| Spring Boot 版本 | 命名空间 | 引用方式 | 自动装配机制 |
|-----------------|---------|---------|-------------|
| 3.x（默认） | jakarta | 默认坐标 | `AutoConfiguration.imports` |
| 2.7 | javax | `-sb27` 制品 | `spring.factories` |

**SB 3.x 使用方**（默认）：
```xml
<dependency>
    <groupId>com.cc.compents</groupId>
    <artifactId>compents-mock-spring-boot-starter</artifactId>
</dependency>
```

**SB 2.7 使用方**：使用 `-Psb27` 构建产出的 javax 制品（构建方执行 `mvn clean install -Psb27`，产出 jar finalName 带 `-sb27` 后缀）。jakarta/javax 命名空间分裂使同一字节码无法跑两版本，故通过 Maven profile 产出双制品。

## 文档导航

| 文档 | 面向 | 内容 |
|------|------|------|
| **[ARCHITECTURE.md](ARCHITECTURE.md)** | 维护者 / 贡献者 | 架构设计与可复用模式（级联装配、prod 守卫、optional 策略、SpEL 安全、能力诊断、热刷新、异常传播） |
| **[CONTRIBUTING.md](CONTRIBUTING.md)** | 贡献者 | 新增组件流程、自动装配规范、测试规范、代码风格 |
| [compents-log README](compents-log-spring-boot-autoconfigure/README.md) | 使用方 | 请求日志增强：路径过滤、慢请求标记 |
| [compents-mock README](compents-mock-spring-boot-autoconfigure/README.md) | 使用方 | 接口/方法 mock：HTTP/Feign/方法三类，SpEL 条件、配置刷新、抛异常 |
| [compents-backup README](compents-backup-spring-boot-autoconfigure/README.md) | 使用方 | 表级数据备份：全量/增量、幂等模式、事务隔离 |

## 内置组件

| 组件 | 功能 |
|---|---|
| **log** | HTTP 请求日志增强：通过 `HandlerInterceptor` 记录每个请求的 method/URI/状态码/耗时，支持路径过滤（include/exclude）与慢请求 WARN 标记。 |
| **mock** | 接口/方法 mock：HTTP 接口、OpenFeign 调用、Java 方法三类桩化，支持 SpEL 参数条件匹配与配置中心实时刷新。仅 dev/test 等非生产 profile 生效。 |
| **backup** | 同数据源表级数据备份：配置驱动「源表→目标表」搬运，支持全量/增量、三种幂等模式（none/delete-insert/upsert）、独立事务失败隔离、配置中心实时刷新。定时任务由业务系统驱动，模块开放 BackupExecutor/BackupPositionStore 扩展点。仅非 prod profile 生效。 |

---

## 模块结构

```
compents (pom, 父 POM)
├── compents-dependencies                      ← BOM：统一管理所有组件版本
├── compents-log-spring-boot-autoconfigure     ← log 组件：自动装配实现
├── compents-log-spring-boot-starter           ← log 组件：空 jar，依赖聚合
├── compents-mock-spring-boot-autoconfigure    ← mock 组件：自动装配实现
├── compents-mock-spring-boot-starter          ← mock 组件：空 jar，依赖聚合
├── compents-backup-spring-boot-autoconfigure  ← backup 组件：自动装配实现
├── compents-backup-spring-boot-starter        ← backup 组件：空 jar，依赖聚合
└── compents-test                              ← 聚合测试模块：单元 + 集成测试 + 覆盖率（不发布制品）
```

命名遵循官方约定：第三方 starter 为 `xxx-spring-boot-starter`，自动装配为 `xxx-spring-boot-autoconfigure`。装配注册使用 SB3 的 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`。

---

## 业务方如何引入

### 1. 引入 BOM 统一版本

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.cc.compents</groupId>
            <artifactId>compents-dependencies</artifactId>
            <version>1.0.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

### 2. 按需引入组件 starter

```xml
<dependencies>
    <dependency>
        <groupId>com.cc.compents</groupId>
        <artifactId>compents-log-spring-boot-starter</artifactId>
        <!-- 版本由 BOM 管理，无需声明 -->
    </dependency>
</dependencies>
```

各组件的详细配置与使用示例见对应的模块 README（见上方文档导航）。

### 快速示例：log 配置

```yaml
compents:
  log:
    enabled: true                 # 总开关
    prefix: "[compents-log]"      # 日志前缀
    request:
      enabled: true               # 请求日志开关
      include-paths: ["/api/**"]  # 仅记录这些路径；为空则记录全部
      exclude-paths: ["/actuator/**", "/favicon.ico"]  # 不记录这些路径（优先级高）
      slow-request-threshold: 1s  # 慢请求阈值，超过则 WARN 级别标记
```

**效果**：
```
INFO  [compents-log] GET /api/users -> status=200 (45ms)
WARN  [compents-log] SLOW POST /api/export -> status=200 (2350ms, threshold=1000ms)
```

### 快速示例：backup 使用

```yaml
compents:
  backup:
    rules:
      - id: order-archive
        source-table: t_order
        target-table: t_order_bak
        condition: "status = 1"
        mode: full
        idempotent-mode: delete-insert
        order: 0
```

```java
@Autowired
private BackupService backupService;

@Scheduled(cron = "0 0 2 * * ?")
public void dailyBackup() {
    BackupSummary summary = backupService.execute();
    if (!summary.isOverallSuccess()) {
        log.warn("部分规则失败: {}", summary.getFailedCount());
    }
}
```

更多用法（增量备份、幂等模式、扩展点）见 [backup README](compents-backup-spring-boot-autoconfigure/README.md)。

---

## 如何新增一个组件

详见 **[CONTRIBUTING.md](CONTRIBUTING.md)** 的「新增组件流程」（6 步法：复制模块 → 改 pom → 编写装配类 → 注册 imports → 配置元数据 → BOM 登记双处）。

---

## 构建

### 构建并跳过测试（发布场景）

```bash
mvn clean install -DskipTests
```

### 构建并运行测试（含覆盖率报告）

```bash
mvn clean install
```

测试与覆盖率收集在 `compents-test` 模块进行：

| 场景 | 命令 |
|---|---|
| 仅跑测试模块测试 | `mvn clean test -pl compents-test` |
| 跳过覆盖率门禁只看报告 | `mvn clean verify -pl compents-test -Djacoco.skip=true` |

覆盖率报告产物：`compents-test/target/site/jacoco/index.html`（HTML）/ `jacoco.csv`（机器可读）。
`mvn verify` 会触发 `jacoco:check`，要求 compents 包行覆盖率 ≥ 80%。

测试分层与覆盖率归因机制详见 [CONTRIBUTING.md](CONTRIBUTING.md#测试规范)。

环境要求：JDK 17+、Maven 3.6+。