Spring专题「技术原理」为大家介绍一下Spring中的Ant路径匹配工具组件AntPathMatcher

Posted 2022-12-30 洛神灬殇

Spring中的绝大多数的路径匹配规则是依照Ant的标准来的

实际上不只是SpringMVC，整个Spring框架的路径解析都是按照Ant的风格来的，在Spring中的具体实现,详情参见 org.springframework.util.AntPathMatcher，具体规则如下

spring mvc url地址匹配工具类

AntPathRequestMatcher

在spring mvc 中我们会经常使用//.jsp、/app//dir/file.、/**/example 、/app/.x 类似于这样语法而负责真正判断是否匹配的工具类就是AntPathRequestMatcher

/**
 * @link PathMatcher implementation for Ant-style path patterns.
 *
 * <p>Part of this mapping code has been kindly borrowed from <a href="http://ant.apache.org">Apache Ant</a>.
 *
 * <p>The mapping matches URLs using the following rules:<br>
 * <ul>
 * <li>@code ? matches one character</li>
 * <li>@code * matches zero or more characters</li>
 * <li>@code ** matches zero or more <em>directories</em> in a path</li>
 * <li>@code spring:[a-z]+ matches the regexp @code [a-z]+ as a path variable named "spring"</li>
 * </ul>
 *
 * <h3>Examples</h3>
 * <ul>
 * <li>@code com/t?st.jsp &mdash; matches @code com/test.jsp but also
 * @code com/tast.jsp or @code com/txst.jsp</li>
 * <li>@code com/*.jsp &mdash; matches all @code .jsp files in the
 * @code com directory</li>
 * <li><code>com/&#42;&#42;/test.jsp</code> &mdash; matches all @code test.jsp
 * files underneath the @code com path</li>
 * <li><code>org/springframework/&#42;&#42;/*.jsp</code> &mdash; matches all
 * @code .jsp files underneath the @code org/springframework path</li>
 * <li><code>org/&#42;&#42;/servlet/bla.jsp</code> &mdash; matches
 * @code org/springframework/servlet/bla.jsp but also
 * @code org/springframework/testing/servlet/bla.jsp and @code org/servlet/bla.jsp</li>
 * <li>@code com/filename:\\\\w+.jsp will match @code com/test.jsp and assign the value @code test
 * to the @code filename variable</li>
 * </ul>
 *
 * <p><strong>Note:</strong> a pattern and a path must both be absolute or must
 * both be relative in order for the two to match. Therefore it is recommended
 * that users of this implementation to sanitize patterns in order to prefix
 * them with "/" as it makes sense in the context in which they're used.
 * /

符号的规则定义标准

AntPathMatcher如名使用的ant 的匹配规则,我们先看看吧.

• ? 匹配1个字符
• • 匹配0个或多个字符
• ** 匹配路径中的0个或多个目录
• spring:[a-z]+ 将正则表达式[a-z]+匹配到的值，赋值给名为spring的路径变量。
  必须是完全匹配才行，在SpringMVC中只有完全匹配才会进入controller层的方法

符号 ?

和其它几个不一样的是? 要求必须为一个字符，并且不能是代表路径分隔符的/。

@RequestMapping("/index?")
@ResponseBody
public String index()
    return "index.html";
 

结果

index           false 404错误(必须要有一个字符)
index/          false 404错误(不能为"/")
indexab         false 404错误(不能是多个字符)
indexa          true  输出页面index.html

符号 *

* ，虽然可以匹配多个任意的字符，但是，无法用 * 可以替代 ** ，因为 * 代表的多个任意字符组成的字符串不能是个目录或者说路径.也就是说，* 并不能拿来替代 **.

示例代码:

@RequestMapping("/index*")
@ResponseBody
public String index()
    return "index.html";

结果:

index           true  输出index.html(可以为0字符)
index/          true  输出 index.html(可以为"/")
indexa          true  输出 index.html(可以为1个字符)
indexabc        true  输出 index.html(可以为多个字符)
index/a         false 404错误("/a"是一个路径)

符号 **

0个或多个目录.** 代表的字符串本身不一定要包含 /

@RequestMapping("/index/**/a")
@ResponseBody
public String index()
    return "index.html";

结果:

index/a         true  输出 index.html(可以为0个目录)
index/x/a       true  输出 index.html(可以为一个目录)
index/x/z/c/a   true  输出 index.html(可以为多个目录)

符号 spring:[a-z]+

其它的关于 AntPathMatcher 的文章里,对 spring:[a-z]+ 的匹配大多是只字未提.这里补充下.

示例代码:

@RequestMapping("/index/username:[a-b]+")
@ResponseBody
public String index(@PathVariable("username") String username)
    System.out.println(username);
    return username;

结果:

index/ab        true  输出 ab
index/abbaaa    true  输出 abbaaa
index/a         false 404错误
index/ac        false 404错误

