【大数据存储与管理】分布式文件系统HDFS：07 HDFS编程实践

Ne0inhk

15 Mar 2026 — 20 min read

【作者主页】Francek Chen
【专栏介绍】 ⌈ ⌈ ⌈大数据技术原理与应用 ⌋ ⌋ ⌋专栏系统介绍大数据的相关知识，分为大数据基础篇、大数据存储与管理篇、大数据处理与分析篇、大数据应用篇。内容包含大数据概述、大数据处理架构Hadoop、分布式文件系统HDFS、分布式数据库HBase、NoSQL数据库、云数据库、MapReduce、Hadoop再探讨、数据仓库Hive、Spark、流计算、Flink、图计算、数据可视化，以及大数据在互联网领域、生物医学领域的应用和大数据的其他应用。
【GitCode】专栏资源保存在我的GitCode仓库：https://gitcode.com/Morse_Chen/BigData_principle_application。

文章目录

一、HDFS常用命令
二、HDFS的Web页面
三、HDFS常用Java API及应用实例
- （一）常用Java API介绍
- （二）应用实例
总结

本文介绍 Linux 操作系统中关于 HDFS 文件操作的常用 Shell 命令，利用 Web 页面查看和管理 Hadoop 文件系统，以及利用 Hadoop 提供的 Java API 进行基本的文件操作。这里采用的 Hadoop 版本为 3.1.3。

一、HDFS常用命令

HDFS 有很多 shell 命令，其中，fs 命令可以说是 HDFS 最常用的命令。利用该命令可以查看 HDFS 文件系统的目录结构、上传和下载数据、创建文件等。该命令的用法为：

hadoop fs [genericOptions][commandOptions]

备注：Hadoop 中有三种 Shell 命令方式：

hadoop fs 适用于任何不同的文件系统，比如本地文件系统和 HDFS 文件系统
hadoop dfs 只能适用于 HDFS 文件系统
hdfs dfs 跟 hadoop dfs 的命令作用一样，也只能适用于 HDFS 文件系统

具体如下。

hadoop fs -ls <path>。显示<path>指定的文件的详细信息。
hadoop fs -ls -R <path>。ls 命令的递归版本。
hadoop fs -cat <path>。将<path>指定的文件的内容输出到标准输出（stdout）。
hadoop fs -chgrp [-R] group <path>。将<path>指定的文件所属的组改为 group，使用-R 对<path>指定的文件夹内的文件进行递归操作。这个命令只适用于超级用户。
hadoop fs -chown [-R] [owner] [: [group]] <path>。改变<path>指定的文件所有者，-R 用于递归改变文件夹内的文件所有者。这个命令只适用于超级用户。
hadoop fs -chmod [-R] <mode> <path>。将<path>指定的文件的权限更改为<mode>。这个命令只适用于超级用户和文件所有者。
hadoop fs -tail [-f] <path>。将<path>指定的文件最后 1KB 的内容输出到标准输出（stdout）上，-f 选项用于持续检测新添加到文件中的内容。
hadoop fs -stat [format] <path>。以指定的格式返回<path>指定的文件的相关信息。当不指定 format 的时候，返回文件<path>的创建日期。
hadoop fs -touchz <path>。创建一个<path>指定的空文件。
hadoop fs -mkdir [-p] <paths>。创建<paths>指定的一个或多个文件夹，-p 选项用于递归创建子文件夹。
hadoop fs -copyFromLocal <localsrc> <dst>。将本地源文件<localsrc>复制到路径<dst>指定的文件或文件夹中。
hadoop fs -copyToLocal [-ignorecrc] [-crc] <target> <localdst>。将目标文件<target>复制到本地文件或文件夹<localdst>中，可用 -ignorecrc 选项复制 CRC 校验失败的文件，使用 -crc 选项复制文件以及 CRC 信息。
hadoop fs -cp <src> <dst>。将文件从源路径<src>复制到目标路径<dst>。
hadoop fs -du <path>。显示<path>指定的文件或文件夹中所有文件的大小。
hadoop fs -expunge。清空回收站，请参考 HDFS 官方文档以获取更多关于回收站特性的信息。
hadoop fs -get [-ignorecrc] [-crc] <src> <localdst>。复制<src>指定的文件到本地文件系统<localdst>指定的文件或文件夹，可用 -ignorecrc 选项复制 CRC 校验失败的文件，使用 -crc 选项复制文件以及 CRC 信息。
hadoop fs -getmerge [-nl] <src> <localdst>。对<src>指定的源目录中的所有文件进行合并，写入<localdst>指定的本地文件。-nl 是可选的，用于指定在每个文件结尾添加一个换行符。
hadoop fs -put <localsrc> <dst>。从本地文件系统中复制<localsrc>指定的单个或多个源文件到<dst>指定的目标文件系统中，也支持从标准输入（stdin）中读取输入并写入目标文件系统。
hadoop fs -moveFromLocal <localsrc> <dst>。与 put 命令功能相同，但是文件上传结束后会从本地文件系统中删除<localsrc>指定的文件。
hadoop fs -mv <src> <dest>。将文件从源路径<src>移动到目标路径<dst>。
hadoop fs -rm <path>。删除<path>指定的文件，只删除非空目录和文件。
hadoop fs -rm -r <path>。删除<path>指定的文件夹及其下的所有文件，-r 选项表示递归删除子目录。
hadoop fs -setrep [-R] <path>。改变<path>指定的文件的副本系数，-R 选项用于递归改变目录下所有文件的副本系数。
hadoop fs -test -[ezd] <path>。检查<path>指定的文件或文件夹的相关信息。不同选项的作用如下。
- ① -e 检查文件是否存在，如果存在则返回 0，否则返回 1。
- ② -z 检查文件是否是 0 字节，如果是则返回 0，否则返回 1。
- ③ -d 如果路径是个目录，则返回 1，否则返回 0。
hadoop fs -text <path>。将<path>指定的文件输出为文本格式，文件的格式也允许是 zip 和 TextRecordInputStream 等。

