HDFS编程实践入门：从Java API调用到底层读写流程全解析

不少人在学HDFS的时候，都会卡在同一个地方：命令操作敲得飞起，hdfs dfs -put、-get、-ls用得很熟，但一到"编程实践"这四个字就懵了——API怎么调？配置怎么加载？写进去的数据到底走了一条什么路？这篇博客就围绕HDFS编程实践展开，把从环境准备、Java API核心操作到底层读写流程的完整链路捋一遍，重点讲清楚代码背后的数据流转逻辑，以及我在实际实训和项目中踩过的坑。适合刚学完HDFS基础命令、准备迈入编程阶段的大数据学习者，也适合做HDFS和MapReduce综合实训时想补一补底层的同学。

1. 为什么"会敲命令"不等于"会编程"——先搞清楚HDFS客户端编程的定位

1.1 命令操作和API编程的分界线在哪里

先问一个问题：hdfs dfs -put local.txt /data这条命令，背后到底是什么？

答案是一个Java程序调用了一组API。HDFS自带的hdfs命令行工具本身就是用Java写的客户端，它内部调用的是FileSystem、FSDataOutputStream这些类。也就是说，命令操作其实是别人已经帮你写好的API调用，而编程实践要做的事情，是把这层"壳"揭开，自己直接用Java去跟NameNode和DataNode打交道。

这两者之间隔着一条分界线：命令操作处理的是"文件这个整体"，而API编程处理的是"字节流、文件块、元数据、管道"这些更底层的东西。举个例子，你用hdfs dfs -put上传一个200MB的文件，你看到的是"文件上传成功"；但如果你要在代码里实现同样的上传，你必须明白：这个200MB的文件会被切成多少个块（默认128MB，所以是2个块），每个块又会被复制到几个DataNode（默认3副本），客户端是先把数据写到第一个DataNode、再由它转发给第二个，还是客户端自己一个一个地写——这个细节在API编程里直接关系到你的代码性能和正确性。这就是为什么各大实训平台（包括相关的头歌实训）在讲完"命令操作"之后，总要单开一节"编程实践"。

1.2 编程实践在整个HDFS学习路径中的位置

我的建议是，HDFS的学习路径可以分四步走：

1. 体系认知：了解HDFS是什么、架构里有哪几个角色（NameNode、DataNode、SecondaryNameNode）、它解决什么问题。
2. 命令操作：用命令行熟悉文件增删改查、权限管理、块报告。这是让你快速建立"手感"的阶段。
3. 编程实践：用Java API把命令操作重新实现一遍，重点理解读写流程、容错机制。
4. 进阶应用：把HDFS作为存储底座，在其上跑MapReduce、Hive、Spark等计算框架。

编程实践正好卡在第二步和第四步之间。它既是验证架构理解的手段，也是后续所有计算框架的基础。你后面写MapReduce作业，FileInputFormat.addInputPath(job, new Path(args[0]))这一行代码，底层就是今天要讲的HDFS客户端API在帮你读文件。换句话说，MapReduce综合实训能不能跑顺，很大程度上取决于你对HDFS编程实践的掌握深度。

1.3 动手前需要具备的基础知识

在进入代码之前，有几个前置知识我建议先复习一下，不然写代码的时候很容易一头雾水：

• HDFS架构：NameNode管元数据（文件路径、块列表、副本位置），DataNode管实际数据。客户端不直接跟NameNode传数据，只传请求。
• 块（Block）：默认128MB，一个文件被拆成若干个块，每个块多个副本分布在不同的DataNode上。
• 副本放置策略：第一个副本放在客户端所在的节点（如果客户端在集群外，则随机挑一个不太忙的节点），第二个副本放在不同机架，第三个副本放在与第二个相同机架的不同节点。
• RPC机制：客户端和NameNode之间走的是RPC协议，也就是Java接口调用。理解了这一点，你就知道为什么FileSystem对象在你调用mkdirs的时候，实际上是在远程调用NameNode的方法。

这些概念不需要背得滚瓜烂熟，但至少要在大脑里有画面。接下来进入实操部分。

