Guide to Using easy-data-scope for Dynamic SQL Data Permissions in Spring Boot

Introduction

easy-data-scope is a data‑permission project that implements dynamic SQL injection. It supports MyBatis, MyBatis‑plus and MyBatis‑flex, and can be used simply by adding annotations without complex configuration.

Basic Project Setup

1. Database

A simple user table is created, and the following permission rules will be applied:

Only view records with id = 1

Only view records with age = 111

Only view records with age = 222

View records with age = 111 OR age = 222

2. Import Basic Dependencies (MyBatis‑plus, MyBatis XML demo)

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
        <version>2.2.1.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <version>2.2.1.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-boot-starter</artifactId>
        <version>3.3.0</version>
    </dependency>
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <version>8.0.33</version>
    </dependency>
</dependencies>

3. Core Dependency

<dependency>
    <groupId>cn.zlinchuan</groupId>
    <artifactId>ds-mybatis</artifactId>
    <version>1.0.1</version>
</dependency>

4. Main Application Class

@SpringBootApplication
public class Main {
    public static void main(String[] args) {
        SpringApplication.run(Main.class);
    }
}

5. Omit Mapper and Service Implementation

6. application.yml

server:
  port: 8001
# DataSource Config
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: url
    username: name
    password: password
mybatis:
  mapper-locations: classpath:mapper/*.xml
# XML mapping file path
mybatis-plus:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

7. Test

@Autowired
private UserService userService;

@Test
public void test() {
    userService.getAll().forEach(System.out::println);
}

Using easy-data-scope

Implement the core interface DataScopeFindRule and let Spring manage it.

easy-data-scope will proxy methods annotated with @DataScope and call
find()
to obtain a list of
DataScopeInfo
objects, which are then used to build the SQL.

DataScopeInfo Introduction

The easy-data-scope component builds SQL based on the DataScopeInfo list returned by DataScopeFindRule.find() .

@DataScope Annotation

Place the annotation on methods that require data‑permission interception. It defines the permission keys, optional SQL template, merge behavior, logical operator and flag.

public @interface DataScope {
    /** Keys used to retrieve permission entities */
    String[] keys();
    /** Optional template for multiple keys */
    String template() default "";
    /** Whether to merge permissions with the same column/operator */
    boolean merge() default false;
    /** Logical operator (WHERE, AND, OR) */
    String logical() default SqlConsts.AND;
    /** Whether to enable the data‑scope flag placeholder */
    boolean flag() default false;
}

Creating the Permission Table

CREATE TABLE auth_datascope (
    id INT AUTO_INCREMENT COMMENT '编号' PRIMARY KEY,
    datascope_key VARCHAR(200) NULL COMMENT '数据权限标识',
    datascope_name VARCHAR(200) NULL COMMENT '数据权限名称',
    datascope_tb_name VARCHAR(500) NULL COMMENT '数据权限表别名',
    datascope_col_name VARCHAR(500) NULL COMMENT '数据权限字段名',
    datascope_op_name VARCHAR(10) NULL COMMENT '数据权限操作符',
    datascope_sql VARCHAR(5000) NULL COMMENT '数据权限SQL',
    datascope_value VARCHAR(200) NULL COMMENT '数据权限值',
    datascope_sort INT NULL COMMENT '数据权限排序',
    datascope_des VARCHAR(500) NULL COMMENT '数据权限描述'
) COMMENT '数据权限表';

Permission Scenarios

1. Only view Id = 1

@DataScope(keys = "USER_LIST_ID", logical = SqlConsts.WHERE)
public List
getAll(){
    return userMapper.selectList(null);
}
// Generated SQL: SELECT id, username, age FROM user WHERE (user.id = 1)

2. Only view Age = 111

@DataScope(keys = "USER_LIST_AGE111", logical = SqlConsts.WHERE)
public List
getAll2(){
    return userMapper.selectList(null);
}
// Generated SQL: SELECT id, username, age FROM user WHERE (user.age = 111)

3. Only view Age = 222

@DataScope(keys = "USER_LIST_AGE222", logical = SqlConsts.WHERE)
public List
getAll3(){
    return userMapper.selectList(null);
}
// Generated SQL: SELECT id, username, age FROM user WHERE (user.age = 222)

4. View Age = 111 OR 222 (merge = true)

@DataScope(keys = {"USER_LIST_AGE111", "USER_LIST_AGE222"}, merge = true, logical = SqlConsts.WHERE)
public List
getAll4(){
    return userMapper.selectList(null);
}
// Generated SQL: SELECT id, username, age FROM user WHERE (user.age IN (111, 222))

Additional Features

@DataScope.flag

When flag = true , the placeholder {{_DATA_SCOPE_FLAG}} is inserted into MyBatis XML and will be replaced at runtime.

@DataScope(keys = {"USER_LIST_AGE111", "USER_LIST_AGE222"}, flag = true)
List
getAll5();
select * from (select * from user {{_DATA_SCOPE_FLAG}}) t where 1 = 1

@DataScope.template

Custom SQL templates can be defined with placeholders for each key.

@DataScope(keys = {"USER_LIST_AGE111", "USER_LIST_AGE222"}, flag = true, template = "{{USER_LIST_AGE111}} OR {{USER_LIST_AGE222}}")
List
getAll6();
select * from (select * from user {{_DATA_SCOPE_FLAG}}) t where 1 = 1

Project Source Code

Repository: https://github.com/zoulinchuan/easy-data-scope