FilenameUtils.getName 函数源码分析

2024-04-02 19:55

短信预约 -IT技能 免费直播动态提醒

一、背景

最近用到了 org.apache.commons.io.FilenameUtils#getName 这个方法，该方法可以传入文件路径，获取文件名。简单看了下源码，虽然并不复杂，但和自己设想略有区别，值得学习，本文简单分析下。

二、源码分析

org.apache.commons.io.FilenameUtils#getName

 
    public static String getName(final String fileName) {
     // 传入 null 直接返回 null 
        if (fileName == null) {
            return null;
        }
        // NonNul 检查
        requireNonNullChars(fileName);
       //  查找最后一个分隔符
        final int index = indexOfLastSeparator(fileName);
     // 从最后一个分隔符窃到最后
        return fileName.substring(index + 1);
    }

2.1 问题1：为什么需要 NonNul 检查？

2.1.1 怎么检查的？

org.apache.commons.io.FilenameUtils#requireNonNullChars

   
    private static void requireNonNullChars(final String path) {
        if (path.indexOf(0) >= 0) {
            throw new IllegalArgumentException("Null byte present in file/path name. There are no "
                + "known legitimate use cases for such data, but several injection attacks may use it");
        }
    }

java.lang.String#indexOf(int) 源码：

 
    public int indexOf(int ch) {
        return indexOf(ch, 0);
    }

可知，indexOf(0) 目的是查找 ASCII 码为 0 的字符的位置，如果找到则抛出 IllegalArgumentException异常。搜索 ASCII 对照表，得知 ASCII 值为 0 代表控制字符 NUT，并不是常规的文件名所应该包含的字符。

2.1.2 为什么要做这个检查呢？

null 字节是一个值为 0 的字节，如十六进制中的 0x00。存在与 null 字节有关的安全漏洞。因为 C 语言中使用 null 字节作为字符串终结符，而其他语言（Java，PHP等）没有这个字符串终结符；例如，Java Web 项目只允许用户上传 .jpg 格式的图片，但利用这个漏洞就可以上传 .jsp 文件。如用户上传 hack.jsp<NUL>.jpg 文件， Java 会认为符合 .jpg 格式，实际调用 C 语言系统函数写入磁盘时讲当做字符串分隔符，结果将文件保存为 hack.jsp。有些编程语言不允许在文件名中使用 ·· <NUL>，如果你使用的编程语言没有对此处理，就需要自己去处理。因此，这个检查很有必要。

代码示例：

package org.example;
import org.apache.commons.io.FilenameUtils;
public class FilenameDemo {
    public static void main(String[] args) {
        String filename= "hack.jsp\0.jpg";
        System.out.println( FilenameUtils.getName(filename));
    }
}

报错信息：

Exception in thread "main" java.lang.IllegalArgumentException: Null byte present in file/path name. There are no known legitimate use cases for such data, but several injection attacks may use it
   at org.apache.commons.io.FilenameUtils.requireNonNullChars(FilenameUtils.java:998)
   at org.apache.commons.io.FilenameUtils.getName(FilenameUtils.java:984)
   at org.example.FilenameDemo.main(FilenameDemo.java:8)

如果去掉校验：

package org.example;
import org.apache.commons.io.FilenameUtils;
public class FilenameDemo {
    public static void main(String[] args) {
        String filename= "hack.jsp\0.jpg";
        // 不添加校验
        String name = getName(filename);
        // 获取拓展名
        String extension = FilenameUtils.getExtension(name);
        System.out.println(extension);
    }
    public static String getName(final String fileName) {
        if (fileName == null) {
            return null;
        }
        final int index = FilenameUtils.indexOfLastSeparator(fileName);
        return fileName.substring(index + 1);
    }
}

Java 的确会将拓展名识别为 jpg

jpg

JDK 8 及其以上版本试图创建 hack.jsp\0.jpg 的文件时，底层也会做类似的校验，无法创建成功。

大家感兴趣可以试试使用 C 语言写入名为 hack.jsp\0.jpg 的文件，最终很可能文件名为 hack.jsp。

2.2 问题2：为什么不根据当前系统类型来获取分隔符？

