g2rain-spring-boot-starter（通用 Starter）

g2rain-spring-boot-starter 是 聚合父 POM，统一管理版本与构建；实际按需引入的是仓库内多个子模块 Starter（当前 11 个）。项目遵循 Spring Boot 自动配置约定，模块职责单一。

近期重点能力包括：机构 / 部门行级数据隔离（g2rain-starter-mybatis-extensions）、登录态部门路径增强（g2rain-starter-department-principal），与 g2rain-department 及 g2rain-common 的 deptPath 配合使用。

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

子模块一览

模块	ArtifactId	说明
核心防护	g2rain-starter-aegis-core	微服务基础能力聚合与统一依赖
Web 基础设施	g2rain-starter-web-infra	过滤器、拦截器、全局异常与访问日志；提供 PrincipalContextHolder
MyBatis 扩展	g2rain-starter-mybatis-extensions	分页、机构 / 部门数据隔离、@DataIsolation
Redis	g2rain-starter-data-redis	Redis 封装、Redisson 分布式锁等
缓存同步	g2rain-starter-cache-sync	跨实例缓存事件同步
身份客户端	g2rain-starter-identity-client	分布式身份生成
Feign 增强	g2rain-starter-feign-plus	OpenFeign 相关增强
链路追踪	g2rain-starter-tracing-otel	OpenTelemetry 追踪
Stream Redis	g2rain-starter-stream-redis	Spring Cloud Stream + Redis 绑定
SpringDoc	g2rain-starter-spring-doc	OpenAPI 文档公共配置
部门 Principal	g2rain-starter-department-principal	登录态从 g2rain-department 拉取 deptPath 写入 Principal

MyBatis 扩展细节见仓库内 g2rain-starter-mybatis-extensions/README.md。

环境要求

• Java：25+
• Maven：3.6+
• Spring Boot：4.x（父 POM 当前 4.0.5）
• 推荐版本与 Maven Central / 仓库 revision 一致（如 1.0.1）

引入方式（示例）

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.g2rain</groupId>
      <artifactId>g2rain-spring-boot-starter</artifactId>
      <version>1.0.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependency>
  <groupId>com.g2rain</groupId>
  <artifactId>g2rain-starter-aegis-core</artifactId>
  <version>1.0.1</version>
</dependency>

Web 基础设施（示例）

g2rain:
  web:
    enabled: true
    http-wrapper-filter-order: 100
    principal-context-filter-order: 150
    access-log-filter-order: 200
    login-guard-interceptor-order: 300
    identity-param-injector-order: 400

@RestController
public class DemoController {
  @LoginGuard(require = true, anonymous = false)
  @IdentityInject(userIdPropertyName = "userId")
  @GetMapping("/api/demo")
  public Result<String> demo(@RequestParam String param) {
    return Result.success("Hello World");
  }
}

机构 + 部门数据隔离

生效范围（摘要）

• 默认对 租户类型机构 的前台请求生效；后端系统调用（PrincipalContextHolder.isBackEnd()）、运营公司账号（isAdminCompany()）不拦截。
• 仅机构隔离：Mapper 标注 @DataIsolation 且不配置 permissionTableName。
• 机构 + 部门动态权限：配置 permissionTableName，并由 g2rain-department 解析策略（用户维度、dept_path LIKE、分组读/写、Other 规则等）。

最小配置

g2rain:
  data:
    isolation:
      enabled: true
      policy-service-name: g2rain-department
      policy-service-path: data_permission_meta
      policy-resolve-path: /policy_resolve
  principal:
    department:
      enabled: true
      service-name: g2rain-department
      service-path: department_user_relation
      path-business: /principal_enrichment

spring:
  application:
    name: g2rain-order   # 须与 data_permission_model.module_code 一致

Mapper 示例

@DataIsolation(
    permissionTableName = "order",
    userIdColumnName = "owner_user_id",
    deptPathColumnName = "dept_path"
)
@Mapper
public interface OrderMapper {
    List<Order> selectList(OrderQuery query);
}

配套依赖

Starter	作用
g2rain-starter-web-infra	注入 organId / userId 等 Principal
g2rain-starter-department-principal	部门隔离必需：写入 deptPath
g2rain-starter-mybatis-extensions	SQL 改写与策略解析

若 userId 或 deptPath 缺失，策略解析为 null，此时通常仅保留机构隔离。

缓存同步（示例）

g2rain:
  syncer:
    enabled: true
    redis:
      publisher-enabled: true
      subscriber-enabled: true
      publisher-topic: g2rain:events
      subscriber-topics:
        - g2rain:events

常见排障（数据隔离）

现象	排查方向
隔离不生效	是否租户前台请求；@DataIsolation 是否标注；g2rain.data.isolation.enabled
仅有机构隔离、无部门过滤	是否配置 permissionTableName；spring.application.name 是否与 module_code 一致；是否引入 department-principal；Principal 是否有 deptPath
策略不更新	策略结果有本地缓存，变更后需按级别失效或重启

调试：logging.level.com.g2rain.data.isolation: DEBUG

相关文档

• g2rain-common
• g2rain-department
• g2rain-mybatis-extensions（生态侧 MyBatis 能力说明）