2. 环境准备：我推荐的HDFS编程最小可行环境

2.1 三种常见环境的选择思路

HDFS编程不是非得搭一个三节点集群才能练，根据自己的条件选就行。我梳理一下三种环境，你们对号入座。

第一种：在线实训环境（头歌等平台）。如果你正在做头歌的分布式文件系统HDFS实训，那么环境通常已经帮你配好了，Java和Hadoop依赖也集成在项目里。这种环境的好处是零配置、开箱即用，缺点是你没法做环境层面的排查训练。用这种环境的话，你直接把注意力放在API代码本身，别花时间纠结环境问题。

第二种：本地伪分布式。在自己的机器上装一个Hadoop，配置成伪分布式模式，也就是所有守护进程都在本机跑。这是我最推荐的练习方式，因为既能体验完整的集群交互流程，又不用维护多台机器。伪分布式下，fs.defaultFS通常是hdfs://localhost:9000，你在代码里连的就是这个地址。

第三种：远程真实集群。公司或学校提供的集群。这种环境的坑最多：网络权限、Kerberos认证、队列资源限制。初学者不建议一上来就搞这种，容易在环境问题上消磨掉信心。

2.2 Java工程怎么搭

不管哪种环境，代码工程本身是标准的Maven Java项目。我习惯用一个单独的模块来写HDFS客户端代码。下面是我常用的pom.xml核心依赖：

<properties> <hadoop.version>3.3.6</hadoop.version> </properties> <dependencies> <dependency> <groupId>org.apache.hadoop</groupId> <artifactId>hadoop-client</artifactId> <version>${hadoop.version}</version> </dependency> </dependencies>

hadoop-client这个依赖是聚合包，会把hadoop-common、hadoop-hdfs、hadoop-mapreduce-client-core等都带进来，做客户端开发完全够用。如果你的集群是CDH或HDP发行版，版本号要跟集群保持一致，否则可能出现RPC协议不兼容的问题。这个坑我后面细说。

2.3 关键配置：fs.defaultFS和core-site.xml

写HDFS客户端代码，最容易被忽略但最核心的配置就是fs.defaultFS。这个参数决定了你的FileSystem对象到底连哪里。

有两种设置方式：

// 方式一：代码里直接设置 Configuration conf = new Configuration(); conf.set("fs.defaultFS", "hdfs://localhost:9000"); FileSystem fs = FileSystem.get(conf); // 方式二：读取classpath下的core-site.xml // 把hadoop的core-site.xml放到src/main/resources下，然后： Configuration conf = new Configuration(); FileSystem fs = FileSystem.get(conf);

方式二依赖Classpath里存在core-site.xml。如果你用的是本地伪分布式，可以把Hadoop安装目录下的core-site.xml和hdfs-site.xml复制到项目的resources目录里，这样代码里就不用硬编码地址了。

有一个常见的误解必须纠正：FileSystem.get(conf)返回的对象并不一定是HDFS客户端。如果fs.defaultFS没配置，它会默认使用file:///，也就是本地文件系统。很多同学代码写半天，最后发现文件传到了本地磁盘而不是HDFS，原因就是这里——看起来new Path("/data/input")是个根路径，实际上它指向的是Linux的根目录。判断自己连的是不是HDFS有一个笨办法：打印一下fs.getUri()，输出file:///就说明你连错地方了，hdfs://localhost:9000才是对的。

2.4 环境验证：从一段最简代码开始

环境是否就绪，用一段最简代码验证最快。我先写一个获取FileSystem并打印工作目录的程序，跑通之后再逐步叠加功能。

import org.apache.hadoop.conf.Configuration; import org.apache.hadoop.fs.FileSystem; public class HdfsConnectTest { public static void main(String[] args) throws Exception { Configuration conf = new Configuration(); conf.set("fs.defaultFS", "hdfs://localhost:9000"); FileSystem fs = FileSystem.get(conf); System.out.println("Connected to: " + fs.getUri()); System.out.println("Working directory: " + fs.getWorkingDirectory()); fs.close(); } }

如果输出如下内容，说明环境OK：

