# grief.AUrl

**Repository Path**: subpu/AURL

## Basic Information

- **Project Name**: grief.AUrl
- **Description**: 解析, 构建, 编辑URL的实用工具包
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-08-17
- **Last Updated**: 2024-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java

## README

# grief.AUrl

#### 介绍
解析, 构建, 编辑URL的实用工具包. 工具主要有三个类: AUrl入口类, AUrlMeta解析信息类, AUrlMetaBuilder信息类(AUrlMeta)的构建器

#### 软件架构
项目基于JDK17开发. 内置的解析器依赖Antlr 4.  


#### 使用说明

1. 解析和构建 
 - 1.1 默认的内置解析器: AntlrParser. 示例:

    ```
    AUrlMeta meta = AUrl.parse("http://www.a.com:8080/order/create?product=100#descript");
    ```

 - 1.2 支持自定义解析器参数的parse. 示例:

    ```
    AUrlMeta meta = AUrl.parse("http://www.a.com:8080/order/create?product=100#descript", new PatternParser());
    ```


  - 1.3 构建

    借鉴了Spring的UriComponentsBuilder的方法思想. 毕竟很少需要手动去构造。但构建器仍作为解析器的关键组件. 示例:

    ```
    AUrlMeta urlRawMeta = AUrl.create().scheme("https").host("www.google.com").queryParam("q", Arrays.asList("baeldung")).build();
    ```

    除此之外也提供基于部分构建整体的方法. 示例:

    ```
    AUrlMeta urlRawMeta = AUrl.create("https://www.google.com/").queryParam("q", Arrays.asList("baeldung")).build();
    ```
    

2. 地址的规范化

   AUrl提供了两个静态方法: `normalize` 和 `canonical`, 两者不同之处在于其返回值不同. 示例:

   ````
    @Test
    public void testNormalize(){
        String nurl = AUrl.normalize("http://www.example.com/app/#/home?a=1").orElse("about:blank");
        assertEquals(nurl, "http://www.example.com/app/home?a=1");
    }
   ````
   