查找最后一个分隔符 org.apache.commons.io.FilenameUtils#indexOfLastSeparator

 
    public static int indexOfLastSeparator(final String fileName) {
        if (fileName == null) {
            return NOT_FOUND;
        }
        final int lastUnixPos = fileName.lastIndexOf(UNIX_SEPARATOR);
        final int lastWindowsPos = fileName.lastIndexOf(WINDOWS_SEPARATOR);
        return Math.max(lastUnixPos, lastWindowsPos);
    }

该方法的语义是获取文件名，那么从函数的语义层面上来说，不管是啥系统的文件分隔符都必须要保证得到正确的文件名。试想一下，在 Windows 系统上调用该函数，传入一个 Unix 文件路径，得不到正确的文件名合理吗？函数设计本身就应该考虑兼容性。因此不能获取当前系统的分隔符来截取文件名。源码中分别获取 Window 和 Unix 分隔符，有哪个用哪个，显然更加合理。

三、Zoom Out

3.1 代码健壮性

我们日常编码时，要做防御性编程，对于错误的、非法的输入都要做好预防。

3.2 代码严谨性

我们写代码一定不要想当然。我们先想清楚这个函数究竟要实现怎样的功能，而且不是做一个 “CV 工程师”，无脑“拷贝”代码。同时，我们也应该写好单测，充分考虑各种异常 Case ，保证正常和异常的 Case 都覆盖到。

3.3 如何写注释

org.apache.commons.io.FilenameUtils#requireNonNullChars 函数注释部分就给出了这么设计的原因：This may be used for poison byte attacks.

注释不应该“喃喃自语”讲一些显而易见的废话。对于容易让人困惑的设计，一定要通过注释讲清楚设计原因。

此外，结合工作经验，推荐一些其他注释技巧：（1）对于稍微复杂或者重要的设计，可以通过注释给出核心的设计思路；如： java.util.concurrent.ThreadPoolExecutor#execute

    
    public void execute(Runnable command) {
        if (command == null)
            throw new NullPointerException();
        
        int c = ctl.get();
        if (workerCountOf(c) < corePoolSize) {
            if (addWorker(command, true))
                return;
            c = ctl.get();
        }
        if (isRunning(c) && workQueue.offer(command)) {
            int recheck = ctl.get();
            if (! isRunning(recheck) && remove(command))
                reject(command);
            else if (workerCountOf(recheck) == 0)
                addWorker(null, false);
        }
        else if (!addWorker(command, false))
            reject(command);
    }

（2)对于关联的代码，可以使用 @see 或者 {@link } 的方式，在代码中提供关联代码的快捷跳转方式。

    
    public void setCorePoolSize(int corePoolSize) {
        if (corePoolSize < 0 || maximumPoolSize < corePoolSize)
            throw new IllegalArgumentException();
        int delta = corePoolSize - this.corePoolSize;
        this.corePoolSize = corePoolSize;
        if (workerCountOf(ctl.get()) > corePoolSize)
            interruptIdleWorkers();
        else if (delta > 0) {
            // We don't really know how many new threads are "needed".
            // As a heuristic, prestart enough new workers (up to new
            // core size) to handle the current number of tasks in
            // queue, but stop if queue becomes empty while doing so.
            int k = Math.min(delta, workQueue.size());
            while (k-- > 0 && addWorker(null, true)) {
                if (workQueue.isEmpty())
                    break;
            }
        }
    }

（2）在日常业务开发中，非常推荐讲相关的文档、配置页面链接也放到注释中，极大方便后期维护。如：

    
    public void demo(){
        // 省略
    }

（4)对于工具类可以考虑讲给出常见的输入对应的输出。如 org.apache.commons.lang3.StringUtils#center(java.lang.String, int, char)

 
    public static String center(String str, final int size, final char padChar) {
        if (str == null || size <= 0) {
            return str;
        }
        final int strLen = str.length();
        final int pads = size - strLen;
        if (pads <= 0) {
            return str;
        }
        str = leftPad(str, strLen + pads / 2, padChar);
        str = rightPad(str, size, padChar);
        return str;
    }

（5) 对于废弃的方法，一定要注明废弃的原因，给出替代方案。如：java.security.Signature#setParameter(java.lang.String, java.lang.Object)

    
    @Deprecated
    public final void setParameter(String param, Object value)
            throws InvalidParameterException {
        engineSetParameter(param, value);
    }