{"id":29306528,"url":"https://github.com/eternalstone/sensitivebye","last_synced_at":"2025-07-07T06:13:01.991Z","repository":{"id":192529357,"uuid":"549348203","full_name":"eternalstone/SensitiveBye","owner":"eternalstone","description":"SensitiveBye是一款专注于解决数据脱敏的Java和SpringBoot工具包, 能帮助您快速解决项目中的脱敏需求，支持对象字段，接口字段，数据库字段脱敏，json序列化脱敏，日志打印脱敏、敏感词条脱敏、Spring配置文件脱敏等功能","archived":false,"fork":false,"pushed_at":"2025-06-05T05:03:50.000Z","size":136,"stargazers_count":7,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-05T06:47:42.119Z","etag":null,"topics":["java","spring","springboot2","springmvc"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eternalstone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-10-11T03:41:06.000Z","updated_at":"2025-06-05T05:03:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"de918d45-8640-4acf-af33-d2569c6b98cd","html_url":"https://github.com/eternalstone/SensitiveBye","commit_stats":null,"previous_names":["eternalstone/sensitivebye"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/eternalstone/SensitiveBye","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eternalstone%2FSensitiveBye","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eternalstone%2FSensitiveBye/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eternalstone%2FSensitiveBye/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eternalstone%2FSensitiveBye/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eternalstone","download_url":"https://codeload.github.com/eternalstone/SensitiveBye/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eternalstone%2FSensitiveBye/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264025395,"owners_count":23545693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","spring","springboot2","springmvc"],"created_at":"2025-07-07T06:13:01.004Z","updated_at":"2025-07-07T06:13:01.983Z","avatar_url":"https://github.com/eternalstone.png","language":"Java","readme":"# SensitiveBye\n![MavenCentral](https://img.shields.io/maven-central/v/io.github.eternalstone/sensitivebye-spring-boot-starter?style=flat-square)\n![Hex.pm](https://img.shields.io/hexpm/l/plug.svg?style=flat-square)\n\n\n\n## 1、简介\n\n一款专注于解决数据脱敏的Java工具包, 能帮助您快速解决项目中的脱敏需求，支持对接口字段、java对象字段和json序列化字段脱敏；常见日志框架(logback,log4j2)输出内容脱敏；基于mybatis拦截器实现的数据库脱敏；敏感词条、Spring配置文件等内容进行自定义格式数据脱敏，使用简单方便、易于扩展。[详细开发文档](https://gitee.com/eternalstone/SensitiveBye/wikis)\n\n\n\n---\n\n\n\n## 2、功能概述\n\n1. java版本基准：jdk1.8\n\n2. 支持Restful接口字段脱敏，java对象字段脱敏，支持jackson和fastjson序列化字段脱敏\n\n3. 支持基于mybatis的数据库字段加解密脱敏\n\n4. 支持常用日志框架输出脱敏，例如logback，log4j2\n\n5. 支持SpringBoot配置文件配置项脱敏\n\n6. 内置基于[ AhoCorasickDoubleArrayTrie ](https://github.com/hankcs/AhoCorasickDoubleArrayTrie)实现的敏感词库 \n\n   \n---\n\n\n\n\n\n## 3、使用\n\n#### 3.1 导入 \n\n##### 3.1.1 SpringBoot项目导入\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.eternalstone\u003c/groupId\u003e\n  \u003cartifactId\u003esensitivebye-spring-boot-starter\u003c/artifactId\u003e\n  \u003cversion\u003e1.0.7\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\n\n##### 3.1.2 SpringMVC或其他java项目带入\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.eternalstone\u003c/groupId\u003e\n  \u003cartifactId\u003esensitivebye-core\u003c/artifactId\u003e\n  \u003cversion\u003e1.0.7\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\u003e ​\t包导不下来需要添加以下maven中央仓库：\n\u003e\n\u003e ```xml\n\u003e \u003crepositories\u003e\n\u003e    \u003crepository\u003e\n\u003e       \u003cid\u003emaven-central\u003c/id\u003e\n\u003e       \u003cname\u003eCentral Repository\u003c/name\u003e\n\u003e       \u003curl\u003ehttps://repo1.maven.apache.org/maven2\u003c/url\u003e\n\u003e    \u003c/repository\u003e\n\u003e \u003c/repositories\u003e\n\u003e ```\n\n\n\n#### 3.2 配置\n\n​\t\t在SpringBoot项目中，在`Application`启动类上面加入`@EnableGlobalSensitiveBye`注解用来开启SensitiveBye自动装配。`@EnableGlobalSensitiveBye`注解可视为SensitiveBye所有功能是否生效的\u003cfont style=\"red\"\u003e总开关\u003c/font\u003e。\n\n```java\n@EnableGlobalSensitiveBye\n@SpringBootApplication\npublic class Application {\n\n    public static void main(String[] args) {\n        SpringApplication.run(Application.class, args);\n    }\n\n}\n```\n\n​\t\tSensitiveBye集成了以下配置\n\n~~~yaml\nsensitive-bye:\n  field:\n    enabled: true #默认为true, 开启字段脱敏开关\n  log:\n    enabled: false #默认为false, 开启日志脱敏开关\n  mybatis:\n    enabled: false #默认为false, 开启mybatis数据库脱敏开关\n~~~\n\n\u003e ​\t当开启对应开关时，需要导入相关的依赖，例如，开启log开关需要依赖logback或者log4j2相关的maven坐标，开启mybatis开关需要依赖mybatis或者基于mybatis开发的框架的maven坐标。\n\n\n\n#### 3.3 字段脱敏\n\n​\t\t`SensitiveBye`字段脱敏的组件是`SensitiveFieldProvider`，SpringBoot引入starter包配合@EnableGlobalSensitiveBye注解将此组件自动注入，其他java项目引入core包则需要初始化此组件：\n\n```java\n@Bean\npublic SensitiveFieldProvider sensitiveFieldProvider(){\n    return SensitiveFieldProvider.instance();\n}\n```\n\n​\t\t在需要脱敏java对象字段上注解`@SensitiveBye`，填入对应的脱敏规则即可：\n\n```java\n@SensitiveBye(strategy = SensitiveType.MOBILE)\nprivate String mobile;\n```\n\n##### 3.3.1 接口字段脱敏\n\n​\t\tSpringMVC的接口序列化是基于jackson实现的，SensitiveBye已完成对jackson序列化的脱敏，所有进行以上配置后接口字段即可自动脱敏。\n\n\n\n##### 3.3.2 json序列化脱敏\n\n- jackson序列化脱敏\n\n  ```java\n  ObjectMapper mapper = new ObjectMapper();\n  LOGGER.info(\"jackson序列化脱敏:{}\", mapper.writeValueAsString(user));\n  ```\n\n- fastjson序列化脱敏\n\n  ```java\n   //fastjson序列化, 需要添加一个fastjson的值过滤器，SensitiveBye已经内置实现了SensitiveByeFilter\n  LOGGER.info(\"fastjson序列化脱敏:{}\", JSONObject.toJSONString(user, SensitiveByeFilter.instance()));\t\n  ```\n\n\n\n##### 3.3.3 java对象脱敏\n\n```java\nSensitiveFieldProvider.instance().handle(SensitiveType.MOBILE, \"13100001111\", \"*\")\n```\n\n\n\n##### 3.3.4 自定义字段脱敏策略\n\n​\t\tSpring项目的自定义字段脱敏策略可以直接Bean一个CustomeFieldStrategy对象：\n\n```java\n@Bean\npublic CustomeFieldStrategy customeFieldStrategy(){\n    CustomeFieldStrategy strategy = new CustomeFieldStrategy();\n    //自定义策略key=test, var1表示原始值，var2表示脱敏符号, 后面的表达式即是自定义脱敏逻辑\n    strategy.add(\"test\", (var1, var2)-\u003e var1.concat(var2));\n    return strategy;\n}\n```\n\n​\t\t其他java项目需要给SensitiveFieldProvider设置自定义策略：\n\n```java\nCustomeFieldStrategy strategy = new CustomeFieldStrategy();\nstrategy.add(\"test\", (var1, var2)-\u003e var1.concat(var2));\nSensitiveFieldProvider instance = SensitiveFieldProvider.instance();\ninstance.setCustomeStrategy(strategy);\n```\n\n​\t\t添加的'test'自定义策略直接在注解中使用即可：@SensitiveBye(\"test\")\n\n\n\n#### 3.4 日志脱敏\n\n​\t\t`SensitiveBye`日志脱敏的组件是`SensitiveLogProvider`，SpringBoot项目配置`sensitive-bye.log.enabled=true`自动注入此组件，其他java项目需要初始化此组件：\n\n```java\n@Bean\npublic SensitiveLogProvider sensitiveFieldProvider(){\n    SensitiveLogProvider sensitiveLogProvider = SensitiveLogProvider.instance();\n    //如果存在自定义策略,可以设置一个SensitiveRule对象\n    sensitiveLogProvider.setSensitiveRule();\n    return sensitiveLogProvider\n}\n```\n\n##### 3.4.1 logback日志脱敏\n\n​\t\t在logback.xml中添加如下配置即可：\n\n```xml\n\u003cconversionRule conversionWord=\"msg\" converterClass =\"LogbackSensitiveConverter\"/\u003e\n```\n\n\n\n##### 3.4.2 log4j2日志脱敏\n\n​\t\t在log4j2-spring.xml中，原日志内容格式为 %msg，需要将其替换为%sdmsg。例如：\n\n```xml\n\u003cappenders\u003e\n  \u003cconsole name=\"STDOUT\" target=\"SYSTEM_OUT\"\u003e\n    \u003cpatternLayout pattern=\"%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level ---- [%thread] %logger Line:%-3L - %sdmsg%n\" /\u003e\n  \u003c/console\u003e\n\u003c/appenders\u003e\n```\n\n\n\n##### 3.4.3 自定义日志脱敏规则\n\n​\t\tSensitiveBye集成的默认日志脱敏规则见枚举类：LoggerRule。\n\n​\t\t如需添加或删除或自定义脱敏规则，实现`ISensitiveLogRule`接口的`custome(Map\u003cString, SensitiveLogRuleWrapper\u003e ruleMap)`方法即可，例如：\n\n```java\n@Component\npublic class CustomeLogRule implements ISensitiveLogRule {\n  @Override\n  public void custome(Map\u003cString, SensitiveLogRuleWrapper\u003e ruleMap) {\n    SensitiveLogRuleWrapper wrapper = new SensitiveLogRuleWrapper();\n    //规则名称\n    wrapper.setName(\"wechat\");\n    //规则前缀匹配词\n    wrapper.setKeys(new HashSet\u003cString\u003e(){{\n      add(\"微信\");\n      add(\"wechat\");\n    }});\n    //规则匹配词与匹配值之间的分隔符\n    wrapper.setSeparators(new HashSet\u003cString\u003e(){{\n      add(\"=\");\n      add(\":\");\n      add(\"\\\\[\");\n    }});\n    //正则表达式\n    wrapper.setPattern(Pattern.compile(\"([a-zA-Z]{1})([-_a-zA-Z0-9]{5,19}+$)\"));\n    //替换表达式，注意需要带上匹配词和分隔符的占位符 $1表示keys, $2表示分隔符，后续就是对内容的拆分和替换\n    wrapper.setReplacement(\"$1$2$3*******\");\n    //新增规则\n    ruleMap.put(wrapper.getName(), wrapper);\n    //或者移除默认规则\n    ruleMap.remove(LoggerRule.BANK_CARD.name().toLowerCase());\n  }\n}\n```\n\n\n\n\n\n#### 3.5 基于mybatis拦截器的数据库字段脱敏\n\n​\t\t`SensitiveBye`的mybatis脱敏组件是`MybatisSensitiveInterceptor`，它是基于Mybatis拦截器实现的。SpringBoot项目配置`sensitive-bye.mybatis.enabled=true`自动注入此组件，其他java项目需要初始化此组件：\n\n```java\n@Configuration\npublic class MybatisConfig {\n  @Bean\n  public ConfigurationCustomizer mybatisConfigurationCustomizer() {\n    return new ConfigurationCustomizer() {\n      @Override\n      public void customize(Configuration configuration) {\n        configuration.addInterceptor(new MybatisInterceptor());\n      }\n    };\n  }\n}\n```\n\n\u003e 注：通过@Bean将mybatis拦截器加载到spring容器可能在不同环境下会失效，这里稳妥的做法是将拦截器添加到mybatis拦截器配置中\n\n​\t\tmybatis数据库字段脱敏用到了两个核心注解`@EnableCipher`和`@CipherField`:\n\n```java\n//@EnableCipher作用于Mapper接口的方法上，标注入参是加密还是解密，返回值是加密还是解密\n@Mapper\npublic interface UserMapper {\n    @EnableCipher(parameter = CipherType.ENCRYPT)\n    int insertAndReturnId(User user);\n    \n    @EnableCipher(result = CipherType.DECRYPT)\n    User selectById(@Param(\"id\") Integer id);\n}\n\n//@CipherField作用于对象字段上，标注此字段需要加解密，并且指定加解密算法,加解密算法需要实现ICipherAlgorithm接口\npublic class User\n    @CipherField(PasswordAlgorithm.class)\n    private String password;\n\t@CipherField(MobileAlgorithm.class)\n    private String mobile;\n}\n```\n\n\u003e  ​\t1.@SensitiveBye注解和@CipherField注解虽然都是标注在对象属性上的，但是两个注解的作用互不影响，可以叠加使用，例如手机号从数据库密文查出来解密成明文，再用@SensitiveBye(strategy = SensitiveType.MOBILE)将明文手机号打上掩码。\n\n\u003e ​\t2.如果项目中存在多个Mybatis拦截器，需要指定拦截器的执行顺序，可以写个配置类以此添加：\n\n```java\n@Configuration\npublic class MybatisConfig {\n    @Bean\n    public ConfigurationCustomizer mybatisConfigurationCustomizer() {\n       return new ConfigurationCustomizer() {\n           @Override\n           public void customize(Configuration configuration) {\n                configuration.addInterceptor(new MybatisInterceptor());\n           }\n       };\n    }\n}\n```\n\n\n\n#### 3.6 其他工具使用\n\n##### 3.6.1 敏感词库组件\n\n​\t\t`SensitiveBye`的敏感词组件是`SensitiveWordProvider`，默认不自动注入，需要使用的时候初始化即可：\n\n```java\n@Bean\npublic SensitiveWordProvider sensitiveWordProvider(){\n    return new SensitiveWordProvider();\n}\n```\n\n​\t\tSensitiveWordProvider提供了一个有参构造器，用于以不同的方式获取词库，SensitiveBye内置了两种方式：\n\n- SensitiveWordSourceFromResource (获取resource目录下的sensitive.txt文件, 可自定义文件名)\n- SensitiveWordSourceFromUrl(传入一个url，从网络获取词库文件)\n\n​\t\t你可以通过实现`ISensitiveWordSource`接口的loadSource()自定义获取词库的方式。\n\n​\t\tSensitiveWordProvider提供了三个方法：\n\n```java\n//handle方法用于将传入的字符串中的敏感词替换成输入的符号\nString handle(String word, String symbol);\n//contain方法用于检测传入的字符串中包含的敏感词组\nList\u003cString\u003e contain(String word);\n//reload方法用于重新载入词库\nvoid reload();\n```\n\n\n\n##### 3.6.2 SpringBoot配置文件静态脱敏工具类\n\n​\t\t`SensitiveBye`实现了对SpringBoot的配置文件相关的配置项进行打掩码的工具`SensitiveFileUtil`， 支持对yml, yaml, properties三种配置文件，它提供了以下几个方法：\n\n```java\n//将source路径的配置文件进行配置项脱敏后输出到target目录\npublic static void sensitiveByeToFile(String source, String target);\n\n//将source路径的配置文件进行配置项脱敏后输出到target目录,可传入handler自定义实现对配置项自定义操作\npublic static void sensitiveByeToFile(String source, String target, IFileHandler handler);\n\n//将source路径的配置文件进行配置项脱敏后输出成字符串\npublic static String sensitiveByeToString(String source);\n\n//将source路径的配置文件进行配置项脱敏后输出成字符串，可传入handler自定义实现对配置项自定义操作\npublic static String sensitiveByeToString(String source, IFileHandler handler);\n\n```\n\n​\t\tSensitiveFileUtil对配置项脱敏的处理器是`SensitiveFileHandler`，它是默认的实现，你可以继承`AbstractFileHandler`类实现doFilter()对配置项进行操作：\n\n```java\npublic class SensitiveCustomeFilterHandler extends AbstractFileHandler {\n    @Override\n    public void doFilter(LinkedHashMap\u003cString, Object\u003e param) {\n        //删除test配置项\n        param.remove(\"test\");\n    }\n}\n\n```\n\n​\t\t你可以将自定义的handler加入SensitiveFileHandler的后续执行链中，也可以直接传递自定义handler跳过SensitiveBye的SensitiveFileHandler的实现\n\n```java\nSensitiveFileHandler handler = new SensitiveFileHandler();\nhandler.setNextHandler(new SensitiveCustomeFilterHandler());\nString s2 = SensitiveFileUtil.sensitiveByeToString(source, handler);\n```\n\n\n\n​\t\t\n\n---\n\n\n\n## 4.引文\n\nhttps://pagehelper.github.io/docs/interceptor/\n\n\n\n---\n\n## 联系方式\n1. 邮箱联系： senstivebye@163.com，欢迎通过此邮件讨论与SensitiveBye相关的一切。","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feternalstone%2Fsensitivebye","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feternalstone%2Fsensitivebye","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feternalstone%2Fsensitivebye/lists"}