Connected to: hdfs://localhost:9000 Working directory: hdfs://localhost:9000/user/root

如果输出Connected to: file:///，回到小节2.3检查fs.defaultFS。这一步虽然简单，但至少能帮你省掉后面两小时的无效调试。

3. Java API实操：五个绕不开的入门操作

3.1 操作前先认识核心类

HDFS的Java API，核心类其实很少，掰着手指头数也就这几个：

• Configuration：配置容器，承载fs.defaultFS、DFS副本数等相关配置。
• FileSystem：分布式文件系统的抽象基类，所有文件操作都从它发起。它是门面类，背后封装了对NameNode的RPC调用和对DataNode的数据传输。
• Path：文件或目录的路径表示，可以是hdfs://localhost:9000/user/data这种全路径，也可以是/user/data这种相对HDFS根目录的路径。
• FSDataInputStream/FSDataOutputStream：HDFS的文件输入/输出流，分别继承自DataInputStream和DataOutputStream，支持随机读（seek）和带缓冲的写。

搞清楚了这五个类之间的关系，HDFS编程就算入门一半了。后面所有的操作，无非是围绕它们排列组合。

3.2 创建目录：mkdirs背后的RPC调用

第一个操作从最简单的开始：创建目录。

import org.apache.hadoop.conf.Configuration; import org.apache.hadoop.fs.FileSystem; import org.apache.hadoop.fs.Path; public class MkdirDemo { public static void main(String[] args) throws Exception { Configuration conf = new Configuration(); conf.set("fs.defaultFS", "hdfs://localhost:9000"); FileSystem fs = FileSystem.get(conf); Path dir = new Path("/user/bigdata/hdfs-practice"); boolean success = fs.mkdirs(dir); System.out.println("Create directory result: " + success); fs.close(); } }

mkdirs是递归创建的，也就是说中间任何一级目录不存在，它都会一并创建，行为类似Linux的mkdir -p。这个方法的返回值是布尔值，但我见过的绝大多数代码都没检查这个返回值——这其实是个坏习惯。如果目录创建失败，你是希望程序静默通过，还是立刻抛异常让调用方感知？我通常这样写：

if (!fs.mkdirs(dir)) { throw new RuntimeException("Failed to create directory: " + dir); }

3.3 上传文件：copyFromLocalFile的两种重载

文件上传是使用频率最高的操作。copyFromLocalFile有两个最常用的重载：

// 重载1：不删除本地源文件，不覆盖HDFS目标文件 fs.copyFromLocalFile(new Path("D:/data/test.txt"), new Path("/user/bigdata/")); // 重载2：控制是否删除源文件、是否覆盖目标 // delSrc：是否删除本地原文件 // overwrite：是否覆盖HDFS上已存在的同名文件 fs.copyFromLocalFile(false, true, new Path("D:/data/test.txt"), new Path("/user/bigdata/test.txt"));

请注意重载1的语义：目标路径写的是目录，那就把test.txt放进去；目标路径写的是完整文件名，那就以这个文件名落盘。而重载2第4个参数必须是文件路径而不是目录，如果写成目录名会把目录本身当作文件名。这个细节容易搞混，我已经见过至少三个同学在这里把文件传成一个奇怪的名字。

上传时文件已经存在该怎么办？如果overwrite没开，程序会抛FileAlreadyExistsException，这是正常保护机制。所以如果你要覆盖写，一定要显式传true。

3.4 下载文件：copyToLocalFile与随机读

下载文件的API长这样：

fs.copyToLocalFile(new Path("/user/bigdata/test.txt"), new Path("D:/data/download/"));

这里有个细节很多人第一次都会翻车：copyToLocalFile的第二个参数是本地目标路径，如果这个目录本身不存在，不会自动创建，而且如果本地目标已存在同名文件，默认会失败。另外，HDFS 3.x中copyToLocalFile默认不会把文件的副本数、权限等元数据带过来，它只负责把数据本身拖下来。