3. 执行器 / 选择器 / 转换器
 - 3.1 提供对查询参数常见的编辑操作. API作为AUrlMeta 对象的扩展执行器实现. 示例:

    ```
    System.out.println("[1]Before URL:"+urlRawMeta);
    ClipParameterExecutor executor = urlRawMeta
                .clipQueryParam()
                .delete("q")
                .add("product", 1)
                .add("member", 11)
                .replace("product", 1010);
    // 打印编辑后的结果
    System.out.println("[1]After URL:"+executor.getRawMeta().toURI());
    // 打印编辑动作的执行历史
    executor.getActionRecords().stream().forEach(System.out::println);
    ```

 - 3.2 AUrlMeta的执行器方法: execute

    ```
    <T,S> S execute(Class<? extends AUrlMetaExecutor<T>> classIns) throws NullPointerException
    ```

    除了上面提到的查询参数编辑执行器(ClipParameterExecutor), 还提供一个对URL转换的执行器，例: 短地址的执行器

    ```
    ShortUrlExecutor shortUrlExecutor = meta.execute(ShortUrlExecutor.class);
    // 打印生成的短地址
    System.out.println("[SUS]url:"+shortUrlExecutor.generate());
    // 打印编辑动作的执行历史, short为生成的结果，original为原地址
    shortUrlExecutor.getActionRecords().stream().forEach(System.out::println);
    
    ```

    短地址生成执行器支持自定义生成配置. 提供: 
   + urlBase 前缀地址, 若不提供使用AUrlMeta的schema和host
   + path 路径, 若不提供使用: /
   + length 生成字符长度, 若不提供默认为: 6. 允许的范围在: 5~8之间
   + algorithm 生成字符使用的散列算法名称, 若不提供默认为: MD5. 其它可供选择的有: SHA1, SHA256
 
    示例:
    ```
    ShortUrlExecutor shortUrlExecutor = meta.execute(ShortUrlExecutor.class);
    ShortUrlExecutor.Config config = ShortUrlExecutor.Config
                                            .create("http://z.cn")
                                            .path("u")
                                            .length(6)
                                            .algorithm(ShortUrlExecutor.Algorithm.MD5);
    System.out.println("[SUS]url:"+shortUrlExecutor.generate(config));
    ```

 - 3.3 AUrlMetaExecutor执行器实现提供执行历史的信息.若不需要这些信息可以使用同名方法: execute

    ```
    <R> R execute(Function<AUrlMeta,R> executor)
    ```

 - 3.4 转换器用于将当前实例转换为另一种结构或对像. 例: toURI, toMap, toBuilder. AUrlMeta提供的转换器方法

   ```
   <R> R convert(AUrlMetaConvertor<R> convertor)
   ```
   
   除了上面提到的toXXX方法. AUrlMeta中一些扩展方法也使用转换器实现. 例: link / join. 完成将参数地址中缺少的部分使用当前对象相应部份填充. 两者不同之处在于其返回值不同.

   ```
   AUrlMetaBuilder link(String urlStr)
   ```

   ```
   String join(String urlStr)
   ```
 - 3.5 使用选择器实现从当前实例的属性值中提出或复合成某些实用的方法.  例: toString, getQuery, getFile. AUrlMeta提供的选择器方法

   ```
   <S> S select(Class<? extends AUrlMetaSelector> classIns)
   ```
   
   除了上面提到的方法外. AUrlMeta中的fileType方法返回一个文件类型选择器: FileTypeSelector, 选择器中提供了一些检查方法用以检查连接的文件类型. 这些方法的格式如下:

   ````
   isExtension()
   ````
   
   例: 是否是图片的: `isImage`, 是否是Word的: `isWord`, 是否是Excel的: `isExcel`, 是否是Pdf的: `isPdf`, 是否是压缩包的: `isZip`等等. 对于判断连接的媒体类型是有效的，该选择器还提供了自定义校验方法：

   ````
   boolean isValide(Predicate<String> customValider)
   ````
   
 - 3.6 AUrlMeta其它方法说明
   + 查看指定查询参数的值: getQueryParam, getQueryParams
   
   + 查看查询字符串中key的数量: getQueryParamSize
   
   + 是否是合法的URL: isLegalURL
   
   + 是否是加密模式: isHttps
   
   + java.net.URL的同名方法: sameFile
   
   + 信息转换: join, 别名方法: link
    
   用于将当前信息中的非域名部分的信息转换到join参数上. 示例:
    
   ```
   AUrlMeta meta = AUrl.parse("https://www.google.com/search?q=baeldung");
   String temp = meta.join("/page");
   // temp输出为: https://www.google.com/page?q=baeldung
   ```
    
   + path修正: relative, 别名方法: resolve
    
   基于方法参数的相对路径信息修正当前信息中的：path, query, fragment. 示例:

   ```
   AUrlMeta meta = AUrl.parse("http://www.a.com:8080/order/create?product=100#descript");
   String temp = meta.relative("../look?p=1&word=php");
   // temp输出为: http://www.a.com:8080/order/look?p=1&word=php#descript
   ```

