开发工具可观测性后端【免费下载链接】vjtoolsThe vip.coms java coding standard, libraries and tools项目地址https://gitcode.com/gh_mirrors/vj/vjtools点击查看免费下载VJKit 是唯品会开源 Java 开发基础类库位于 vjkit它提炼了 Guava、Apache Commons 等主流类库的常用 API并移植了 Netty、ElasticSearch、Facebook JCommon 等项目的精华实现让开发者避免底层代码的重复开发默认即拥有最佳实践。本文将以 VJKit 官方文档为主线结合仓库源码完整讲解如何引入依赖、认识模块体系并深入实战演示其日志脱敏vjmask组件的配置与使用读完即可在业务项目中落地这套类库。一、VJKit 的定位与设计理念VJKit 的定位是综合各门各派众多开源类库的精华而成的 Java 基础类库核心价值在于两点让开发人员避免底层代码的重复开发开箱即用地获得经过验证的实现默认就拥有最佳实践尤其是在性能方面。针对基础、文本、数字、日期、文件、集合、并发、反射、日志脱敏这些开发人员的日常高频场景VJKit 主要做了两件事提炼归类对 Guava。借鉴移植移植了各门各派的精华实现包括大项目附送的基础库Netty、ElasticSearch专业基础库Jodd、commons-io、commons-collections大厂基础库Facebook JCommon、twitter commons。二、模块全景按日常场景组织的类库体系从源码结构看源码目录VJKit 的包划分与文档宣称的日常场景一一对应可以推断这是作者刻意按开发者的使用习惯组织的场景包路径代表类基础basebaseBooleanUtil、ObjectUtil、ExceptionUtil、Platforms集合collectioncollectionListUtil、MapUtil、QueueUtil以及高性能原始类型 Mapcollection/type/primitive并发concurrentconcurrentThreadPoolBuilder、Concurrents、RateLimiterUtil日志脱敏datamaskingdatamaskingDataMask、SensitiveType、MaskMappingIDididIdUtilIOioioFileUtil、FilePathUtil、ResourceUtil日志loggingloggingPerformanceUtil映射mappermapperBeanMapper、JsonMapper、XmlMapper网络netnetIPUtil、NetUtil数字numbernumberNumberUtil、MoneyUtil、RandomUtil反射reflectreflectReflectionUtil、ClassUtil、AnnotationUtil安全securitysecurityCryptoUtil文本texttextMoreStringUtil、EncodeUtil、EscapeUtil时间timetimeDateUtil、DateFormatUtil、ClockUtil官方文档建议具体使用方式请直接在 IDE 中阅读 JavaDoc并结合对应的单元测试写法理解。仓库在 vjkit/src/test 下为每个模块都配套了完整的测试用例如 DataMaskTest、DateUtilTest这是学习每个工具类用法的最佳入口。三、Maven 引入与依赖清单3.1 Maven 坐标在pom.xml中引入如下依赖即可使用 VJKitdependency groupIdcom.vip.vjtools/groupId artifactIdvjkit/artifactId version1.0.8/version /dependency说明官方 README 中标注的发布版本为 1.0.8仓库当前 pom.xml 中版本为1.0.9-SNAPSHOT属于开发快照版本。建议在业务项目中以 Maven Central 实际发布的稳定版本号为准。3.2 运行环境要求JDK 7.0 及以上版本。pom.xml中编译级别配置为java.version1.7maven.compiler.source与maven.compiler.target均为 1.7并在jdk9profile 中为 JDK 9 环境的XmlMapper测试额外配置了--add-modules java.xml.bind参数说明类库在 JDK 7 到 JDK 9 的环境中均可工作。3.3 依赖清单项目版本是否可选Guava20.0必选Apache Commons Lang3.7仓库 pom 实际为 3.8.1必选Slf4j1.7.25必选Dozer5.5.1Optional仅供 BeanMapper 使用在 pom.xml 中除了 Guava、commons-lang3、slf4j-api 三个必选依赖外还有一组optionaltrue/optional的可选依赖按需在业务项目中自行引入net.sf.dozer:dozer可选供 BeanMapper 使用com.fasterxml.jackson.core:jackson-databind2.9.10.4可选供 JsonMapper 使用com.alibaba:fastjson1.2.70可选供 DataMask日志脱敏的 JSON 序列化使用ch.qos.logback:logback-classic可选供测试与日志场景使用。仓库注释明确写到尽量少的引入依赖包方便单独重用本模块因此 VJKit 将上述重依赖全部声明为 optional业务项目只有真正用到对应功能时才需要自行引入。例如要用日志脱敏的DataMask.toJSONString()就必须在自己的项目中额外加入 fastjson 依赖详见下文。3.4 测试依赖测试阶段还使用了 JUnit 4.12、AssertJ 2.6.0、Mockito 2.18.3以及仅供 XmlMapper 测试使用的 dom4j、jaxen 和 jsonassert这些均为testscope不会进入业务项目的传递依赖。四、实战核心日志脱敏组件 vjmask日志脱敏vjmask是唯品会日志脱敏组件在业务中广泛使用也是 VJKit 文档单独开篇详解的功能。它的设计目标是基于性能和通用性考虑让使用方用最少的配置和代码轻松实现敏感信息过滤。官方完整文档见 日志脱敏。4.1 依赖引入在引入 vjkit 主依赖见 3.1 节的同时因为序列化脱敏基于 fastjson 实现需要在业务项目 pom 中额外引入dependency groupIdcom.alibaba/groupId artifactIdfastjson/artifactId version1.2.70/version /dependency4.2 最佳实践三种脱敏用法脱敏组件支持对单个字符串进行脱敏也支持toJSON和toString的序列化脱敏import com.vip.vjtools.vjkit.datamasking.DataMask; // 单个字符串按中文姓名规则脱敏 logger.info(some sensitive info:{}, DataMask.mask(name, SensitiveType.Name)); // 单个字符串按默认方式脱敏结果为 t***; logger.info(some sensitive info:{}, DataMask.mask(test)); // 对象json序列化脱敏 logger.info(some sensitive object:{}, DataMask.toJSONString(obj)); // 对象toString序列化脱敏 logger.info(some sensitive object:{}, DataMask.toString(obj));从 DataMask 源码 可以看到其内部实现mask(String source)调用默认的SensitiveType.Default策略只显示第一个字符mask(String source, SensitiveType type)委托给对应枚举类型的MaskStrategy执行异常时回退返回原字符串保证日志打印不中断toJSONString(Object object)通过JSON.toJSONString(object, jsonFilter)传入 DataMaskJsonFilterfastjson 的ContextValueFilter在序列化过程中逐字段脱敏失败时降级为普通 JSON 输出toString(Object object)先做脱敏 JSON 序列化再JSON.parseObject反序列化后调用对象的toString()因此字段较多的场景下性能比 toJSON 差官方建议优先使用 toJSON。对类的序列化脱敏先要对相关敏感字段标记Sensitive支持字符串类型的字段包括String、String[]和CollectionString嵌套类的敏感字段也能被识别public class User{ Sensitive(type SensitiveType.Phone) // type 参考 4.3 节脱敏规则表 private String phone; }4.3 内置脱敏规则一览VJKit 已定义并实现了常用脱敏类型可直接使用。这些类型定义在 SensitiveType 枚举 中敏感信息脱敏要求样例SensitiveType中文姓名三个字及以下只显示最后一个字三个字以上显示最后两个字*明****小明Name手机号/固定电话只显示前三后三138*****111Phone身份证号显示前五个和后二个字符44010************58IDCard银行卡号显示前四个和后二个字符6228************89BankCard地址保留前9个字符广东省广州市荔湾区******Address电子邮箱只显示前一后一及和后面的内容a***babc.comEmail验证码只显示前一后一a**bCaptcha护照/军官号只显示前二后二EI****64Passport账号只显示前一后一a****bAccount密码不显示任意字符*********Password散列sha1(sourcesalt)可以通过DataMask.setSalt设置 salt用于希望在日志系统中精确找回这条日志的场景6b76e070c5b5d1b889295506faa8b98e97da7e87Hash从源码可确认各类型的实现细节PartMask部分掩码通用策略支持前后各保留 n 个字符SensitiveType中通过构造参数注入例如Phone(new PartMask(), 3)、IDCard(new PartMask(), 5, 2)。实现上预生成了 1~10 个*的掩码串缓存见 PartMask当保留位数越界时回退为只保留第一位的默认规则NameMask姓名掩码长度小于等于 3 显示最后一位大于 3 显示最后两位见 NameMaskEmailMask邮箱掩码前面的部分首尾各保留 1 位非邮箱格式回退默认模式见 EmailMaskHashMask散列掩码算法为sha1(sourcesalt)默认 salt 为default_salt可通过DataMask.setHashSalt(String)修改见 HashMask。4.4 Sensitive 注解的三种标注方式Sensitive注解 只对字符串相关类型的字段生效String、String[]、CollectionString标注方式包括// 根据类型来标注 Sensitive(type SensitiveType.Name) private String name; // 也可以自定义掩码规则 Sensitive(keepChars 2) // 首尾各保留2个字符keepChars {1,3} 表示头部保留1个字符尾部保留3个字符 private String[] phone; // 散列的方式 Sensitive(type SensitiveType.Hash) private String hash; // 默认的方式只保留第一个字符 Sensitive private ListString account;注解属性说明对应源码type()脱敏类型默认SensitiveType.DefaultkeepChars()自定义保留字符数默认{1, 0}。当首尾保留数量一致时可只写一个数字如{2}表示首尾各保留 2 个字符{1, 2}表示头部保留 1 个、尾部保留 2 个。从 DataMaskJsonFilter 源码 可以看出序列化脱敏的完整处理逻辑对每个 JSON 字段按字段类型分流处理——String直接脱敏、String[]逐元素脱敏、Collection通过泛型参数判断是否为CollectionString后重建集合逐元素脱敏其余类型原样返回脱敏时优先取字段上的Sensitive注解没有注解则回落到MaskMapping的字段名映射。4.5 映射配置免注解的字段名脱敏如果不想逐个字段标注Sensitive可以在 classpath 的 resource 目录下新建data_mask.properties添加敏感字段名映射#SensitiveType字段名称 NamenickName那么nickName字段即使没有标注Sensitive在序列化时也会自动按SensitiveType.Name的方式脱敏。注意标注Sensitive的优先级高于文件配置。组件内部已默认配置了系统级映射文件sys_data_mask.properties加载逻辑见 MaskMapping 源码默认映射如下NamechineseName,userName Phonephone,phoneNum,mobile,tel,telephone IDCardIDCard,IdNo BankCardbankCard Addressaddress,addr Emailmail,email Captchacaptcha Passportpassport Accountaccount Passwordpassword,passwd映射机制的两个实现要点从 MaskMapping 源码归纳通过Thread.currentThread().getContextClassLoader().getResources(...)加载 classpath 下所有同名配置文件支持多个 jar 同时提供映射字段名匹配时统一转为小写后查找mappings.put(map.toLowerCase(), sensitiveType)查询时getMaskTypeMapping同样转小写因此映射配置对大小写不敏感。4.6 性能基准JMH Benchmark脱敏组件基于性能和通用性考量设计官方使用 JMH 基准测试验证了 2 个使用场景。场景 1通用场景包含 10 个左右 Sensitive 字段的对象Benchmark Mode Score Error Units DataMaskTest.testJson(不脱敏) avgt 0.001 ± 0.001 ms/op DataMaskTest.testMaskJson avgt 0.003 ± 0.002 ms/op DataMaskTest.testMaskToString avgt 0.005 ± 0.003 ms/op DataMaskTest.testToString avgt ≈ 10⁻⁴ ms/optoJSONString()平均耗时 0.003mstoString()平均耗时 0.005ms。场景 2极限场景超大对象序列化有 160 多个字段需要脱敏3 层嵌套Benchmark Mode Score Error Units DataMaskTest.testJson avgt 0.043 ± 0.025 ms/op DataMaskTest.testMaskJson avgt 0.064 ± 0.002 ms/op DataMaskTest.testMaskToString avgt 0.098 ± 0.095 ms/op DataMaskTest.testToString avgt ≈ 10⁻⁴ ms/optoJSONString()平均耗时 0.064mstoString()平均耗时 0.098ms。结论脱敏处理的性能与脱敏字段的数量相关如果需要脱敏的字段不多耗时在 0.001ms ~ 0.009ms 范围内对业务不会造成太多额外开销在可控范围内如果需要脱敏的字段特别多建议做性能测试评估toString()性能比toJson()慢建议优先使用toJson()。五、建议直接使用的第三方工具类VJKit 并非要替代一切官方文档直用三方工具类明确指出以下成熟能力建议直接使用第三方库原生的 API而不是经由 VJKit 封装项目类Commons LangStringUtilsValidateGuavaCacheOrderingJDKArraysCollections这个取舍思路贯穿 VJKit 整体设计该提炼的提炼、该直用的直用避免重复造轮子。六、质量保障Sonar 静态扫描VJKit 通过 SonarCloud 进行持续静态质量检查使用 Sonar Way 规则集扫描状态可在官方文档给出的面板地址查看。仓库 vjkit/pom.xml 中配置了sonarprofile结合 JaCoCo 覆盖率与 sonar-maven-plugin 执行扫描并对从外部移植的代码做了排除处理sonar.exclusions排除了**/primitive/**、**/jsr166e/**、SortedArrayList.java、WildcardMatcher.java、CsvUtil.java等文件说明这些移植代码不参与自研质量扫描。七、小结VJKit 作为唯品会的 Java 基础类库用提炼归类 借鉴移植两条路线覆盖了日常开发的基础设施需求通过 Maven 坐标 一步引入JDK 7 即可运行必选依赖仅 Guava、Commons Lang 与 Slf4j重依赖全部 optional 化以便按需引入。其中日志脱敏组件vjmask是开箱即用的亮点——支持单字符串、JSON 序列化、toString 三种脱敏方式内置 11 种敏感信息规则提供注解与字段名映射两种配置途径并以 JMH 数据验证了其低开销。配合仓库内每个模块的单元测试与 JavaDocVJKit 是一套可以直接指导生产编码实践的基础设施类库。延伸阅读日志脱敏完整文档、直用三方工具类、vjkit 单元测试目录。赞分享开发工具可观测性后端【免费下载链接】vjtoolsThe vip.coms java coding standard, libraries and tools项目地址https://gitcode.com/gh_mirrors/vj/vjtools点击查看免费下载相关推荐nginxconfig.io日志脱敏敏感信息过滤与保护nginxconfig.io日志脱敏敏感信息过滤与保护 引言日志安全的隐形威胁 你是否意识到NGINX服务器的访问日志中可能潜藏着用户密码、API密钥等敏开发工具前端10个步骤掌握POCO C库日志脱敏从入门到实战的完整指南10个步骤掌握POCO C库日志脱敏从入门到实战的完整指南 POCO C库是一套功能强大的跨平台C库用于构建运行在桌面、服务器、移动设备、物联网后端网络/通信数据库密码学Web框架日志安全防线30天自制C服务器敏感信息脱敏实战指南日志安全防线30天自制C服务器敏感信息脱敏实战指南 在当今数据驱动的时代服务器日志作为系统运行的“黑匣子”记录着用户行为、系统状态和业务交互的关键信息示例工程上一篇OctoPrint主题开发教程创建个性化界面的步骤下一篇DooTask多项目协同大型组织任务管理的架构设计终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