需求：我在做rbac权限校验的时候，设置管理员的访问路径为/admin/**,希望所有的开头为/admin/的uri操作地址都能进行匹配判断。

PathMatcher接口

主要是判断是否匹配pattern,并解析出path中的参数

package org.springframework.util;

public interface PathMatcher 

    /**
     * 判断传入的path是否可以作为pattern使用
     */
    boolean isPattern(String path);

    /**
     * 使用pattern匹配path
     */
    boolean match(String pattern, String path);

    /**
     * 如名,是否开始部分匹配
     */
    boolean matchStart(String pattern, String path);

    /**
     * 提取path中匹配到的部分,如pattern(myroot/*.html),path(myroot/myfile.html),返回myfile.html
     */
    String extractPathWithinPattern(String pattern, String path);

    /**
     * 提取path中匹配到的部分,只是这边还需跟占位符配对为map,
     * 如pattern(/hotels/hotel),path(/hotels/1),解析出"hotel"->"1"
     */
    Map<String, String> extractUriTemplateVariables(String pattern, String path);

    /**
     * 提供比较器
     */
    Comparator<String> getPatternComparator(String path);

    /**
     * 合并pattern,pattern1然后pattern2
     */
    String combine(String pattern1, String pattern2);

手动使用方式

• AntPathMatcher不仅可以匹配Spring的@RequestMapping路径，也可以用来匹配各种字符串，包括文件路径等。
• AntPathMatcher默认路径分隔符为“/”，而在匹配文件路径时，需要注意Windows下路径分隔符为“\\”，Linux下为“/”，写法即为：

初始化创建操作

匹配文件路径，使用AntPathMatcher创建一个对象时，需要注意AntPathMatcher也有有参构造，传递路径分隔符参数pathSeparator，对于文件路径的匹配来说，则需要根据不同的操作系统来传递各自的文件分隔符，以此防止匹配文件路径错误。

AntPathMatcher matcher = new AntPathMatcher(File.separator)；
AntPathMatcher matcher = new AntPathMatcher(System.getProperty("file.separator"))；

执行匹配操作

import org.springframework.util.AntPathMatcher;
String content = "/admin/acuff";
String pattern = "/admin/**";
System.out.println(antPathMatcher.match(pattern, content));

最长匹配原则(has more characters)

最长匹配规则（has more characters），即越精确的模式越会被优先匹配到。例如，URL请求/app/dir/file.jsp，现在存在两个路径匹配模式/**/.jsp和/app/dir/.jsp，那么会根据模式/app/dir/*.jsp来匹配。

当然如果觉得这个工具还不够强大，还可以使用RegexRequestMatcher ，它支持使用正则表达式对URL地址进行匹配。如果你觉得这些都不够强大可以自己重写 RequestMatcher接口来进行定制的路由匹配规则

看AntPathMatcher的使用

match 跟 matchStart

match 跟 matchStart 的差异,这个我们在测试用例看下面的情况会比较明确

package org.springframework.util;
public class AntPathMatcherTests 
    @Test
    public void match() 
        // ...
        assertFalse(pathMatcher.match("/x/x/**/bla", "/x/x/x/"));
        // ...
    
    @Test
    public void withMatchStart() 
        // ...
        assertTrue(pathMatcher.matchStart("/x/x/**/bla", "/x/x/x/"));
        // ...
    

extractPathWithinPattern

package org.springframework.util;
public class AntPathMatcherTests 
    @Test
    public void extractPathWithinPattern() throws Exception 
        // ...
        assertEquals("", pathMatcher.extractPathWithinPattern("/docs/commit.html", "/docs/commit.html"));
        assertEquals("cvs/commit", pathMatcher.extractPathWithinPattern("/docs/*", "/docs/cvs/commit"));
        assertEquals("docs/cvs/commit", pathMatcher.extractPathWithinPattern("/d?cs/*", "/docs/cvs/commit"));
        // ...
    

extractUriTemplateVariables

package org.springframework.util;
public class AntPathMatcherTests 
    @Test
    public void extractUriTemplateVariables() throws Exception 
        Map<String, String> result = pathMatcher.extractUriTemplateVariables("/hotels/hotel", "/hotels/1");
        assertEquals(Collections.singletonMap("hotel", "1"), result);
        // ...
        result = pathMatcher.extractUriTemplateVariables("/page.*", "/42.html");
        assertEquals(Collections.singletonMap("page", "42"), result);
        // ...
    
    /**
     * SPR-7787
     */
    @Test
    public void extractUriTemplateVarsRegexQualifiers() 
        Map<String, String> result = pathMatcher.extractUriTemplateVariables(
                "symbolicName:[\\\\pL\\\\.]+-sources-version:[\\\\pN\\\\.]+.jar",
                "com.example-sources-1.0.0.jar");
        assertEquals("com.example", result.get("symbolicName"));
        assertEquals("1.0.0", result.get("version"));
        // ...
    

combine

package org.springframework.util;
public class AntPathMatcherTests 
    @Test
    public void combine() 
        // ...
        assertEquals("/hotels", pathMatcher.combine("/hotels", null));
        assertEquals("/hotels/booking", pathMatcher.combine("/hotels/*", "/booking"));
        assertEquals("/hotels/**/booking", pathMatcher.combine("/hotels/**", "booking"));
        assertEquals("/hotels/**/booking", pathMatcher.combine("/hotels/**", "/booking"));
        assertEquals("/hotels/booking", pathMatcher.combine("/hotels", "/booking"));
        assertEquals("/hotels/hotel", pathMatcher.combine("/hotels/*", "hotel"));
        assertEquals("/hotels/**/hotel", pathMatcher.combine("/hotels/**", "hotel"));
        assertEquals("/hotels/*/booking/booking", pathMatcher.combine("/hotels/*/booking", "booking"));