小代码大智慧： FilenameUtils.getName 函数分析
Posted 明明如月学长
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了小代码大智慧： FilenameUtils.getName 函数分析相关的知识，希望对你有一定的参考价值。
一、背景
最近用到了 org.apache.commons.io.FilenameUtils#getName 这个方法，该方法可以传入文件路径，获取文件名。
简单看了下源码，虽然并不复杂，但和自己设想略有区别，值得学习，本文简单分析下。
二、源码分析
org.apache.commons.io.FilenameUtils#getName
/**
* Gets the name minus the path from a full fileName.
* <p>
* This method will handle a file in either Unix or Windows format.
* The text after the last forward or backslash is returned.
*
<pre>
* a/b/c.txt --> c.txt
* a.txt --> a.txt
* a/b/c --> c
* a/b/c/ --> ""
* </pre>
* <p>
* The output will be the same irrespective of the machine that the code is running on.
*
* @param fileName the fileName to query, null returns null
* @return the name of the file without the path, or an empty string if none exists.
* Null bytes inside string will be removed
*/
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
/**
* Checks the input for null bytes, a sign of unsanitized data being passed to to file level functions.
*
* This may be used for poison byte attacks.
*
* @param path the path to check
*/
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) 源码：
/**
* Returns the index within this string of the first occurrence of
* the specified character. If a character with value
* @code ch occurs in the character sequence represented by
* this @code String object, then the index (in Unicode
* code units) of the first such occurrence is returned. For
* values of @code ch in the range from 0 to 0xFFFF
* (inclusive), this is the smallest value <i>k</i> such that:
* <blockquote><pre>
* this.charAt(<i>k</i>) == ch
* </pre></blockquote>
* is true. For other values of @code ch, it is the
* smallest value <i>k</i> such that:
* <blockquote><pre>
* this.codePointAt(<i>k</i>) == ch
* </pre></blockquote>
* is true. In either case, if no such character occurs in this
* string, then @code -1 is returned.
*
* @param ch a character (Unicode code point).
* @return the index of the first occurrence of the character in the
* character sequence represented by this object, or
* @code -1 if the character does not occur.
*/
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
/**
* Returns the index of the last directory separator character.
* <p>
* This method will handle a file in either Unix or Windows format.
* The position of the last forward or backslash is returned.
* <p>
* The output will be the same irrespective of the machine that the code is running on.
*
* @param fileName the fileName to find the last path separator in, null returns -1
* @return the index of the last separator character, or -1 if there
* is no such character
*/
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
/**
* Executes the given task sometime in the future. The task
* may execute in a new thread or in an existing pooled thread.
*
* If the task cannot be submitted for execution, either because this
* executor has been shutdown or because its capacity has been reached,
* the task is handled by the current @link RejectedExecutionHandler.
*
* @param command the task to execute
* @throws RejectedExecutionException at discretion of
* @code RejectedExecutionHandler, if the task
* cannot be accepted for execution
* @throws NullPointerException if @code command is null
*/
public void execute(Runnable command)
if (command == null)
throw new NullPointerException();
/*
* Proceed in 3 steps:
*
* 1. If fewer than corePoolSize threads are running, try to
* start a new thread with the given command as its first
* task. The call to addWorker atomically checks runState and
* workerCount, and so prevents false alarms that would add
* threads when it shouldn't, by returning false.
*
* 2. If a task can be successfully queued, then we still need
* to double-check whether we should have added a thread
* (because existing ones died since last checking) or that
* the pool shut down since entry into this method. So we
* recheck state and if necessary roll back the enqueuing if
* stopped, or start a new thread if there are none.
*
* 3. If we cannot queue task, then we try to add a new
* thread. If it fails, we know we are shut down or saturated
* and so reject the task.
*/
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 的方式，在代码中提供关联代码的快捷跳转方式。
/**
* Sets the core number of threads. This overrides any value set
* in the constructor. If the new value is smaller than the
* current value, excess existing threads will be terminated when
* they next become idle. If larger, new threads will, if needed,
* be started to execute any queued tasks.
*
* @param corePoolSize the new core size
* @throws IllegalArgumentException if @code corePoolSize < 0
* or @code corePoolSize is greater than the @linkplain
* #getMaximumPoolSize() maximum pool size
* @see #getCorePoolSize
*/
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）在日常业务开发中，非常推荐讲相关的文档、配置页面链接也放到注释中，极大方便后期维护。
如：
/**
* 某某功能
*
* 相关文档：
* <a href="https://blog.csdn.net/w605283073">设计文档</a>
* <a href="https://blog.csdn.net/w605283073">三方API地址</a>
*/
public void demo()
// 省略
（4)对于工具类可以考虑讲给出常见的输入对应的输出。
如 org.apache.commons.lang3.StringUtils#center(java.lang.String, int, char)
/**
* <p>Centers a String in a larger String of size @code size.
* Uses a supplied character as the value to pad the String with.</p>
*
* <p>If the size is less than the String length, the String is returned.
* A @code null String returns @code null.
* A negative size is treated as zero.</p>
*
* <pre>
* StringUtils.center(null, *, *) = null
* StringUtils.center("", 4, ' ') = " "
* StringUtils.center("ab", -1, ' ') = "ab"
* StringUtils.center("ab", 4, ' ') = " ab "
* StringUtils.center("abcd", 2, ' ') = "abcd"
* StringUtils.center("a", 4, ' ') = " a "
* StringUtils.center("a", 4, 'y') = "yayy"
* </pre>
*
* @param str the String to center, may be null
* @param size the int size of new String, negative treated as zero
* @param padChar the character to pad the new String with
* @return centered String, @code null if null String input
* @since 2.0
*/
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)
/**
* 省略部分
*
* @see #getParameter
*
* @deprecated Use
* @link #setParameter(java.security.spec.AlgorithmParameterSpec)
* setParameter.
*/
@Deprecated
public final void setParameter(String param, Object value)
throws InvalidParameterException
engineSetParameter(param, value);
四、总结
很多优秀的开源项目的代码设计都非常严谨，往往简单的代码中也蕴藏着缜密的思考。
我们有时间可以看看一些优秀的开源项目，可以从简单的入手，可以先想想如果自己写大概该如何实现，然后和作者的实现思路对比，会有更大收获。
平时看源码时，不仅要知道源码长这样，更要了解为什么这么设计。
创作不易，如果本文对你有帮助，欢迎点赞、收藏加关注，你的支持和鼓励，是我创作的最大动力。
参考文章
《What does it mean to have a “file name with NULL bytes in serialized instances”?》
相关文章推荐
以上是关于小代码大智慧： FilenameUtils.getName 函数分析的主要内容，如果未能解决你的问题，请参考以下文章
小代码大智慧： FilenameUtils.getName 函数分析