feat: 新增 ZipTools 工具类 (#70 #Gitea)

新增 `ZipTools` 工具类提供最基础的数据压缩/解压方法

plusone-commons/src/main/java/xyz/zhouxy/plusone/commons/util/ZipTools.java

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package xyz.zhouxy.plusone.commons.util;
+
+import static xyz.zhouxy.plusone.commons.util.AssertTools.checkArgument;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.util.zip.Deflater;
+import java.util.zip.DeflaterOutputStream;
+import java.util.zip.Inflater;
+import java.util.zip.InflaterOutputStream;
+
+import javax.annotation.CheckForNull;
+import javax.annotation.Nullable;
+
+/**
+ * zip 工具类
+ *
+ * <p>
+ * 提供最基础的数据压缩/解压方法
+ *
+ * @author ZhouXY108 <luquanlion@outlook.com>
+ *
+ * @see Deflater
+ * @see Inflater
+ */
+public class ZipTools {
+
+    /**
+     * 使用默认压缩级别压缩数据
+     *
+     * @param input 输入
+     * @param level 压缩级别
+     * @return 压缩后的数据
+     *
+     * @throws IOException 发生 I/O 错误时抛出
+     */
+    public static byte[] zip(@Nullable byte[] input) throws IOException {
+        return zipInternal(input, Deflater.DEFAULT_COMPRESSION);
+    }
+
+    /**
+     * 使用指定压缩级别压缩数据
+     *
+     * @param input 输入
+     * @param level 压缩级别
+     * @return 压缩后的数据
+     *
+     * @throws IOException 发生 I/O 错误时抛出
+     */
+    public static byte[] zip(@Nullable byte[] input, int level) throws IOException {
+        checkArgument((level >= 0 && level <= 9) || level == Deflater.DEFAULT_COMPRESSION,
+                "invalid compression level");
+        return zipInternal(input, level);
+    }
+
+    @CheckForNull
+    private static byte[] zipInternal(@Nullable byte[] input, int level) throws IOException {
+        if (input == null) {
+            return null;
+        }
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        try (DeflaterOutputStream dos = new DeflaterOutputStream(baos, new Deflater(level))) {
+            dos.write(input);
+            dos.finish();
+            return baos.toByteArray();
+        }
+    }
+
+    /**
+     * 解压数据
+     *
+     * @param input 输入
+     * @return 解压后的数据
+     *
+     * @throws IOException 发生 I/O 错误时抛出
+     */
+    @CheckForNull
+    public static byte[] unzip(@Nullable byte[] input) throws IOException {
+        if (input == null) {
+            return null;
+        }
+        ByteArrayOutputStream baos = new ByteArrayOutputStream();
+        try (InflaterOutputStream dos = new InflaterOutputStream(baos, new Inflater())) {
+            dos.write(input);
+            dos.finish();
+            return baos.toByteArray();
+        }
+    }
+
+    private ZipTools() {
+        throw new IllegalStateException("Utility class");
+    }
+}

plusone-commons/src/test/java/xyz/zhouxy/plusone/commons/util/ZipToolsTests.java

@@ -0,0 +1,86 @@
+package xyz.zhouxy.plusone.commons.util;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.io.IOException;
+import java.lang.reflect.Constructor;
+import java.net.URL;
+import java.util.Arrays;
+import java.util.Random;
+import java.util.zip.DataFormatException;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import com.google.common.base.Stopwatch;
+import com.google.common.io.Resources;
+
+import lombok.extern.slf4j.Slf4j;
+
+@Slf4j
+public class ZipToolsTests {
+
+    static byte[] bytes;
+
+    @BeforeAll
+    static void setup() throws IOException {
+        URL resource = Resources.getResource("xyz/zhouxy/plusone/commons/util/LoremIpsum.txt");
+        bytes = Resources.toByteArray(resource);
+    }
+
+    @Test
+    void zip_WithDefaultLevel() throws IOException, DataFormatException {
+        Stopwatch stopwatch = Stopwatch.createStarted();
+        byte[] zip = ZipTools.zip(bytes);
+        stopwatch.stop();
+        log.info("default level, size: {} ({})", zip.length, stopwatch);
+        assertArrayEquals(bytes, ZipTools.unzip(zip));
+
+        assertNull(ZipTools.zip(null));
+        assertNull(ZipTools.unzip(null));
+    }
+
+    @ParameterizedTest
+    @ValueSource(ints = { -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 })
+    void zip_WithLevel(int level) throws IOException, DataFormatException {
+        Stopwatch stopwatch = Stopwatch.createStarted();
+        byte[] zip = ZipTools.zip(bytes, level);
+        stopwatch.stop();
+        log.info("level: {}, size: {} ({})", level, zip.length, stopwatch);
+        assertArrayEquals(bytes, ZipTools.unzip(zip));
+
+        assertNull(ZipTools.zip(null, level));
+        assertNull(ZipTools.unzip(null));
+    }
+
+    @Test
+    void zip_WithWrongLevel() throws IOException, DataFormatException {
+        Random random = new Random();
+        final int levelGtMax = random.nextInt() + 9;
+        assertThrows(IllegalArgumentException.class, () -> ZipTools.zip(bytes, levelGtMax));
+
+        final int levelLtMin = -1 - random.nextInt();
+        assertThrows(IllegalArgumentException.class, () -> ZipTools.zip(bytes, levelLtMin));
+    }
+
+    @Test
+    void test_constructor_isNotAccessible_ThrowsIllegalStateException() {
+        Constructor<?>[] constructors = ZipTools.class.getDeclaredConstructors();
+        Arrays.stream(constructors)
+                .forEach(constructor -> {
+                    assertFalse(constructor.isAccessible());
+                    constructor.setAccessible(true);
+                    Throwable cause = assertThrows(Exception.class, constructor::newInstance)
+                            .getCause();
+                    assertInstanceOf(IllegalStateException.class, cause);
+                    assertEquals("Utility class", cause.getMessage());
+                });
+    }
+}