除了整体下载，HDFS还支持随机读。什么叫随机读？就是你可以像在本地文件里用seek定位一样，在HDFS文件里直接跳到某个offset读取。这个特性是FSDataInputStream.seek()提供的，MapReduce处理大文件分片时靠的就是它。

import org.apache.hadoop.fs.FSDataInputStream; FSDataInputStream in = fs.open(new Path("/user/bigdata/test.txt")); in.seek(100); // 跳到偏移量100字节处 byte[] buffer = new byte[50]; int read = in.read(buffer); // 从100字节处往后读50字节 System.out.println(new String(buffer, 0, read, "UTF-8")); in.close();

注意fs.open()打开的是FSDataInputStream，它跟普通的Java输入流不同的地方就在于多了一个seek能力。你可以把HDFS上的一个文件理解为一个巨大的字节数组，随机读就是在这个数组上任意定位。

3.5 遍历目录和查看文件状态

遍历目录是排查数据的必备操作。listStatus返回的是一个FileStatus数组，每个FileStatus包含路径、大小、块大小、副本数、修改时间、owner等元数据。

import org.apache.hadoop.fs.FileStatus; FileStatus[] statuses = fs.listStatus(new Path("/user/bigdata")); for (FileStatus status : statuses) { String type = status.isDirectory() ? "DIR" : "FILE"; System.out.printf("%s %d %s%n", type, status.getLen(), status.getPath()); }

这里有个使用技巧：如果你只想要文件不想要目录，用FileSystem.listFiles(path, recursive)，它返回的是RemoteIterator<LocatedFileStatus>，而LocatedFileStatus是FileStatus的子类，额外带块位置信息（getBlockLocations）。想知道"某个文件的块分布在哪些DataNode上"，就是靠它拿到的。

import org.apache.hadoop.fs.LocatedFileStatus; import org.apache.hadoop.fs.RemoteIterator; RemoteIterator<LocatedFileStatus> iter = fs.listFiles(new Path("/user/bigdata"), true); while (iter.hasNext()) { LocatedFileStatus status = iter.next(); System.out.println("File: " + status.getPath() + ", length: " + status.getLen()); System.out.println("Block locations: " + String.join(",", status.getBlockLocations()[0].getHosts())); }

listFiles的第二个参数recursive如果传true，会递归遍历所有子目录，非常实用。

下面把这个五个操作对应的API整理成一个速查表，方便你复制到代码注释里：

4. 读写流程深度拆解：客户端代码背后的数据流转

4.1 写入流程：一个字节从客户端到三个副本的旅程

如果你只是调用fs.copyFromLocalFile，看不到底层发生了什么。但如果你改用流式API手动写文件，整个过程就暴露出来了：

import org.apache.hadoop.fs.FSDataOutputStream; FSDataOutputStream out = fs.create(new Path("/user/bigdata/stream-test.txt")); out.writeUTF("Hello HDFS, this is a stream write test.\n"); out.hflush(); out.close();

这五行代码背后，HDFS完成了一整套复杂的协调流程。我用四个阶段来拆解：

阶段一：客户端请求NameNode创建文件。客户端调用fs.create，底层通过RPC向NameNode发送create请求。NameNode收到请求后会做一系列校验：父目录是否存在、是否有权限、同名文件是否存在（取决于你传的overwrite参数）。校验通过后，NameNode在内存中创建文件元数据，文件状态是UNDER_CONSTRUCTION，也就是"正在被写入"，此时文件还没有任何块分配。

阶段二：申请块和选择副本节点。客户端开始写数据时，会向NameNode申请新的块。NameNode根据副本放置策略，返回一个LocatedBlock，里面包含了这个块要写入的DataNode列表。比如默认3副本，返回的就是[dn1, dn2, dn3]这样的有序列表，dn1叫"主DataNode"，dn2、dn3叫"次DataNode"。

阶段三：建立管道（Pipeline），逐级传输数据。客户端不会自己把数据分别发给三个DataNode，而是跟dn1建立连接，dn1再连接dn2，dn2再连接dn3，形成一条管道。客户端把数据包按顺序发给dn1，dn1一边落盘一边转发给dn2，dn2也一边落盘一边转发给dn3。这样做的目的是减少客户端网络连接数，让数据在机架内/机架间以最快路径传播。