二、HDFS的Web页面

在配置好 Hadoop 集群之后，可以通过浏览器登录“http://[NameNodeIP]:9870”访问 HDFS，其中， [NameNodeIP] 表示名称节点的 IP 地址。例如我们在本地机器上完成Hadoop伪分布式安装后，可以登录“http://localhost:9870” 来查看文件系统信息（见图1）。

图1 查看文件系统信息

通过该 Web 页面，我们可以查看当前文件系统中各个节点的分布信息，浏览名称节点上的存储、登录等日志，以及下载某个数据节点上某个文件。该 Web 页面的所有功能都能通过 Hadoop 提供的 Shell 命令或者 Java API 来等价实现。例如通过 Web 页面中的“Browse the filesystem”查看目录。我们也可以通过如下命令实现同样的功能：

hadoop fs -ls/

三、HDFS常用Java API及应用实例

Hadoop 主要是使用 Java 语言编写实现的，Hadoop 不同的文件系统之间通过调用 Java API 进行交互。上面介绍的 Shell 命令，本质上就是 Java API 的应用。这里将介绍 HDFS 中进行文件上传、复制、下载等操作常用的 Java API 及其编程实例。

（一）常用Java API介绍

HDFS 编程的主要 Java API 如下。

org.apache.hadoop.fs.FileSystem。一个通用文件系统的抽象基类，可以被分布式文件系统继承。所有可能使用 Hadoop 文件系统的代码都要使用到这个类。Hadoop 为 FileSystem 这个抽象类提供了多种具体的实现，如 LocalFileSystem、 DistributedFileSystem、 HftpFileSystem、HsftpFileSystem、HarFileSystem、KosmosFileSystem、FtpFileSystem 和 NativeS3FileSystem 等。
org.apache.hadoop.fs.FileStatus。一个接口，用于向客户端展示系统中文件和目录的元数据，具体包括文件大小、块大小、副本信息、所有者、修改时间等，可通过 FileSystem.listStatus() 方法获得具体的实例对象。
org.apache.hadoop.fs.FSDataInputStream。文件输入流，用于读取 Hadoop 文件。
org.apache.hadoop.fs.FSDataOutputStream。文件输出流，用于写 Hadoop 文件。
org.apache.hadoop.conf.Configuration。访问配置项。所有的配置项的值，如果在 core-site.xml 中有对应的配置，则以 core-site.xml 为准。
org.apache.hadoop.fs.Path。用于表示 Hadoop 文件系统中的一个文件或者一个目录的路径。
org.apache.hadoop.fs.PathFilter。一个接口，通过实现方法 PathFilter.accept(Path path) 来判定是否接收路径 path 表示的文件或目录。

