skrstop-components 是一个基于 Spring Boot 的常用功能封装组件库，开箱即用地提供统一响应（统一返回值）、通用异常处理、多数据源（动态数据源）、Redis、MongoDB、远程对象存储、常用自定义注解等能力，帮助你省去大量重复配置代码，支持 JDK 8+ 与 JDK 17+。本文带你 5 分钟完成依赖接入，零配置跑通第一个项目。

一、skrstop-components 是什么？

一句话：把 Spring Boot 项目里"人人要写、写法都差不多"的通用代码，提前封装成 Starter 自动配置模块。它的模块结构清晰，按需引入即可：

• components-core：基础核心模块，含统一响应实体 Result.java、通用异常、通用注解
• components-starters：自动配置模块，如 components-starter-web（统一返回值 + 异常处理）、components-starter-database（数据库 + 多数据源）、components-starter-redis、components-starter-mongodb、components-starter-id（ID 生成服务）等
• components-utils：解压缩、序列化、线程池、HTTP 客户端等纯工具模块
• components-examples：可直接运行的完整样例工程

完整目录说明见 README.md，版本变更记录见 CHANGELOG.md。

二、一键安装步骤：添加 Maven 依赖

组件已发布到 Maven，按需引入即可。JDK 17 项目使用最新版（当前 1.3.5.20260520-RELEASE），JDK 17 以下请使用 1.2.x 版本。

以"统一响应 + 通用异常 + 数据库"为例，在 pom.xml 中引入三个 starter：

<dependency> <groupId>com.skrstop.framework</groupId> <artifactId>components-starter-web</artifactId> </dependency> <dependency> <groupId>com.skrstop.framework</groupId> <artifactId>components-starter-database</artifactId> </dependency>

版本管理集中在根 pom.xml 中，基于 Spring Boot 3.3.13、MyBatis-Plus、Redisson 等主流版本统一管理，无需自己处理版本冲突。

三、统一响应：Controller 返回值自动包装

这是最"省心"的功能。引入components-starter-web后，Controller 返回任意对象都会被自动包装成统一的 Result 结构，含状态码、消息和数据节点，全程零配置。

看官方样例 ExampleReturnController.java：

@GetMapping("/exampleReturn1") public Object exampleReturn1() { HashMap<String, String> result = new HashMap<>(); result.put("1", "1"); return result; // 返回后自动被包装为统一 Result }

访问该接口，前端拿到的不再是裸 Map，而是标准的统一响应 JSON。内置通用错误码定义在 CommonResultCode.java（SUCCESS、FAIL、NOT_FOUND 等）。

几个实用开关（前缀skrstop.response.config，参考 GlobalConfigConst.java）：

• @DisableGlobalResponse：单个接口关闭自动包装
• longToString: true：Long 转字符串，避免前端精度丢失
• 时间格式化、null 字段隐藏等均支持 yml 配置

四、通用异常：自定义错误码 + 全局兜底

业务异常只需抛框架异常类，全局异常处理器会自动将其转成统一响应格式，不用每个 Controller 写 try-catch。

第 1 步：定义业务错误码枚举，实现IResult接口。样例见 CustomErrorCode.java：

@AllArgsConstructor public enum CustomErrorCode implements IResult { CUSTOM_ERROR("custom_error", "自定义异常code"); // code / message 字段 }

第 2 步：在业务逻辑中直接抛出，见 ExampleExceptionController.java：

throw new SkrstopBusinessException(CustomErrorCode.CUSTOM_ERROR);

框架提供多级异常体系（位于 components-core-exception）：SkrstopBusinessException（业务异常）、SkrstopRuntimeException（运行时异常）、SkrstopDataRuntimeException（可携带数据）等。

配合配置项skrstop.exception.config.always-return-http-ok: true（样例见 application.yml），异常时 HTTP 状态码恒为 200，具体成败由响应体中的 code 表达，方便前端统一解析。

五、多数据源：yml 声明 + 注解切换

components-starter-database内置动态多数据源（基于 dynamic-datasource），三步接入：

1. yml 中声明多个数据源（样例配置见 application.yml 的skrstop.database.dynamic节点）：

skrstop: database: dynamic: enabled: true primary: db0 >@GetMapping("/exampleDynamic") @DSDatabaseTransactional(rollbackFor = Exception.class) public Map<String, List<Example1>> exampleDynamic(boolean exception) { ... }

MyBatis-Plus 的SuperMapper、分页PageQuery、基础实体（AbstractBaseEntity.java 等）也已内置，Mapper 扫描位置通过skrstop.database.config.mapper-class-location配置。

六、跑通第一个项目：从官方样例开始

仓库内置可直接启动的完整示例工程 components-example-starters-simple，覆盖统一响应、异常、MySQL/H2 多数据源、Redis、MongoDB、Feign 等全部核心功能。

1. 克隆仓库（如需）：git clone https://gitcode.com/gh_mirrors/sk/skrstop-components
2. 打开示例启动类 ExampleStartersSimpleApplicationBootstrap.java，直接运行
3. 访问接口验证：
   • /exampleReturn1—— 体验返回值自动包装
   • /exampleException?exception=2—— 体验统一异常响应
   • /exampleDynamic—— 体验跨库本地事务

示例默认使用 H2 嵌入式数据库 + 本地 Redis/MongoDB，无需额外准备生产级环境。

七、版本兼容与更多能力

版本选择提示：JDK 17 及以上 → 最新版（Spring Boot 3.3.x）；JDK 8+ 老项目 → 1.2.x 版本（Spring Boot 2.x 线）。

总结

skrstop-components 的价值就体现在"少写代码"上：

1. 统一响应——引入 starter 即生效，Controller 只管返回业务对象
2. 通用异常——自定义错误码枚举 + 全局兜底，前端按统一结构解析
3. 多数据源——yml 声明 + 注解切换 + 跨库本地事务，开箱即用

按本文步骤走完，5 分钟内即可在示例工程上验证全部三大核心功能。更多细节可继续阅读 README.md 的模块清单，或深入 components-starters 目录探索每个 starter 的自动配置实现。