这里有个关键点：每个数据包（默认64KB）在管道里走一圈之后，dn3写完会返回一个ack给dn2，dn2返给dn1，dn1最终返给客户端。只有收到这个ack链，客户端才确认这个包写成功了。这也是HDFS"写不成功就重传"的基础。如果某个DataNode中途挂了，管道会断裂，客户端会收到异常，然后重新向NameNode申请新的DataNode，把未确认的数据包重写一遍。这也是为什么写大文件时偶尔看到"慢节点"会影响整体速度——整条管道的速度由最慢的那个DataNode决定。

阶段四：关闭文件，提交元数据。等所有包都写完，客户端调用close，NameNode收到"文件写入完成"的信号，把文件状态从UNDER_CONSTRUCTION改成COMPLETE，并记录所有块信息。此时文件才对外可见。如果你在调用close之前去读这个文件，是读不到的，只能看到一个长度为0的文件占位。

4.2 读取流程：客户端怎么找到数据

读取流程比写入简单不少，但有一个极易被忽略的设计。

调用fs.open(Path)后，客户端向NameNode请求读取文件。NameNode返回给客户端的并不是文件内容，而是文件所有块的元数据以及每个块所在的DataNode列表。比如一个文件有3个块，NameNode返回的可能是：

Block 1 -> [dn1, dn2, dn3] Block 2 -> [dn3, dn1, dn2] Block 3 -> [dn2, dn3, dn1]

客户端拿到这个列表之后，会为每个块单独选择"最优"的DataNode去读数据。怎么判断最优？一是看网络距离最近（比如客户端就在dn2这台机器上，那么包含dn2的块优先从dn2本地读），二是看负载情况。这就是所谓的数据本地性（Data Locality）的雏形。MapReduce框架里的"计算移动比数据移动便宜"这句话，底层依赖的就是这个读取机制。

读取的时候还有一个细节：客户端跟NameNode的通信只发生在open阶段——拿到块位置列表之后，后续的数据传输完全跟NameNode没关系了，全部是客户端直接跟DataNode建立socket连接读取数据。这意味着即使NameNode繁忙，也不影响大文件的持续读取吞吐。

4.3 这些流程在代码里的体现

现在回头再看copyFromLocalFile，你应该能理解它内部为什么是"先读本地文件，再通过DFSOutputStream写入HDFS"了。

fs.create返回的FSDataOutputStream内部，实际上维护着一个DFSOutputStream组件，它管着几件事：把数据切分成chunk并打包、在内存中维护待发送的数据包队列、给每个数据包编号、处理管道的ack超时重传。你在代码里调用out.write(bytes)，其实就是往这个打包流水线上丢数据；调用out.hflush()，则是把缓冲在客户端的数据包全部推送到管道里但不关闭流；调用out.close()，才是真正把文件从UNDER_CONSTRUCTION推成COMPLETE。

我在很多项目里见过别人写上传代码时只在最后调close，中途大量write之后不flush。小文件没问题，大文件会有隐患：如果程序在close之前崩溃，缓冲的数据全部丢失，NameNode侧只保留一个空壳元数据。所以经验是：大文件写入时每隔一段时间调用一次hflush，宁可牺牲少量吞吐，也要换取数据可见性。当然，hsync比hflush更强，它保证数据真正落到磁盘而不是OS缓存，但代价是性能明显下降。默认场景用hflush就够。

5. 实操血泪史：五个高频踩坑点与排查路径

5.1 花式连错文件系统：file:///还是hdfs://

这个问题我在前面已经提过，但因为太常见，值得专门展开一次完整的排查过程。

现象：写了一个上传程序，代码里用的是new Path("/input/data.txt")，程序跑完没报错，但hdfs dfs -ls /input什么都看不到。

排查链路：

