简介一份围绕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 本地文件上传 HDFSput 与 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 操作 HDFSMaven 工程搭建与依赖版本避坑Shell 命令是操作 HDFS 的“手脚”Java API 则是更底层的能力。实验报告的第二部分要求通过 Intellij IDEA 创建 Maven 项目导入 Hadoop 依赖后编写文件操作代码。这个环节的坑集中在依赖版本和配置类初始化上。3.1 Maven 依赖导入hadoop-client 与版本一致性实验环境中 Hadoop 如果是 3.x依赖用hadoop-client是最省事的它会传递引入 HDFS、Common、YARN 等核心模块。dependencies dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-client/artifactId version3.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 的写入与 flushimport 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 refusedNameNode 没起来或端口不对现象执行任何 HDFS 命令或 Java 程序时报java.net.ConnectException: Connection refused或Call From ... to localhost:9000 failed on connection exception。原因SSH 登录到集群后只启动了 DataNodeNameNode 进程没有启动或者实验环境修改过 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中添加propertynamedfs.support.append/namevaluetrue/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 编程实践上少走一些弯路。本文还有配套的精品资源点击获取