# java-framework

**Repository Path**: headtea/java-framework

## Basic Information

- **Project Name**: java-framework
- **Description**: java项目框架
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 頭茗 java-framework

> 一套面向国内企业交付场景的 Spring Boot starter 组合拳：统一响应、多租户、数据权限、认证、字典、操作日志、Redis 缓存与分布式锁，零配置接线。

**状态：`0.1.0` 已发布**（Central 坐标 `io.gitee.headtea`），主干跑 `0.2.0-SNAPSHOT`（时间口径改造 + Redis starter）。分期与破坏性变更见 [CHANGELOG](CHANGELOG.md)。

## 它解决什么问题

单点能力已有强者（mybatis-plus、sa-token、hutool），但每个交付项目仍要重新做同一套整合：
统一响应体与错误码、租户上下文贯穿 SQL、数据权限与接口权限联动、字典缓存、操作日志落库。
本框架把这些整合做成**开箱即用的 starter**，每个都能独立使用，也可以一键全引。

## 模块一览

| 模块 | 作用 |
|---|---|
| `headtea-dependencies` | BOM：本框架构件与三方基线（Spring Boot / MyBatis-Plus / sa-token / Redisson）的统一版本矩阵 |
| `headtea-core` | 纯契约：统一响应体 `R<T>`、错误码 SPI、业务异常。零三方依赖、无自动配置 |
| `headtea-web-spring-boot-starter` | Web 基座：全局异常、统一响应渲染、错误码 i18n、traceId |
| `headtea-mybatis-spring-boot-starter` | 数据层：行级多租户（隔离策略 SPI）、数据权限、分页、审计字段自动填充 |
| `headtea-auth-spring-boot-starter` | 认证：sa-token 整合层，多端登录、在线用户、接口权限、错误码联动 |
| `headtea-system-spring-boot-starter` | 系统件：字典、系统参数（TTL 本地缓存）、注解式操作日志（存储 SPI） |
| `headtea-redis-spring-boot-starter` | Redis：`RedisUtil` 静态入口（免注入）、每个键自动带项目命名空间、分布式锁。**不在聚合 starter 里**，需单独引 |
| `headtea-spring-boot-starter` | 聚合 starter：一个依赖引入全部，并桥接登录态 → 操作人上下文 |
| `examples/headtea-examples-app` | 可运行 demo（不发版），同时作为真实消费方接入示例 |

## 版本矩阵

| 项 | 版本 |
|---|---|
| 构建 / CI JDK | 25（字节码目标 `release=17`） |
| Spring Boot | 4.1.2 |
| Spring Cloud（对齐列车，v1 不引入） | 2025.1.4 |
| MyBatis-Plus | 3.5.18.1（`mybatis-plus-spring-boot4-starter`） |
| sa-token | 1.46.0（`sa-token-spring-boot4-starter`） |
| Redisson | 4.8.0（`redisson-spring-boot-starter`，仅 redis starter） |

## 快速开始

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.gitee.headtea</groupId>
            <artifactId>headtea-dependencies</artifactId>
            <version>0.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.gitee.headtea</groupId>
        <artifactId>headtea-spring-boot-starter</artifactId>
    </dependency>
    <!-- Redis 是可选基础设施，聚合 starter 不带它。该构件从 0.2.0 起发布，
         用 0.1.0 BOM 还引不到，先把上面 BOM 的版本换成 0.2.0。 -->
    <dependency>
        <groupId>io.gitee.headtea</groupId>
        <artifactId>headtea-redis-spring-boot-starter</artifactId>
    </dependency>
</dependencies>
```

跑 demo：

```bash
mvn -q clean verify          # 全仓构建 + 校验
cd examples/headtea-examples-app && mvn spring-boot:run
```

## 文档

文档站（VitePress）位于 `docs/`：`guide/` 讲能力（统一响应、多租户与数据权限、多端认证、字典·参数·操作日志、Redis 缓存与分布式锁、版本矩阵），`ai-conventions/` 是给 AI 编程助手的接入 recipe——每个 starter 一份，写清配置键、扩展点与禁止事项。

```bash
npm --prefix docs install && npm --prefix docs run dev     # 本地预览
npm --prefix docs run build                               # 构建静态站点
```

接入前最值得先看的六件事都在文档里：如何看到 MyBatis-Plus 实际下发的 SQL、字典的三层结构与 JSON 键名、操作日志「写入按租户隔离、读取不隔离」这条边界、统一响应 `R` 含 `success` 的真实形状、时间一律用 epoch 毫秒（展示时区走 `X-Time-Zone`），以及 Redis 键的命名空间（默认 `spring.application.name`，装在 Redisson 的 `Config` 上所以绕不过去）与「值里不写 `@class`、读侧显式给类型」这套编解码口径。

聚合 starter `headtea-spring-boot-starter` 除了一键引入，还承担唯一一处跨 starter 的接线：把 sa-token 登录态回填 `OperatorContext`，让 `@OperationLog` 采到操作人（默认开启，`headtea.starter.operator-context.enabled=false` 可关）。

## 参与贡献

见 [CONTRIBUTING.md](CONTRIBUTING.md)。构建需 JDK 17+（推荐 25）与 Maven 3.9+。
用 AI 助手改这个仓库时，[AGENTS.md](AGENTS.md) 是它会读到的根规则。

## 许可证

[Apache License 2.0](LICENSE)