# sdpj

**Repository Path**: clarkstore/sdpj

## Basic Information

- **Project Name**: sdpj
- **Description**: SDPJ 是基于 JDK 21 构建的模块化开发工具平台，项目坐标为 `io.gitee.clarkstore:sdpj`。

项目定位为"按需引入的业务开发工具包"，沉淀通用响应、异常体系、Spring 上下文工具、国际化、Web 增强、Redis、MyBatis-Plus、代码生成、文档模板导出、邮件、HTTP、业务日志、NanoMQ等基础能力，便于在同技术栈业务系统中复用。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-03
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[![License](https://img.shields.io/badge/License-Apache--2.0-brightgreen.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![JDK](https://img.shields.io/badge/JDK-21+-green.svg)](https://www.oracle.com/java/technologies/downloads/)
[![maven-central](https://maven-badges.herokuapp.com/maven-central/io.gitee.clarkstore/sdpj/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.gitee.clarkstore/sdpj)
[![Author](https://img.shields.io/badge/Ones%20Author-Clark-blue.svg)](https://gitee.com/clarkstore/sdpj)

# SDPJ 工具平台

## 平台简介

SDPJ 是基于 JDK 21、Spring Boot 3.x 构建的模块化开发工具平台，项目坐标为 `io.gitee.clarkstore:sdpj`。

项目定位为"按需引入的业务开发工具包"，沉淀通用响应、异常体系、Spring 上下文工具、国际化、Web 增强、Redis、MyBatis-Plus、代码生成、文档模板导出、邮件、HTTP、业务日志、公共参数与字典、NanoMQ、OSS 等基础能力，便于在同技术栈业务系统中复用。

## 技术栈

| 类型 | 说明 |
| --- | --- |
| JDK | 21+ |
| Spring Boot | 3.5.x |
| Web 容器 | Undertow（项目 BOM 中排除了 Web Starter 默认 Tomcat） |
| ORM | MyBatis-Plus |
| Redis | Spring Data Redis |
| 连接池 | Druid Spring Boot Starter |
| 工具库 | Hutool、Lombok |
| 文档处理 | FesodSheet、docx4j、Freemarker、Apache FOP |
| API 文档 | SpringDoc OpenAPI |
| AI 相关 | Spring AI、Spring AI Alibaba、DashScope SDK |
| 对象存储 | AWS S3 SDK、x-file-storage |
| 发布 | Central Portal / Maven Central，使用 `flatten-maven-plugin` 支持 CI-Friendly 版本 |

## 项目结构

```text
sdpj
├── sdpj-bom                        # 依赖版本管理 BOM
├── sdpj-common                     # 通用基础模块（core/data/web）
├── sdpj-kit                        # 工具模块（codegen/doc/extra/log/nanomq/oss）
├── sdpj-ai                         # AI 模块（pgvector/tika/rag）
├── sdpj-example                    # 示例模块
├── README.md                       # 项目说明（本文件）
├── mvn.md                          # 发布和版本命令备忘
└── AGENTS.md                       # AI Agent 项目规则
```

## 模块说明

| 模块 | 说明 | 详情 |
| --- | --- | --- |
| sdpj-bom | 依赖版本管理 BOM | [查看详情](sdpj-bom/README.md) |
| sdpj-common | 通用基础模块（core/data/web） | [查看详情](sdpj-common/README.md) |
| sdpj-kit | 工具模块（codegen/doc/extra/log/nanomq/oss） | [查看详情](sdpj-kit/README.md) |
| sdpj-ai | AI 模块（pgvector/tika/rag） | - |
| sdpj-example | 示例模块，演示各子模块用法 | [查看详情](sdpj-example/README.md) |

## 自动装配概览

| 模块 | 自动装配入口 |
| --- | --- |
| sdpj-common-core | `com.ones.sdp.common.core.util.SpringContextKit` |
| sdpj-common-web | `com.ones.sdp.common.web.OnesWebAutoConfiguration` |
| sdpj-kit-extra | `com.ones.sdp.kit.extra.OnesKitExtraAutoConfiguration` |
| sdpj-kit-log | `com.ones.sdp.kit.log.OnesLogAutoConfiguration` |
| sdpj-kit-param | `com.ones.sdp.kit.param.config.ParamAutoConfiguration`<br>`com.ones.sdp.kit.param.config.DictAutoConfiguration` |
| sdpj-kit-nanomq | `com.ones.sdp.kit.nanomq.OnesNanoMqAutoConfiguration` |

自动配置入口文件路径：

```text
src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
```

## 使用提示

1. 本项目基于 JDK 21 构建。
2. 建议优先通过 `sdpj-bom` 统一依赖版本。
3. 根工程的 `maven-compiler-plugin` 默认配置了 `<skip>true</skip>`，需要真实编译时请显式添加 `-Dmaven.compiler.skip=false`。
4. 部分工具类依赖 `SpringContextKit` 从 Spring 容器获取 Bean，使用前需确保对应配置类已被注册。
5. `sdpj-common-data` 当前未声明自动装配入口，引入后需注意组件扫描或显式导入。
6. `sdpj-kit-log` 需要业务侧实现 `OnesLogService` 才会启用日志切面和监听器。
7. `sdpj-kit-codegen` 会直接连接数据库并输出代码，使用前请检查 `generator.properties`。
8. `sdpj-kit-oss` 当前不属于聚合构建模块，使用前请确认版本和依赖状态。

## Maven 常用命令

### 编译

```powershell
mvn compile "-Dmaven.compiler.skip=false"
```

指定模块及其依赖一起编译：

```powershell
mvn -pl sdpj-example -am compile "-Dmaven.compiler.skip=false"
```

### 测试

```powershell
mvn test "-Dmaven.compiler.skip=false"
```

运行示例模块测试：

```powershell
mvn -pl sdpj-example -am test "-Dmaven.compiler.skip=false"
```

Redis 示例依赖本地 Redis 服务，PostgreSQL 日志示例依赖本地数据库，运行前需确认环境。

### 版本与发布

发布除 `sdpj-example` 之外的模块：

```powershell
mvn clean deploy -T 2.0C -P release -pl !sdpj-example -f pom.xml
```

指定发布核心模块：

```powershell
mvn clean deploy -T 2.0C -P release -pl sdpj-bom,sdpj-common,sdpj-kit -f pom.xml
```

## 代码规范摘要

- Java 版本按根 POM 使用 JDK 21。
- 源码编码统一使用 UTF-8。
- 包名保持 `com.ones.sdp...` 结构。
- 常量类优先使用接口形式命名为 `*Consts`，例如 `DataConsts`、`RedisStreamConsts`。
- 工具类命名使用 `*Kit`，例如 `RedisKit`、`SpringContextKit`、`MsgKit`。
- Service 建议使用接口 + `impl` 实现类结构。
- 日志使用 Lombok `@Slf4j`，不要手写 `LoggerFactory`。
- 示例代码、测试说明、日志和注释优先使用中文。
- 对外 API 参数建议显式指定注解名称，例如 `@RequestParam("message")`。
- 公共默认值和魔法值应提取到常量中，避免硬编码。

## 开源协议

遵循 [Apache 2.0 协议](https://www.apache.org/licenses/LICENSE-2.0.html)，允许商业使用，但请保留类作者、Copyright 信息。