# g2rain-common（公共基础类）

g2rain-common 是企业级 Java 基础工具库，面向分布式系统开发提供核心组件与实用工具集合，重点覆盖：统一异常、Web 会话管理、通用数据模型、JSON 编解码增强、事件同步等。

近期版本在 Web 会话 / Principal 中补充了 用户部门路径（deptPath） 能力，与部门服务及 Starter 数据权限链路对齐。

源码仓库：github.com/g2rain/g2rain-common (opens new window)

# 核心特性

事件同步与消息分发（分布式事件处理、消息存储管理、基于 ScopedValue 的线程安全上下文）
JSON 处理增强（高精度序列化、RawNumberDeserializer 避免精度丢失、可配置 JsonCodecBuilder）
统一异常处理（BusinessException / BaseError / FieldError、ErrorCode 错误码规范、国际化错误消息）
Web 会话管理（多身份类型：USER、PASSPORT、APP、APP_TENANT 等；Token JWT + DPoP JWT 封装）
部门上下文（与数据权限联动）
- PrincipalContext / PrincipalContextHolder 支持 deptPath（用户所属部门路径，可为逗号分隔多路径）
- PrincipalHeaders.DEPT_PATH（X-DEPT-PATH）用于网关 / Feign 透传
- PrincipalContext.getHeaders() 在 deptPath 非空时自动加入对应请求头
通用数据模型（Result 统一响应、PageData 分页结构、BasePo 持久化基类、DTO/VO 基类）
实用工具集（字符串/集合/常量工具类、ID 生成接口等）

# 环境要求

Java：25+
Maven：3.6+

# Maven 依赖

<dependency>
  <groupId>com.g2rain</groupId>
  <artifactId>g2rain-common</artifactId>
  <version>1.0.1</version>
</dependency>

# 基本使用示例

# JSON 编解码

JsonCodec codec = JsonCodecFactory.instance();
String json = codec.obj2str(myObject);
MyObject obj = codec.str2obj(json, MyObject.class);

# 统一响应

Result<User> result = Result.success(user);
Result<PageData<User>> pageResult = Result.successPage(1, 10, 100, users);
Result<Void> errorResult = Result.error("USER_NOT_FOUND", "用户不存在", userId);

# 部门路径（会话上下文）

登录链路经 g2rain-starter-department-principal 从 g2rain-department 拉取并写入后，业务代码可读：

String deptPath = PrincipalContextHolder.getDeptPath();
// 下游 Feign 调用时 PrincipalContext.getHeaders() 会携带 X-DEPT-PATH

# 与部门 / 数据权限的关系

组件	作用
`g2rain-department`	维护部门、用户关系及权限策略元数据
`g2rain-starter-department-principal`	登录后填充 `deptPath`
`g2rain-starter-mybatis-extensions`	读取 `organId` / `userId` / `deptPath` 解析策略并改写 SQL

资源驱动的前端菜单权限（g2rain-basis）与上述 行级数据权限 互补，详见资源与权限与 g2rain-department。