（二）应用实例

接下来通过一个简单的实例介绍上述 Java API 的使用方法。

1. 在Eclipse中创建项目

启动 Eclipse。当 Eclipse 启动以后，会弹出如下图2所示界面，提示设置工作空间（workspace）。

图2 设置Eclipse工作空间

可以直接采用默认的设置 “/home/hadoop/workspace”，点击“Launch”按钮。可以看出，由于当前是采用 hadoop 用户登录了 Linux 系统，因此，默认的工作空间目录位于 hadoop 用户目录 “/home/hadoop”。Eclipse 启动以后，会呈现如下图3所示的界面。

图3 Eclipse主界面

选择 “File->New->Java Project”菜单，开始创建一个 Java 工程，会弹出如下图4所示界面。

图4 创建一个Java工程

在“Project name”后面输入工程名称“HDFSExample”。选中“Use default location”，让这个 Java 工程的所有文件都保存到“/home/hadoop/workspace/HDFSExample”目录下。在“JRE”这个选项卡中，可以选择当前的 Linux 系统中已经安装好的 JDK，比如 jdk1.8.0_371。然后，点击界面底部的“Next>”按钮，进入下一步的设置。

2. 为项目添加需要用到的JAR包

进入下一步的设置以后，会弹出如下图5所示界面。

图5 Java工程设置

需要在这个界面中加载该 Java 工程所需要用到的 JAR 包，这些 JAR 包中包含了可以访问 HDFS 的 Java API。这些 JAR 包都位于 Linux 系统的 Hadoop 安装目录下。对于本文而言，就是在“/usr/local/hadoop/share/hadoop”目录下。点击界面中的“Libraries”选项卡。点击界面右侧的“Add External JARs…”按钮，会弹出如下图6所示界面。

图6 添加JAR包

在该界面中，上面的一排目录按钮（即“usr”、“local”、“hadoop”、“share”、“hadoop”和“common”），当点击某个目录按钮时，就会在下面列出该目录的内容。为了编写一个能够与 HDFS 交互的 Java 应用程序，一般需要向 Java 工程中添加以下 JAR 包：

“/usr/local/hadoop/share/hadoop/common”目录下的所有 JAR 包，包括 hadoop-common-3.3.5.jar、hadoop-common-3.3.5-tests.jar、haoop-nfs-3.3.5.jar、haoop-kms-3.3.5.jar 和 hadoop-registry-3.3.5.jar，注意，不包括目录 jdiff、lib、sources 和 webapps；
“/usr/local/hadoop/share/hadoop/common/lib”目录下的所有 JAR 包；
“/usr/local/hadoop/share/hadoop/hdfs”目录下的所有 JAR 包，注意，不包括目录 jdiff、lib、sources 和 webapps；
“/usr/local/hadoop/share/hadoop/hdfs/lib”目录下的所有 JAR 包。

如果要把“/usr/local/hadoop/share/hadoop/common”目录下的 hadoop-common-3.3.5.jar、hadoop-common-3.3.5-tests.jar、haoop-nfs-3.3.5.jar、haoop-kms-3.3.5.jar 和 hadoop-registry-3.3.5.jar 添加到当前的 Java 工程中：可以在界面中点击目录按钮，进入到 common 目录，然后，界面会显示出 common 目录下的所有内容（如图7所示）。

图7 common目录下的JAR包

请在界面中用鼠标点击选中 hadoop-common-3.3.5.jar、hadoop-common-3.3.5-tests.jar、haoop-nfs-3.3.5.jar、haoop-kms-3.3.5.jar 和 hadoop-registry-3.3.5.jar（不要选中目录jdiff、lib、sources和webapps），然后点击界面右下角的“确定”按钮，就可以把这两个 JAR 包增加到当前 Java 工程中，出现的界面如图8所示。

图8 部分JAR包设置完成

从这个界面中可以看出，hadoop-common-3.3.5.jar、hadoop-common-3.3.5-tests.jar、haoop-nfs-3.3.5.jar、haoop-kms-3.3.5.jar 和 hadoop-registry-3.3.5.jar 已经被添加到当前 Java 工程中。然后，按照类似的操作方法，可以再次点击“Add External JARs…”按钮，把剩余的其他 JAR 包都添加进来。需要注意的是，当需要选中某个目录下的所有 JAR 包时，可以使用“Ctrl+A”组合键进行全选操作。全部添加完毕以后，就可以点击界面右下角的“Finish”按钮，完成 Java 工程 HDFSExample 的创建。

