README.md

    ZUtil

    star

    追求更快更全的 Java 工具类。

    工具类使用请查看文档javadoc

    和 Hutool 的性能对比测试请查看 jmh.contrast

    特性

    Stargazers over time

    Stargazers over time

    说明

    安装

    Maven

    ```xml
    <dependency>
      <groupId>top.csaf</groupId>
      <artifactId>ZUtil</artifactId>
      <version>1.13.1</version>
    </dependency>
    ```

    Gradle

    ```groovy
    // groovy
    implementation 'top.csaf:ZUtil:1.13.1'
    // kotlin
    implementation("top.csaf:ZUtil:1.13.1")
    ```

    安装注意

    工具包中已使用 slf4j-api 和 slf4j-simple,和 spring-boot-starter-web 同时使用时会冲突,需要手动排除。

    Maven

    <!-- 方式一:ZUtil 排除 slf4j -->
    <dependency>
      <groupId>top.csaf</groupId>
      <artifactId>ZUtil</artifactId>
      <version>1.13.1</version>
      <exclusions>
        <exclusion>
          <groupId>org.slf4j</groupId>
          <artifactId>slf4j-api</artifactId>
        </exclusion>
        <exclusion>
          <groupId>org.slf4j</groupId>
          <artifactId>slf4j-simple</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
    
    <!-- 方式二:spring-boot-starter-web 排除 Logback -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
      <exclusions>
        <exclusion>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
      </exclusions>
    </dependency>

    Gradle

    参考:Excluding transitive dependencies - Gradle User Manual

    // groovy
    dependencies {
      // 方式一:ZUtil 排除 slf4j
      implementation('top.csaf:ZUtil:1.13.1') {
        exclude group: 'org.slf4j', module: 'slf4j-api'
        exclude group: 'org.slf4j', module: 'slf4j-simple'
      }
      // 方式二:spring-boot-starter-web 排除 Logback
      implementation('org.springframework.boot:spring-boot-starter-web') {
        exclude group: 'org.springframework.boot', module: 'spring-boot-starter-logging'
      }
    }
    
    // kotlin
    dependencies {
      // 方式一:ZUtil 排除 slf4j
      implementation("top.csaf:ZUtil:1.13.1") {
        exclude(group = "org.slf4j", module = "slf4j-api")
        exclude(group = "org.slf4j", module = "slf4j-simple")
      }
      // 方式二:spring-boot-starter-web 排除 Logback
      implementation("org.springframework.boot:spring-boot-starter-web") {
        exclude(group = "org.springframework.boot", module = "spring-boot-starter-logging")
      }
    }

    JMH 性能对比测试结果解释

    // Benchmark                                                 Mode     Cnt    Score    Error   Units
    // ToPinyinTest.toPinyinByHutool                            thrpt       5    2.880 ±  0.160  ops/us
    // ToPinyinTest.toPinyinByZUtil                             thrpt       5    4.577 ±  0.133  ops/us
    // ToPinyinTest.toPinyinByHutool                             avgt       5    0.356 ±  0.012   us/op
    // ToPinyinTest.toPinyinByZUtil                              avgt       5    0.216 ±  0.006   us/op
    // ToPinyinTest.toPinyinByHutool                           sample  175058    0.435 ±  0.008   us/op
    // ToPinyinTest.toPinyinByHutool:toPinyinByHutool·p0.00    sample            0.300            us/op
    // ToPinyinTest.toPinyinByHutool:toPinyinByHutool·p0.50    sample            0.400            us/op
    // ToPinyinTest.toPinyinByHutool:toPinyinByHutool·p0.90    sample            0.500            us/op
    // ToPinyinTest.toPinyinByHutool:toPinyinByHutool·p0.95    sample            0.500            us/op
    // ToPinyinTest.toPinyinByHutool:toPinyinByHutool·p0.99    sample            0.900            us/op
    // ToPinyinTest.toPinyinByHutool:toPinyinByHutool·p0.999   sample            1.600            us/op
    // ToPinyinTest.toPinyinByHutool:toPinyinByHutool·p0.9999  sample           40.900            us/op
    // ToPinyinTest.toPinyinByHutool:toPinyinByHutool·p1.00    sample          277.504            us/op
    // ToPinyinTest.toPinyinByZUtil                            sample  162384    0.393 ±  0.008   us/op
    // ToPinyinTest.toPinyinByZUtil:toPinyinByZUtil·p0.00      sample            0.200            us/op
    // ToPinyinTest.toPinyinByZUtil:toPinyinByZUtil·p0.50      sample            0.300            us/op
    // ToPinyinTest.toPinyinByZUtil:toPinyinByZUtil·p0.90      sample            0.500            us/op
    // ToPinyinTest.toPinyinByZUtil:toPinyinByZUtil·p0.95      sample            0.600            us/op
    // ToPinyinTest.toPinyinByZUtil:toPinyinByZUtil·p0.99      sample            1.000            us/op
    // ToPinyinTest.toPinyinByZUtil:toPinyinByZUtil·p0.999     sample            2.500            us/op
    // ToPinyinTest.toPinyinByZUtil:toPinyinByZUtil·p0.9999    sample           45.425            us/op
    // ToPinyinTest.toPinyinByZUtil:toPinyinByZUtil·p1.00      sample          170.496            us/op
    // ToPinyinTest.toPinyinByHutool                               ss       5   30.880 ± 37.754   us/op
    // ToPinyinTest.toPinyinByZUtil                                ss       5   23.060 ± 16.885   us/op

    Mode 即为org.openjdk.jmh.annotations.Mode,分为:

    • thrpt:Throughput(吞吐量), ops/time,分数越大越好
    • avgt:Average time(平均时间), time/op,分数越小越好
    • sample:Sampling time(采样时间),分数越小越好
    • ss:Single shot invocation time(单次调用时间):分数越小越好

    参与开发

    1. ForkClone 项目到本地。
    2. 开发内容:
      • 新增类或方法需提前加群沟通。
      • 修复 BUG(fix)、优化性能(perf)或新增/更正测试(test)。
    3. 测试步骤:
      • 使用org.junit.jupiter.api.Assertions进行代码覆盖率测试
      ……
      import static org.junit.jupiter.api.Assertions.*;
      
      @Slf4j
      @DisplayName("NanoId 工具类测试")
      class NanoIdUtilsTest {
      
        @DisplayName("生成 NanoID")
        @Test
        void randomNanoId() {
          /** {@link top.csaf.id.NanoIdUtils#randomNanoId(int, char[], java.util.Random) } */
          assertThrows(NullPointerException.class, () -> NanoIdUtils.randomNanoId(0, (char[]) null, NanoIdUtils.DEFAULT_ID_GENERATOR));
          assertThrows(NullPointerException.class, () -> NanoIdUtils.randomNanoId(0, new char[0], null));
          assertThrows(IllegalArgumentException.class, () -> NanoIdUtils.randomNanoId(0, new char[0], NanoIdUtils.DEFAULT_ID_GENERATOR));
          assertThrows(IllegalArgumentException.class, () -> NanoIdUtils.randomNanoId(1, new char[0], NanoIdUtils.DEFAULT_ID_GENERATOR));
          assertThrows(IllegalArgumentException.class, () -> NanoIdUtils.randomNanoId(1, new char[256], NanoIdUtils.DEFAULT_ID_GENERATOR));
          assertDoesNotThrow(() -> NanoIdUtils.randomNanoId(NanoIdUtils.DEFAULT_SIZE, NanoIdUtils.DEFAULT_ALPHABET, NanoIdUtils.DEFAULT_ID_GENERATOR));
        }
      }
      • mvn test -Dtest=要测试的类名进行测试,测试后会在target下生成jacoco.exec
      • mvn jacoco:report生成代码覆盖率测试报告,在target/site目录下。
      • 查看更新的类或方法,覆盖率在 90% 以上时提交。
      • lombok.NonNull的参数校验可以忽略。
    4. 提交时遵循 Angular 提交消息规范,提交后新建 pull request 即可。

    项目简介

    追求更快的 Java 工具类

    发行版本

    当前项目没有发行版本

    贡献者 5

    开发语言

    • Java 100.0 %