# hei-boot

**Repository Path**: jiangbyte/hei-boot

## Basic Information

- **Project Name**: hei-boot
- **Description**: HEI Boot 是 HEI 项目的 Spring Boot 后端模板，使用 JDK 21、Spring Boot 4、Maven 多模块和 PostgreSQL 构建
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-02
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HEI Boot

![JDK](https://img.shields.io/badge/JDK-21-007396?logo=openjdk&logoColor=white)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.1.x-6DB33F?logo=springboot&logoColor=white)
![Maven](https://img.shields.io/badge/Maven-Multi--Module-C71A36?logo=apachemaven&logoColor=white)
![PostgreSQL](https://img.shields.io/badge/PostgreSQL-Supported-4169E1?logo=postgresql&logoColor=white)
![Redis](https://img.shields.io/badge/Redis-Supported-DC382D?logo=redis&logoColor=white)
![MyBatis-Plus](https://img.shields.io/badge/MyBatis--Plus-3.5.x-blue)
![Sa-Token](https://img.shields.io/badge/Sa--Token-1.45.x-orange)
![License](https://img.shields.io/badge/License-MIT-green)

HEI Boot 是 HEI 项目的 Spring Boot 后端模板，使用 JDK 21、Spring Boot 4、Maven 多模块和
PostgreSQL 构建。项目结构参考 HEI FastAPI 原型，并吸收 Snowy、RuoYi-Vue-Plus 的后端分层方式，
目标是为中后台、门户和通用业务系统提供一套可迁移到 `hei-cloud` 的模块化单体后端骨架。

当前仓库只包含后端模板。领域模型严格对齐 `hei-fastapi` 中的模型定义，Java 字段保持驼峰命名，
对外 JSON 字段统一使用 `snake_case`。

> **请注意，本项目目前处于后端模板和模型迁移阶段，基础结构、依赖组合和领域模型已建立，但业务闭环、
> 数据库迁移脚本和生产部署资产仍在持续补齐。暂不建议直接用于生产环境。**

## 功能概览

- 基于 JDK 21、Spring Boot 4.1.x、Spring Framework 7、Maven 多模块。
- `app/admin` 作为可运行的管理端应用入口，后续可平滑拆分或迁移到 `hei-cloud`。
- `common` 沉淀通用技术能力，`module-api` 定义跨模块契约，`module` 承载业务实现。
- API 路径按入口组织，预留 `/api/v1/admin`、`/api/v1/portal`、`/api/v1/internal`。
- 内置 Sa-Token 登录上下文、权限注解、账号类型校验和数据权限模型。
- 内置 IAM/RBAC 模型：账号、身份、角色、部门、用户组、岗位、资源、资源模块和关系表。
- 内置用户中心模型：管理端用户资料、门户端用户资料。
- 内置系统模型：字典、Banner、文件、操作审计日志。
- 内置消息模型：会话、消息、附件、回执、反应、通知、待办、群组和成员关系。
- 数据访问使用 MyBatis-Plus、MyBatis-Plus-Join、动态数据源和 Druid 连接池。
- 支持读写分离语义，默认 `master` 与 `slave` 指向同一数据库。
- JSON 输出使用 `SNAKE_CASE`，统一响应体使用 `ApiResponse`。
- 已接入 Springdoc OpenAPI、Actuator、Micrometer 基础可观测入口。

## 运行要求

后端开发环境：

- JDK 21
- Maven 3.9+
- PostgreSQL
- Redis

可选依赖：

- S3 / MinIO / OSS：对象存储适配预留。
- Prometheus：通过 Actuator 暴露 metrics 时使用。

## 快速启动

### 数据库

默认本地开发连接：

```text
jdbc:postgresql://127.0.0.1:5432/hei_boot
username: hei
password: hei
```

当前 `script/sql/postgres` 只保留初始化脚本约束说明。表结构应从 `hei-fastapi` 的 SQLAlchemy 模型或
Alembic 迁移生成，避免 Java 模型与原型模型出现字段、类型或命名偏差。

### 后端开发

```bash
cd /mnt/e/projects/mine/hei/hei-boot
mvn -pl app/admin -am spring-boot:run
```

默认后端地址为：

```text
http://127.0.0.1:8080
```

常用入口：

```text
/api/v1/internal/health
/swagger-ui/index.html
/v3/api-docs
/actuator/health
```

也可以直接运行主类：

```text
github.jiangbyte.io.BootAdminApplication
```

如果从 IntelliJ IDEA 直接运行，请先刷新 Maven 依赖，确保 `app/admin/target/classes` 中的资源文件
与 `src/main/resources` 保持一致。

## 常用命令

```bash
# 编译全部模块
mvn clean package -DskipTests

# 只运行管理端应用，并自动构建依赖模块
mvn -pl app/admin -am spring-boot:run

# 只编译公共 MyBatis 模块及其依赖
mvn -pl common/common-mybatis -am compile

# 使用 local 配置启动
mvn -pl app/admin -am spring-boot:run -Dspring-boot.run.profiles=local
```

## 配置

配置文件位于 `app/admin/src/main/resources`：

- `application.yml`：通用配置。
- `application-dev.yml`：默认开发环境。
- `application-local.yml`：本机调试环境。
- `application-prod.yml`：生产环境模板。

常用环境变量：

- `SPRING_PROFILES_ACTIVE`：激活配置，默认 `dev`。
- `LOGGING_LEVEL_HEI`：`github.jiangbyte.io` 日志级别。
- `APP_VERSION`：OpenAPI 展示版本。
- `DB_WRITE_URL` / `DB_WRITE_USERNAME` / `DB_WRITE_PASSWORD`：写库连接。
- `DB_READ_URL` / `DB_READ_USERNAME` / `DB_READ_PASSWORD`：读库连接。
- `DB_URL` / `DB_USERNAME` / `DB_PASSWORD`：生产环境通用数据库连接兜底。
- `DB_POOL_INITIAL_SIZE` / `DB_POOL_MIN_IDLE` / `DB_POOL_MAX_ACTIVE`：Druid 连接池容量。
- `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` / `REDIS_DATABASE`：Redis 连接。

默认数据源配置为动态数据源：

```yaml
spring:
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    dynamic:
      primary: master
      strict: true
      datasource:
        master:
          url: ${DB_WRITE_URL:jdbc:postgresql://127.0.0.1:5432/hei_boot}
        slave:
          url: ${DB_READ_URL:${DB_WRITE_URL:jdbc:postgresql://127.0.0.1:5432/hei_boot}}
```

`slave` 默认复用写库连接。需要读写分离时，只要分别配置 `DB_WRITE_*` 和 `DB_READ_*` 即可。
代码中可使用：

```java
@ReadDataSource
public Object query() {
    return null;
}

@WriteDataSource
public void command() {
}
```

## 项目结构

```text
hei-boot
├── app
│   └── admin                  # 可运行的管理端单体应用
├── common
│   ├── common-bom             # 内部模块依赖版本聚合
│   ├── common-core            # 基础响应、分页、异常、ID、枚举
│   ├── common-doc             # OpenAPI 配置
│   ├── common-json            # JSON 能力占位
│   ├── common-log             # 日志能力占位
│   ├── common-mail            # 邮件服务接口
│   ├── common-mybatis         # MyBatis-Plus、MPJ、动态数据源
│   ├── common-observability   # 可观测能力占位
│   ├── common-oss             # 对象存储服务接口
│   ├── common-redis           # Redis / Redisson 依赖入口
│   ├── common-satoken         # Sa-Token 登录上下文
│   ├── common-security        # 权限注解、权限切面、数据权限模型
│   └── common-web             # Web 异常处理、TraceId 过滤器
├── module-api
│   ├── auth-api
│   ├── biz-api
│   ├── iam-api
│   ├── message-api
│   ├── sys-api
│   └── user-api               # 跨模块 API、DTO、事件契约
├── module
│   ├── auth
│   ├── biz
│   ├── iam
│   ├── message
│   ├── sys
│   └── user                   # 业务模块实现和领域模型
└── script
    ├── docker
    └── sql/postgres           # 数据库脚本约束与后续初始化资产
```

## 模型约束

领域模型必须严格对齐 `hei-fastapi/app/modules/**/model.py`：

- 禁止新增 FastAPI 原型中不存在的字段。
- 禁止遗漏 FastAPI 原型中已有的字段。
- 字段类型需要按语义对齐，例如 ID 使用 `String`，时间使用 `OffsetDateTime`。
- JSON 类型使用 `Map<String, Object>` 或 `List<String>` 等结构化类型表达。
- 不额外注入 `deleted`、`version`、`createTime`、`updateTime` 等非原型字段。
- 数据库字段命名、JSON 字段命名保持下划线风格，例如 `created_at`、`account_id`。
- Java 类使用 Lombok 简化样板代码。

## 开发约定

- Maven artifact 不加 `hei-` 前缀，保持 `auth`、`iam`、`common-core` 这类短名称。
- 包名统一使用 `github.jiangbyte.io`。
- 应用放在 `app/` 下，业务模块放在 `module/` 下，插件式能力不使用 `plugin` 命名。
- 对外 DTO、请求体和响应体由 Jackson `SNAKE_CASE` 统一转换。
- 跨模块调用优先依赖 `module-api/*` 中的接口和 DTO。
- Mapper 如需 Join 查询，优先继承 `BaseJoinMapper<T>`。
- 读写分离使用 `@ReadDataSource`、`@WriteDataSource`，默认不强制拆库。

## 代码贡献

欢迎提交 Issue、讨论和 Pull Request。由于当前项目仍在模板与模型迁移阶段，贡献代码时请优先保证
结构稳定和模型一致性。

建议流程：

```bash
git checkout -b feature/your-change
mvn clean package -DskipTests
git commit -m "feat: describe your change"
```

提交 PR 前请确认：

- 领域模型严格对齐 `hei-fastapi/app/modules/**/model.py`，不多字段、不少字段、类型不偏移。
- JSON 对外字段保持 `snake_case`，不要通过手写 `@JsonProperty` 批量制造另一套命名规则。
- 新增模块遵守 `app`、`common`、`module-api`、`module` 的边界。
- 公共能力优先放入 `common/*`，跨模块契约优先放入 `module-api/*`。
- 不引入与 Spring Boot 4、JDK 21、Jakarta 生态不兼容的依赖。
- 数据访问优先使用 MyBatis-Plus、MyBatis-Plus-Join 和现有动态数据源能力。
- 配置项应提供本地开发默认值，生产敏感配置通过环境变量注入。
- README、配置示例和脚本需要随行为变化同步更新。

## 开源协议

本项目使用 [MIT License](LICENSE) 开源协议。

## 参考来源

- [HEI FastAPI](https://github.com/jiangbyte/hei-fastapi)：原型模型、模块边界、API 入口和业务域划分。
- [Snowy](https://gitee.com/xiaonuobase/snowy)：中后台工程结构与通用能力组织方式。
- [RuoYi-Vue-Plus 6.x](https://gitee.com/dromara/RuoYi-Vue-Plus/tree/6.x)：多模块 Maven、动态数据源、MyBatis-Plus 生态组合。