简介：一份围绕HDFS编程实践的完整实验报告，面向正在学习Hadoop与大数据存储的本科生及入门开发者。资源系统梳理了HDFS在Hadoop体系结构中的角色，实验内容分为两大部分：一是通过hdfs dfs -put、-get、-ls、-rm、-copyFromLocal等Shell命令完成文件上传、下载、列表、复制与删除等常用操作；二是基于Hadoop Java API，利用FileSystem类实现文件的创建、写入、读取与删除，并附有Maven项目配置、关键代码片段和运行结果截图。报告同时包含实验目的、操作说明、实验总结与个人心得体会，可帮助读者深入理解分布式文件系统的设计思路和操作方式。资源共1个docx文档，压缩包大小323KB，适合用于课程实验参考、期末复习或自学HDFS操作。目前已有2910人学习，对快速掌握HDFS常用命令与Java编程接口有直接参考价值。
1. HDFS 编程实践：这份实验报告值得照着敲一遍
很多人在学 Hadoop 时都卡在同一点上：理论背得滚瓜烂熟，但一打开终端就不知道从哪里下手。这份《大数据实验二-HDFS 编程实践》是一份典型的实验报告，但价值恰恰在于它把抽象的分布式文件系统落到了具体的命令和代码上。它覆盖了两条主线路：一是 HDFS 常用 Shell 命令操作，二是用 Hadoop 官方 Java API 写文件操作程序。这两块是后续做 MapReduce、Spark 或者数据仓库项目时躲不开的基本功。适合刚装好 Hadoop 集群、准备从命令行过渡到编程阶段的初学者，也适合需要一份可参考模板来搭建自己实验流程的从业者。文中配置步骤和代码可以直接复现，踩坑点也不少，值得照着敲一遍再看细节。
2. HDFS Shell 命令：文件增删改查的完整命令清单与参数说明
HDFS 的 Shell 命令本质上是对分布式文件系统的 REST 操作封装，日常运维和实验中最常用的是文件创建、查看、上传、下载、删除和目录操作。这些命令的用法和 Linux 本地命令高度相似，但路径前缀不同，容易混淆。
2.1 创建文件并查看行数：touchz、cat 与正确路径前缀
实验第一步要求在 HDFS 上创建一个 text.txt 文件并查看它的行数。HDFS 没有类似 Linux 的 touch 命令，对应的是hdfs dfs -touchz，它创建一个空文件。查看行数可以用hdfs dfs -cat配合管道，也可以直接用wc -l。
# 在 HDFS 根目录创建空文件 hdfs dfs -touchz /text.txt # 查看文件内容并统计行数 hdfs dfs -cat /text.txt | wc -ltouchz命令的核心特征是创建一个零字节文件，如果文件已存在，它不会覆盖内容，而是保持原样。这在初始化实验文件时很实用。cat之后接管道统计行数，空文件返回 0，这是验证文件有没有建成功的第一个信号。注意这里的路径/text.txt是 HDFS 根目录路径，不要和 Linux 本地的/text.txt混淆。
2.2 追加内容到文件末尾：appendToFile 的两种写法
追加操作在 HDFS 上受到版本和副本策略限制，所以实验里单独验证这一步是必要的。常见的做法是用appendToFile把本地文件内容追加到 HDFS 文件末尾。
# 先把要追加的内容写到本地文件 echo "this is a test line" > /tmp/append.txt # 追加到 HDFS 文件的末尾 hdfs dfs -appendToFile /tmp/append.txt /text.txt # 验证内容 hdfs dfs -cat /text.txt这里容易踩的坑是 Hadoop 2.x 之后默认开启了 append 支持，但部分发行版在配置上会关闭该特性，报错信息通常是Append is not supported或Failed to replace a bad datanode。如果遇到这类报错，需要检查dfs.support.append配置项。另外，appendToFile只在文件末尾追加，不支持随机写入，这是 HDFS 设计上的一大限制。
2.3 创建文件夹并验证：mkdir -p 与 ls 的组合使用
创建目录用mkdir，如果要一次创建多级目录，必须加-p参数，否则会报父目录不存在的错误。
# 创建多级目录 hdfs dfs -mkdir -p /user/hadoop/experiment # 查看目录是否创建成功 hdfs dfs -ls /user/hadoop/ # 递归查看整个目录树 hdfs dfs -ls -R /user/hadoop/实验报告里要求“查看是否创建成功”，最直观的方式是ls，但只列出一级目录；如果需要确认多级路径都建好了，用-R递归列出全部内容。这里有个小技巧：创建目录后用hdfs dfs -ls -R看到的输出中，目录项以d开头，文件项以-开头，一眼就能区分是文件还是目录。
2.4 本地文件上传 HDFS：put 与 copyFromLocal 的选择
本地文件上传是实验的重点环节，Hadoop 提供了两个命令：put和copyFromLocal。功能上两者都一样，但copyFromLocal更强调来源是本地文件系统，阅读代码时语义更清晰。
# 在本地生成测试文件 echo "hello hadoop" > /tmp/local.txt # 上传到 HDFS 指定目录 hdfs dfs -put /tmp/local.txt /user/hadoop/experiment/ # 验证上传结果 hdfs dfs -ls /user/hadoop/experiment/put命令把本地文件复制到 HDFS，源文件保留，这一步在生产环境中常用于把日志或数据文件导入集群。参数顺序是“本地路径在前，HDFS 路径在后”，容易写反。另外，如果 HDFS 目标路径写的是目录名，文件会保存在该目录下；如果写的是带文件名的路径，则等价于重命名上传。
2.5 读取文件内容：cat、tail 与文本编码问题
上传完成后需要用cat读取内容来验证数据完整性。
# 读取完整文件内容 hdfs dfs -cat /user/hadoop/experiment/local.txt # 查看最后 1KB 内容 hdfs dfs -tail /user/hadoop/experiment/local.txtcat在遇到二进制文件时输出乱码，但实验中的文本文件没有这个问题。注意，HDFS 上默认编码是 UTF-8，如果本地文件是 GBK 编码，cat输出的中文内容会乱码。生产环境中建议统一使用 UTF-8 编码。
2.6 从 HDFS 拉取文件到本地：get 与 copyToLocal 的细节
下载操作与上传对应，使用get或copyToLocal，两者的差别仅仅是语义上的。
# 把 HDFS 文件拉取到本地当前目录 hdfs dfs -get /user/hadoop/experiment/local.txt /tmp/download.txt # 查看下载后的本地文件 cat /tmp/download.txtget命令下载时会校验文件块完整性，如果某个数据块损坏，会报Checksum Error。这是验证 HDFS 数据冗余机制的直接手段。下载路径如果省略，默认会保存到当前工作目录。
2.7 删除 HDFS 文件：rm 与回收站机制
删除操作是实验的收尾环节，HDFS 的rm用法和 Linux 几乎一致。
# 删除指定文件 hdfs dfs -rm /user/hadoop/experiment/local.txt # 删除空目录 hdfs dfs -rmdir /user/hadoop/experiment/ # 递归删除目录及内容 hdfs dfs -rm -r /user/hadoop/experiment/HDFS 从 0.21 版本开始支持回收站机制，默认情况下删除的文件会先进入/user/<用户名>/.Trash/目录，而不是立即物理删除。如果实验环境配置了回收站，删除后还能用hdfs dfs -ls /user/hadoop/.Trash/找回。这一点在生产环境是后悔药，实验中却容易让学生误以为文件已被彻底删除。
提示：在生产集群上，
rm -r是危险操作，建议删除前先用ls确认路径准确无误，再执行删除。
3. Java API 操作 HDFS：Maven 工程搭建与依赖版本避坑
Shell 命令是操作 HDFS 的“手脚”，Java API 则是更底层的能力。实验报告的第二部分要求通过 Intellij IDEA 创建 Maven 项目，导入 Hadoop 依赖后编写文件操作代码。这个环节的坑集中在依赖版本和配置类初始化上。
3.1 Maven 依赖导入：hadoop-client 与版本一致性
实验环境中 Hadoop 如果是 3.x，依赖用hadoop-client是最省事的，它会传递引入 HDFS、Common、YARN 等核心模块。
<dependencies> <dependency> <groupId>org.apache.hadoop</groupId> <artifactId>hadoop-client</artifactId> <version>3.3.4</version> </dependency> </dependencies>这里的关键是版本号必须和集群上安装的 Hadoop 版本保持一致。如果集群是 CDH 发行版，版本号通常是 3.0.0-cdh6.x.x，直接引入 Apache 版本会报协议或方法不兼容的错误。另一个细节是hadoop-client会引入大量传递依赖，首次下载较慢，建议配置阿里云 Maven 镜像加速。
3.2 FileSystem 初始化：Configuration 与文件系统地址
Java API 操作 HDFS 的核心是org.apache.hadoop.fs.FileSystem。它是一个抽象类，需要通过Configuration和文件系统 URI 来获取具体实例。
import org.apache.hadoop.conf.Configuration; import org.apache.hadoop.fs.FileSystem; import org.apache.hadoop.fs.Path; import java.net.URI; public class HdfsClient { public static void main(String[] args) throws Exception { // 创建 Configuration 对象，加载默认配置 Configuration conf = new Configuration(); // 指定 HDFS 的 NameNode 地址 String hdfsUri = "hdfs://localhost:9000"; // 获取 FileSystem 实例 FileSystem fs = FileSystem.get(URI.create(hdfsUri), conf, "hadoop"); System.out.println("FileSystem: " + fs.getUri()); // 操作完成后必须关闭资源 fs.close(); } }这里有三个参数值得注意：hdfsUri是 NameNode 的 RPC 地址，默认端口是 9000 或 8020，取决于安装配置；第三个参数是访问用户，如果不指定，默认使用本地系统用户名，这会导致权限不足。执行时如果本地用户不是 hadoop，会抛出Permission denied异常。
提示：代码中的
fs.close()不是可选项，不关闭连接会占用 ZooKeeper 会话和本地 socket 资源，在循环操作大量文件时会耗尽连接数。
4. 用 Java API 实现文件增删改查：核心方法与运行参数细节
这一章对应实验报告中的核心编码部分。完整代码由四个方法组成：创建文件、写入文件、读取文件、删除文件。每个方法都围绕FileSystem类展开，只是配合的流对象不同。
4.1 创建空文件：create 方法与权限参数
import org.apache.hadoop.fs.FileSystem; import org.apache.hadoop.fs.Path; import org.apache.hadoop.fs.FSDataOutputStream; public void createFile(FileSystem fs, String filePath) throws IOException { Path path = new Path(filePath); // 创建文件，如果已存在则覆盖 FSDataOutputStream out = fs.create(path, true); out.close(); System.out.println("文件创建成功: " + filePath); }create方法第二个参数true表示允许覆盖同名文件。如果不设置，默认是false，文件已存在时会抛出FileAlreadyExistsException。这里有个容易被忽略的细节：create并不会自动创建父目录，如果父目录不存在，需要先调用fs.mkdirs(path.getParent())，否则同样会报父目录缺失。
4.2 写入文件内容：FSDataOutputStream 的写入与 flush
import org.apache.hadoop.fs.FSDataOutputStream; public void writeFile(FileSystem fs, String filePath, String content) throws IOException { Path path = new Path(filePath); FSDataOutputStream out = fs.create(path, true); // 写入内容，getBytes 指定 UTF-8 编码 out.write(content.getBytes("UTF-8")); // 将缓冲数据刷新到数据节点 out.flush(); out.close(); System.out.println("文件写入成功"); }写入的content.getBytes("UTF-8")很容易遗漏编码参数，如果本地默认编码是 GBK，中文内容会乱码。flush的作用是把客户端缓冲区的数据推送到 HDFS 数据节点，在关闭流之前调用它可以减少数据丢失风险。注意：HDFS 的写入是追加式的，不支持随机写，所以这里的create实际上是覆盖整个文件。
4.3 读取文件内容：FSDataInputStream 与缓冲区大小
import org.apache.hadoop.fs.FSDataInputStream; public void readFile(FileSystem fs, String filePath) throws IOException { Path path = new Path(filePath); FSDataInputStream in = fs.open(path); byte[] buffer = new byte[1024]; int bytesRead; // 循环读取，直到文件末尾 while ((bytesRead = in.read(buffer)) > 0) { System.out.print(new String(buffer, 0, bytesRead, "UTF-8")); } in.close(); System.out.println(); }读取时缓冲区大小1024决定每次从数据节点拉取的数据量，调大可以提升大文件读取效率，但内存占用也会增加。FSDataInputStream支持seek操作，可以随机定位到某个 offset 读取，这在处理超大文件的某一段时很有用。实验中用while循环配合read方法，可以应对大小不定的文件。
4.4 删除文件：delete 方法与递归删除
import org.apache.hadoop.fs.FileSystem; import org.apache.hadoop.fs.Path; public void deleteFile(FileSystem fs, String filePath) throws IOException { Path path = new Path(filePath); // 第二个参数 true 表示递归删除，删除目录时必须设置 boolean result = fs.delete(path, true); if (result) { System.out.println("删除成功: " + filePath); } else { System.out.println("删除失败，文件不存在: " + filePath); } }delete的第二个参数recursive在使用上很容易踩坑：删除目录时如果不设置为true，会抛出IOException，提示目录非空。删除文件时该参数无影响。delete方法返回布尔值，文件不存在时返回false，但不会抛异常，所以通过返回值判断删除是否成功是更稳妥的做法。
4.5 main 方法与验证流程
public static void main(String[] args) throws Exception { Configuration conf = new Configuration(); FileSystem fs = FileSystem.get(URI.create("hdfs://localhost:9000"), conf, "hadoop"); HdfsFileOperator operator = new HdfsFileOperator(); String filePath = "/user/hadoop/experiment/test.txt"; // 按顺序验证四个方法 operator.createFile(fs, filePath); operator.writeFile(fs, filePath, "hello, hdfs java api"); operator.readFile(fs, filePath); operator.deleteFile(fs, filePath); fs.close(); }main 方法按“创建-写入-读取-删除”四步执行，符合实验报告的完整流程。运行时如果 README 提示Exception in thread main java.net.ConnectException: Connection refused，说明 NameNode 未启动或端口配置不对，先用jps查看是否包含NameNode进程。
5. 避坑排查：HDFS 实验中最常翻车的 5 个地方
做实训类项目时，真正的瓶颈通常不在代码逻辑，而在于环境和配置细节。这一章把 HDFS 实验里最容易翻车的问题集中列出来，每一条都按“现象 → 原因 → 解决”梳理清楚。
5.1 Permission denied：明明有权限却写不进文件
现象：执行hdfs dfs -mkdir或 Java API 写入时，抛出org.apache.hadoop.security.AccessControlException: Permission denied。
原因：HDFS 的权限检查基于 Linux 用户映射。本地用户是root或ubuntu，而 NameNode 执行的用户是hadoop，两者不一致。
解决：在 Java API 的FileSystem.get()第三个参数显式指定用户，比如"hadoop"。Shell 命令则可以临时切换用户执行，或者修改/etc/hadoop/conf/hdfs-site.xml中dfs.permissions.enabled为false，但生产环境不建议关权限。
5.2 Connection refused：NameNode 没起来或端口不对
现象：执行任何 HDFS 命令或 Java 程序时，报java.net.ConnectException: Connection refused或Call From ... to localhost:9000 failed on connection exception。
原因：SSH 登录到集群后只启动了 DataNode，NameNode 进程没有启动；或者实验环境修改过 RPC 端口，不再是默认的 9000。
解决：执行start-dfs.sh启动全部进程，再用jps确认NameNode、DataNode、SecondaryNameNode三个进程都在。如果启动后仍连不上，检查core-site.xml中fs.defaultFS的端口是否与代码里的 URI 一致。
5.3 文件明明上传了，本地却找不到
现象：执行hdfs dfs -put local.txt /tmp/返回成功，但到/tmp目录下找不到文件。
原因：混淆了 HDFS 路径和 Linux 本地路径。/tmp/在 HDFS 中是独立于 Linux 根目录的命名空间，文件并不在本地磁盘的/tmp下，而是在 DataNode 的dfs.data.dir目录中。
解决：用hdfs dfs -ls /tmp/在 HDFS 中查看。如果一定要确认文件在磁盘上，去dfs.data.dir配置的路径下找blk_开头的块文件。实验中最常用的办法是hdfs dfs -get拉取回本地再查看。
5.4 Append 报错或数据不追加
现象：appendToFile执行时提示Append is not supported，或追加后cat内容没有变化。
原因：HDFS 的追加功能在配置中被显式关闭，或者数据节点处于安全模式。部分实验镜像因为担心误操作，会在hdfs-site.xml中设置dfs.support.append为false。
解决：在hdfs-site.xml中添加<property><name>dfs.support.append</name><value>true</value></property>，重启 HDFS 使配置生效。追加前先用hdfs dfs -ls确认目标文件存在于正确路径，追加再次用cat验证，不要凭命令返回值判断。
5.5 Java 代码编译报错：Hadoop 类找不到
现象：IDEA 中代码全部标红，提示package org.apache.hadoop.conf does not exist，或者编译时报Could not resolve dependencies。
原因：Maven 依赖没有正确下载，常见于版本号不匹配、镜像源访问失败、IDEA 未重新导入 Maven 项目。
解决：在 Maven 仓库（默认~/.m2/repository）下查看org/apache/hadoop目录是否存在对应版本的 jar。如果没有，先在终端执行mvn clean install或mvn dependency:resolve手动拉取依赖，再回到 IDEA 点击 Maven 面板的刷新按钮。如果网络有限制，把settings.xml的镜像换成阿里云地址。
提示：上述前 4 条在真实集群环境里同样适用，最后一条主要针对本地开发环境调试。
6. 验证实验结果的两种手段：fsck 检查与重启后数据持久性确认
实验做完不是终点，验证结果是否可靠同样重要。HDFS 有专门的检查工具fsck，可以看到文件块的分布和副本健康状况。
# 检查 HDFS 上所有文件的块健康状态 hdfs fsck / -files -blocks -locations # 针对单个文件做深度检查 hdfs fsck /user/hadoop/experiment/test.txt -files -blocks -racksfsck输出中的Under-replicated状态表示副本数低于设定的dfs.replication，这种情况在实验环境中很常见，原因是只有一个 DataNode。Available关键字表示文件块可以被正常读取；如果出现CORRUPT，要立刻检查存储磁盘是否故障。执行fsck后会得到一行汇总：Status: HEALTHY或Status: CORRUPT，这是实验报告中值得截图保留的结果。
提示：
fsck只检查文件块完整性，不检查文件内容正确性。内容级校验需要手动比对cat输出。
第二个验证思路是重启后确认数据持久性。HDFS 设计目标是持久化存储，但如果 NameNode 保存的元数据损坏，数据节点上的块文件会变成孤儿块，文件无法正常读取。
# 重启 HDFS 进程 stop-all.sh start-all.sh # 重启后再次检查文件是否存在 hdfs dfs -ls /user/hadoop/experiment/ # 验证文件内容没有被损坏 hdfs dfs -cat /user/hadoop/experiment/test.txt重启后如果ls能看到文件且cat输出原内容，说明实验中上传、写入的文件已经在 HDFS 元数据和数据块上持久化保存。这一步骤模拟了生产环境中集群重启的场景，验证的是 NameNode 元数据恢复能力。
另外，如果要确认实验代码的健壮性，可以做一次断网模拟：在 Java 程序运行时拔掉有线连接或关闭 Wi-Fi，观察程序是否抛出异常。HDFS 客户端默认的dfs.client.socket-timeout是 60000 毫秒，超时后程序会报SocketTimeoutException，这时代码中的IOException捕获逻辑就起作用了。
把 HDFS 的实验从“跑通命令”提升到“验证结果可靠”这一步，才算真正把精力花在了刀刃上。我自己的习惯是：每次做完上传、下载、删除操作只后，强制用fsck过一遍文件块状态，再重启一次集群确认文件持久性，再进入下一个实验。如果跳过这两步，很多潜在问题会被带到 MapReduce 阶段，到时候排查的难度会大得多。希望这份拆解能帮你在 HDFS 编程实践上少走一些弯路。
本文还有配套的精品资源，点击获取