1. 先怀疑路径问题，实际上/input这种路径没问题。
2. 在代码里打印fs.getUri()，发现是file:///。此时可以断定，Configuration中的fs.defaultFS没有被设置，或者你的core-site.xml根本没被加载。
3. 查Maven依赖，确认hadoop-client已在pom中。
4. 查classpath，确认core-site.xml在src/main/resources下。
5. 最终定位：代码中new Configuration()加载的资源列表里没有core-site.xml。

根因：FileSystem.get(conf)在fs.defaultFS缺失时默认file:///。这是Hadoop的默认行为，不是bug。

解决：要么代码里显式conf.set("fs.defaultFS", "hdfs://localhost:9000")；要么把core-site.xml放进classpath。两者都做也行，代码里的设置优先级更高。

5.2 权限被拒：Permission denied的真正原因

现象：在Linux上用root启动的NameNode，在Windows的Eclipse里跑客户端，报Permission denied: user=Administrator, access=WRITE, inode="/user/root":root:supergroup:drwxr-xr-x。

排查链路：

1. 看到user=Administrator就明白了——HDFS客户端会把本地用户名传给NameNode做权限校验，Windows下发的是Administrator，而HDFS上的/user/root目录owner是root，权限只有rwxr-xr-x，其他用户只能读和执行，不能写。
2. 解决方案有两个方向：一是换一个你有权限的目录（比如/user/Administrator），二是配置HADOOP_USER_NAME环境变量，让客户端伪装成root。

在IDEA里给运行配置加环境变量是最快的：

Name: HADOOP_USER_NAME Value: root

这是因为HDFS客户端做了个设计：如果没有HADOOP_USER_NAME，就用System.getProperty("user.name")来当用户名。这个特性在调试时很方便，但要注意别在生产环境滥用权限冒充。

5.3 版本不匹配：NoSuchMethodError的真相

现象：本地Maven工程用的是Hadoop 3.3.6，连的集群是Hadoop 2.7.x，调用某些API时直接抛NoSuchMethodError或者IncompatibleClassChangeError。

排查链路：

1. 检查hadoop-client版本，确实不一致。
2. 检查RPC协议，HDFS的RPC协议在不同大版本之间是有演进约束的。Hadoop 2.x客户端连3.x集群，很多时候能连通，但某些方法签名已经变了，所以要么编译期过不去，要么运行期反射调用出错。

经验：客户端版本必须和集群版本保持大版本一致，最保险的做法是pom.xml里的hadoop.version直接对齐集群版本。这不是"You should"，而是"你必须"，否则后面遇到的一堆诡异错误都跟它有关。

5.4 流的关闭顺序：close还是先flush

现象：写了文件之后立刻读取同一个文件，读出来是空的。

排查链路：

1. 检查代码，写完后调用out.flush()就紧接着fs.open读了。
2. 把flush改成hflush或者直接close再读，问题消失。

根因：flush()只是把数据从DFSOutputStream的缓冲区推到了管道里，但文件状态仍是UNDER_CONSTRUCTION，NameNode对外不提供该文件的可见性。只有hflush或close之后，文件才会转为COMPLETE，此时才能正常读取。

补充：如果你调用了close但依然读不到数据，检查有没有在close之前调用了abort()或者程序直接System.exit()。abort会丢弃所有未提交数据，相当于写入失败。

5.5 小文件把NameNode内存吃光：delete的recursive陷阱

现象：程序循环创建了大量小文件（每个几KB），NameNode内存飙升，最后连写元数据都开始报错。

根因：NameNode的内存主要耗在元数据上——每个文件/目录/块都要占约150字节的堆内存。1000万个文件就是1.5GB元数据。HDFS是为大文件设计的，不适合存海量小文件。这是架构性约束，不是代码bug。

排查和解决：

1. 用fs.delete(path, true)清理无用的目录，注意第二个参数recursive必须传true，否则非空目录会删除失败。
2. 写代码时下意识地做"小文件合并"，比如把日志按小时合并成一个文件。
3. 如果业务上确实必须存大量小文件，考虑Hive、HBase这类能管理小文件的存储方案，或者用HDFS的Archive工具把文件打包成HAR文件。

// 递归删除的坑：第二个参数忘了写true，会报Directory is not empty boolean deleted = fs.delete(new Path("/user/bigdata/temp"), true); System.out.println("Deleted: " + deleted);