3. 编写Java应用程序

下面编写一个 Java 应用程序，用来检测 HDFS 中是否存在一个文件。

请在 Eclipse 工作界面左侧的“Package Explorer”面板中（如下图9所示），找到刚才创建好的工程名称“HDFSExample”。然后在该工程名称上点击鼠标右键，在弹出的菜单中选择“New Class”菜单。

图9 Package Explorer面板

选择“New Class”菜单以后会出现如下图10所示界面。

图10 New Class菜单

在该界面中，只需要在“Name”后面输入新建的Java类文件的名称，这里采用名称“MergeFile”，其他都可以采用默认设置。然后，点击界面右下角“Finish”按钮，出现如下图11所示界面。

图11 新建Java类MergeFile

可以看出，Eclipse 自动创建了一个名为“MergeFile.java”的源代码文件，请在该文件中输入以下代码：

importjava.io.IOException;importjava.io.PrintStream;importjava.net.URI;importorg.apache.hadoop.conf.Configuration;importorg.apache.hadoop.fs.*;/** * 过滤掉文件名满足特定条件的文件 */classMyPathFilterimplementsPathFilter{String reg =null;MyPathFilter(String reg){this.reg = reg;}publicbooleanaccept(Path path){if(!(path.toString().matches(reg)))returntrue;returnfalse;}}/*** * 利用FSDataOutputStream和FSDataInputStream合并HDFS中的文件 */publicclassMergeFile{Path inputPath =null;//待合并的文件所在的目录的路径Path outputPath =null;//输出文件的路径publicMergeFile(String input,String output){this.inputPath =newPath(input);this.outputPath =newPath(output);}publicvoiddoMerge()throwsIOException{Configuration conf =newConfiguration(); conf.set("fs.defaultFS","hdfs://localhost:9000"); conf.set("fs.hdfs.impl","org.apache.hadoop.hdfs.DistributedFileSystem");FileSystem fsSource =FileSystem.get(URI.create(inputPath.toString()), conf);FileSystem fsDst =FileSystem.get(URI.create(outputPath.toString()), conf);//下面过滤掉输入目录中后缀为.abc的文件FileStatus[] sourceStatus = fsSource.listStatus(inputPath,newMyPathFilter(".*\\.abc"));FSDataOutputStream fsdos = fsDst.create(outputPath);PrintStream ps =newPrintStream(System.out);//下面分别读取过滤之后的每个文件的内容，并输出到同一个文件中for(FileStatus sta : sourceStatus){//下面打印后缀不为.abc的文件的路径、文件大小System.out.print("路径："+ sta.getPath()+" 文件大小："+ sta.getLen()+" 权限："+ sta.getPermission()+" 内容：");FSDataInputStream fsdis = fsSource.open(sta.getPath());byte[] data =newbyte[1024];int read =-1;while((read = fsdis.read(data))>0){ ps.write(data,0, read); fsdos.write(data,0, read);} fsdis.close();} ps.close(); fsdos.close();}publicstaticvoidmain(String[] args)throwsIOException{MergeFile merge =newMergeFile("hdfs://localhost:9000/user/hadoop/","hdfs://localhost:9000/user/hadoop/merge.txt"); merge.doMerge();}}

4. 编译运行程序

在开始编译运行程序之前，请一定确保 Hadoop 已经启动运行。然后，要确保 HDFS 的“/user/hadoop”目录下已经存在 file1.txt、file2.txt、file3.txt、file4.abc 和 file5.abc，每个文件里面有内容。这里，假设文件内容如下表1所示。

表1 HDFS目录下的文件内容

文件名称	文件内容
file1.txt	this is file1.txt
file2.txt	this is file2.txt
file3.txt	this is file3.txt
file4.abc	this is file4.abc
file5.abc	this is file5.abc

现在就可以编译运行上面编写的代码。可以直接点击 Eclipse 工作界面上部的运行程序的快捷按钮。当把鼠标移动到该按钮上时，在弹出的菜单中选择“Run As”，继续在弹出来的菜单中选择“Java Application”，如下图12所示。

图12 编译运行代码MergeFile.java

然后，会弹出如下图13所示界面。

图13 编译运行弹窗

在该界面中，点击界面右下角的“OK”按钮，开始运行程序。程序运行结束后，会在底部的“Console”面板中显示运行结果信息（如下图14所示）。同时，“Console”面板中还会显示一些类似“log4j:WARN…”的警告信息，可以不用理会。

图14 Console面板显示警告信息

如果程序运行成功，这时，可以到 HDFS 中查看生成的 merge.txt 文件，比如，可以在 Linux 终端中执行如下命令：

cd /usr/local/hadoop ./bin/hdfs dfs -ls/user/hadoop ./bin/hdfs dfs -cat/user/hadoop/merge.txt

可以看到如下结果：

this is file1.txt this is file2.txt this is file3.txt

5. 应用程序的部署

下面介绍如何把 Java 应用程序生成 JAR 包，部署到 Hadoop 平台上运行。

在 Hadoop 安装目录下新建一个名称为 myapp 的目录，用来存放我们自己编写的 Hadoop 应用程序，可以在 Linux 的终端中执行如下命令：

cd /usr/local/hadoop mkdir myapp

请在 Eclipse 工作界面左侧的“Package Explorer”面板中，在工程名称“HDFSExample”上点击鼠标右键，在弹出的菜单中选择“Export”，如图15所示。

图15 右键HDFSExample工程

然后，会弹出如下图所示界面。

图16 右键HDFSExample工程的弹窗

在该界面中，选择“Runnable JAR file”，然后，点击“Next>”按钮，弹出如下图17所示界面。

图17 选择Runnable JAR file

在该界面中，“Launch configuration”用于设置生成的 JAR 包被部署启动时运行的主类，需要在下拉列表中选择刚才配置的类“MergeFile-HDFSExample”。在“Export destination”中需要设置JAR包要输出保存到哪个目录，比如，这里设置为“/usr/local/hadoop/myapp/HDFSExample.jar”。在“Library handling”下面选择“Extract required libraries into generated JAR”。然后，点击“Finish”按钮，会出现如下图18所示界面。

图18 Runnable JAR File Export弹窗

可以忽略该界面的信息，直接点击界面右下角的“OK”按钮，启动打包过程。打包过程结束后，会出现一个警告信息界面，如下图19所示。

图19 Runnable JAR File Export弹窗警告

可以忽略该界面的信息，直接点击界面右下角的“OK”按钮。至此，已经顺利把 HDFSExample 工程打包生成了HDFSExample.jar。可以到 Linux 系统中查看一下生成的 HDFSExample.jar 文件，可以在 Linux 的终端中执行如下命令：

cd /usr/local/hadoop/myapp ls

可以看到，“/usr/local/hadoop/myapp”目录下已经存在一个 HDFSExample.jar 文件。

由于之前已经运行过一次程序，已经生成了 merge.txt，因此，需要首先执行如下命令删除该文件：

cd /usr/local/hadoop ./bin/hdfs dfs -rm/user/hadoop/merge.txt

现在，就可以在 Linux 系统中，使用 hadoop jar 命令运行程序，命令如下：

cd /usr/local/hadoop ./bin/hadoop jar ./myapp/HDFSExample.jar

上面程序执行结束以后，可以到 HDFS 中查看生成的 merge.txt 文件，比如，可以在 Linux 终端中执行如下命令：

cd /usr/local/hadoop ./bin/hdfs dfs -ls/user/hadoop ./bin/hdfs dfs -cat/user/hadoop/merge.txt

可以看到如下结果：

this is file1.txt this is file2.txt this is file3.txt

总结

本文详细介绍了在 Linux 操作系统中使用 HDFS 的常用方法，包括通过 Shell 命令操作 HDFS，通过 Web 页面查看和管理 HDFS，以及使用 Java API 进行 HDFS 文件操作。对于 Shell 命令，介绍了 hadoop fs、hadoop dfs 和 hdfs dfs 三种方式，并列出了常用的文件操作命令如 ls、cat、mkdir、cp、mv、rm 等。通过 Web 页面，可以直观地查看和管理 HDFS 文件系统。对于 Java API，介绍了主要的类如 FileSystem、FileStatus、FSDataInputStream 和 FSDataOutputStream，并提供了一个合并 HDFS 文件的实例，详细讲解了从创建项目、添加 JAR 包、编写代码到部署运行的整个过程。