4. AUrl中快速入口

   AUrl中提供AUrlMeta的选择器, 执行器和转换器方法的快速入口, 省去AUrlMeta这个中间商. 从执行流上看两者是无区别的, 在一些api调用上还是很有必要的(谁都不想多打字). 以下是一个示例:
  - 4.1 一步一步:
      ````
      AUrlMeta build = AUrl.create("http://localhost/api/employees/{id}/{attr}/{val}").build();
      PathParamExecutor execute = build.execute(PathParamExecutor.class);
      String replacePath = execute.replace(Map.of("id", "1", "attr", "nickname", "val", "xiaofanku"));
      assertEquals(replacePath, "/api/employees/1/nickname/xiaofanku");
      ````
   
  - 4.2 通过快速入口:
      ````
      PathParamExecutor execute = AUrl.execute(PathParamExecutor.class).arg("http://localhost/api/employees/{id}/{attr}/{val}");
      String replacePath = execute.replace(Map.of("id", "1", "attr", "nickname", "val", "xiaofanku"));
      assertEquals(replacePath, "/api/employees/1/nickname/xiaofanku");
      ````
   
  - 4.3 Api对外屏蔽了AUrlMeta的创建过程, 调用者感知不到它的存在. 对于不同的解析器使用也提供了函数式支持, 默认使用: `PatternParser`解析器, 以下示例使用指定的解析器
      ````
      String b = "https://img.baidu.com/newsuploadfiles/2023/9/dfa1d3dc-a259-4dc6-8676-cd40d3ff9570.jpg";
      Map<String, String> map = AUrl.convert(new MapConvertor()).use(new AntlrParser()).apply(b);
      map.entrySet().stream().forEach(System.out::println);
      ````
   
  - 4.4 总结: 
      
    - 默认的解析器: `AUrl.select(选择器实现类.class).arg(参数)` , `AUrl.execute(执行器实现类.class).arg(参数)`, `AUrl.convert(转换器接口实现类).arg(参数)`
    - 自定义解析器: `AUrl.select(选择器实现类.class).use(解析器实现类).apply(参数)` , `AUrl.execute(执行器实现类.class).use(解析器实现类).apply(参数)`, `AUrl.convert(转换器接口实现类).use(解析器实现类).apply(参数)`

5. 地址中的参数变量
  - 5.1 可以在AUrlMetaBuilder上使用`template`方法替换掉参数变量. 示例:

      ````
      AUrlMeta build = AUrl.create("http://localhost/api/employees/{id}/{action}").template(new TBean(1, "modify"));
      assertEquals(build.toString(), "http://localhost/api/employees/1/modify");
      ````

      AUrlMetaBuilder的`template`是多态方法, 支持`JavaBean`, `Map`, `Collection<Pair>`. 这样在AUrlMeta中是不包含路径变量, 可以通过`AUrlMeta.hasPathVariable`来判断实例中是否包含路径变量


  - 5.2 可以通过AUrlMeta中的执行器来进行参数变量的处理, 示例:

      ````
      AUrlMeta build = AUrl.create("http://localhost/api/employees/{id}/{action}").build();
      PathParamExecutor execute = build.execute(PathParamExecutor.class);
      String replacePath = execute.replace("id", "1", "action", "revoke");
      assertEquals(replacePath, "/api/employees/1/revoke");
      ````
    PathParamExecutor中的`replace`是多态方法, 支持不同参数的多种形式来返回参数化后的路径. 若希望返回参数后的完整地址可以使用: `extract` 方法, 不仅支持解压单个地址也支持批量解压, 示例：

    ````
    AUrlMeta build = AUrl.create("http://localhost/api/employees/{id}/{action}").build();
    PathParamExecutor execute = build.execute(PathParamExecutor.class);
    TBean bean = new TBean(1, "modify");
    String bb = execute.extractToString(bean);
    assumeTrue(bb.equals(execute.extract(bean).toString()) && bb.equals("http://localhost/api/employees/1/modify"));
    ````
    
    批量解压示例::
      ````
      AUrlMeta build = AUrl.create("http://localhost/api/employees/{id}/{action}").build();
      PathParamExecutor execute = build.execute(PathParamExecutor.class);
      List<Map<String,String>> list = new ArrayList<>(4);
      list.add(Map.of("id", "1", "action", "revoke"));
      list.add(Map.of("id", "2", "action", "avatar"));
      list.add(Map.of("id", "3", "action", "home"));
      list.add(Map.of("id", "4", "action", "auth"));
      List<String> rs = execute.extractByMapToString(list).collect(Collectors.toList());
      assertThat(rs)
                .contains(
                    "http://localhost/api/employees/1/revoke",
                    "http://localhost/api/employees/2/avatar",
                    "http://localhost/api/employees/3/home",
                    "http://localhost/api/employees/4/auth")
                .hasSize(4);
      ````
    `extract` 方法分为两类,一类返回AUrlMeta实例或实例集合, 一类返回String或String流. 两者使用不同的实现. 切记: 需要String时不要调用返回AUrlMeta的方法再toString. 这样代价比返回String的要高~~