下面把这五个坑整理成表格，方便你贴到笔记里：

6. 从HDFS编程到MapReduce：一条自然的进阶路径

6.1 MapReduce是怎么消费HDFS数据的

实训平台的课程表，在"分布式文件系统HDFS-命令操作"之后，通常紧跟"MapReduce综合实训"。这两章的衔接点在哪里？就在于你刚练过的HDFS读写API。

MapReduce作业的输入输出都以HDFS为默认文件系统。以WordCount为例，你用一行FileInputFormat.addInputPath(job, new Path("/input"))指定输入目录时，MapReduce框架会调用listFiles去遍历目录下的所有文件；然后在每个输入分片（Split）上，通过open和seek按偏移量读取数据。这个过程跟你上一节练习的fs.open几乎一模一样，只是包了一层InputFormat的封装。

输出阶段也一样：每个Reduce任务并行地调用create往输出目录写part-r-00000等文件，写完之后文件才对外可见。所以如果你在Reduce执行到一半时去ls输出目录，通常只能看到_SUCCESS标记还没生成，part文件不完整或不存在。这是一个很常见的"调度系统看进度"的误区——等_SUCCESS文件出现才是作业真正成功。

6.2 数据本地性：为什么说"计算移动比数据移动便宜"

理解HDFS编程后再看MapReduce的调度策略，会有一种"哦原来如此"的感觉。

MapReduce的调度器在给Map任务分配节点时，会优先选择数据所在的节点。为什么？因为如果Map任务跑在A机器，而数据在B机器，就需要通过网络把数据从B拉到A，这不仅占带宽，还增加延迟。反之，如果任务就在数据节点上跑，直接从本地磁盘读数据，速度是网络传输的几十倍甚至更多。

这个"数据本地性"的实现基础，正是HDFS读取流程中getBlockLocations提供的块位置信息——也就是LocatedFileStatus里的那个getBlockLocations。你前面写的遍历程序其实已经在无意中使用了MapReduce调度所依赖的元数据接口。

6.3 综合实训时值得注意的几个点

如果你正在准备HDFS和MapReduce的综合实训，或者准备做一个小项目，我建议你按下面这个清单自查一遍，都是我在实践中见过的问题：

1. 输入路径不能是文件列表，只能是目录或文件通配符。FileInputFormat会递归处理目录下的所有文件，如果你传的文件不存在，作业直接失败。
2. 输出目录不能已存在。HDFS上如果已经有同名输出目录，作业会报FileAlreadyExistsException。很多同学第一次跑MapReduce就栽在这，排查方法是在提交前先保证输出目录被清理干净。
3. Map端调HDFS API慎用fs.close()。Map任务跑在JVM里，FileSystem对象是共享的，你如果在一个Mapper的map方法里把fs关掉，整个TaskTracker的客户端就废了。正确的做法是让框架自己管理声明周期，或者用finally块确保只在main级别关闭。
4. 输出文件名不要乱改。part-r-00000是由框架生成的，你不要在Reduce里用fs自己手动写文件到输出目录，那样很容易绕过OutputCommitter，造成数据一致性问题。

做完HDFS编程实践再去做MapReduce综合实训，你会在WordCount这种入门作业里发现很多熟悉的影子：输入分片对应FileSplit，读文件的偏移量对应seek，输出文件的可见性对应close后文件状态变化。这时候你对HDFS的掌握就不再是"会敲命令"，而是真正理解了一个分布式存储系统最重要的那几个机制。

最后再分享一个小建议：学HDFS编程，不要光看API文档，也不要只停留在"代码跑通了"这个层面。把你写的每一个上传/下载代码，都当成一次观察分布式协议的机会——在write前后打印日志，在hflush之后立刻去用命令行hdfs fsck /path -files -blocks看文件块状态，目睹文件从UNDER_CONSTRUCTION变成COMPLETE的过程。这个习惯一旦养成，后续学HBase、Hive、Spark这些跟HDFS打交道的组件时，你会比别人少踩一半的坑。