企业官网建设流程全解析

Kafka 源码环境搭建这件事，看起来只是"装个 JDK、拉个代码、导入 IDE"三步，实际操作过的人都知道它有多坑。我第一次搭的时候，光是在 IntelliJ 里等那堆红色报错消失就折腾了两天，后来才发现是生成代码没编、Gradle JVM 版本不对、模块没同步三个问题叠在一起。这个系列既然要从源码层面拆 Kafka，第一篇文章就必须把这套环境彻底钉死，否则后面每一篇谈到的类、调用链、断点位置，你都没法在自己机器上复现。这篇文章我会把从零到一的全过程讲清楚：JDK 怎么选、分支怎么挑、IDEA 怎么导、构建到底在干什么、KRaft 模式下怎么用源码把一个本地 Broker 跑起来，以及我实际踩过的那些高频坑。读完之后，你手里应该有一个随时能打断点、能跑通生产消费链路的 Kafka 调试环境。

1. 环境跑不起来，源码学习就永远卡在"看过"这个层面

1.1 断点调试才是读源码的正确姿势

很多人读源码的方式是：打开 GitHub，从KafkaProducer.send()开始一层一层点进去，看到RecordAccumulator、Sender、NetworkClient，觉得"哦，看懂了"，然后关掉页面，三天后全忘光。这不是记性差，而是这种阅读方式缺少一个关键环节——运行时的反馈。

我在实际读 Kafka 源码时，绝大部分关键结论都不是靠肉眼看代码得出的，而是靠断点。比如我想搞明白KafkaApis怎么处理一次 Fetch 请求，我只需要在KafkaApis.handleFetchRequest()里打一个断点，然后启动一个消费者去拉数据，断点命中时就能看到完整的请求对象、会话状态、副本管理的调用栈。这种"带着问题跑一次真实链路"的方式，比在静态代码里猜十遍都管用。

断点调试的前提是什么？前提是你有一个能跑起来的源码工程。这不仅仅是"能编译"这么简单，还要满足三个条件：IDE 能识别全部源码（包括构建过程中自动生成的）、Broker 能用源码编译出的产物启动、你能方便地在任意一层调用链上停下来观察。这三个条件任何一个不满足，调试体验都会大打折扣。这篇文章就是围绕这三个目标展开的。

1.2 源码构建本身就是一条有价值的学习链路

搭环境的副产品往往是意外收获。Kafka 不是一个普通的 Java 工程，它混杂了 Java 和 Scala，是一个多模块 Gradle 项目，而且还带一套"JSON 协议描述自动生成 Java 类"的代码生成机制。你把它的构建流程跑通一遍，实际上就提前接触了后面读源码时必然要理解的一些概念：模块之间的依赖关系、协议层的骨架代码、存储层的日志格式、以及 KRaft 模式下控制器和 Broker 的协作模型。

换句话说，环境搭建不只是"准备工作"，它本身就是一次对 Kafka 工程结构的预读。等后面真正分析源码时，你会发现自己对core、clients、metadata、raft、storage这些模块的分工已经有了一个全局印象，再读具体代码就不会迷路。

1.3 这篇文章结束时的验收标准

为了避免"搭了半天也不知好坏"的情况，先定一个验收标准。读完这篇文章、跟着操作一遍之后，你应该能回答下面四个问题：

• ./gradlew在源码根目录能正常执行，且能编译出各模块的 jar 产物；
• IntelliJ 里导入工程后，核心模块不再出现大面积的红色报错；
• 用源码产物启动一个 KRaft 模式的单节点 Broker，日志显示启动成功；
• 能通过命令行工具创建 Topic、生产消费消息，并且能在 IDE 里打断点看到请求的处理过程。

后面所有源码分析文章，都默认你具备这个环境。我不会每一篇都再讲一遍部署，所以这一篇值得你耐着性子看完。

2. 版本配对是最大的坑：JDK、Gradle、Scala 怎么选

2.1 先搞清版本矩阵，再决定用哪个分支

Kafka 的源码构建对版本有一套硬性要求，选错 JDK 或分支，报错信息往往还很误导人。我整理了一张针对源码阅读场景的版本对照表，读者可以按需选择：

我的建议是：如果你是第一次接触 Kafka 源码，直接用3.7.x 分支搭配 JDK 11。原因有三：第一，3.7 的 KRaft 模式已经很成熟，不需要再装 ZooKeeper，环境复杂度低；第二，这个分支的构建脚本和 IDE 适配经历了大量验证，网上能查到的经验也最多；第三，它仍然保留了相当一部分 Scala 代码，你能看到 Kafka 从 Scala 向 Java 迁移过程中的真实历史状态，对理解社区演进有帮助。

如果你就冲着最新版去，用 4.0 分支 + JDK 17 也没问题，但要注意后面文章中提到的部分类名或包结构在新版本里可能已经变了，对照源码时要有这个心理准备。

2.2 JDK 装好了，但 JAVA_HOME 很可能没配对

JDK 的安装本身不复杂，装一个标准 LTS 发行版就行。真正容易出问题的是JAVA_HOME环境变量和 IDE 里的 Gradle JVM 设置不一致。

常见的诡异现象是：在终端里java -version显示的是 11，但在 IntelliJ 里 Gradle 构建却用的是另一个 JDK，比如 17 甚至 8。等构建报UnsupportedClassVersionError或者 Scala 编译异常时，你根本想不到去查 IDE 里的 JVM 配置。

所以安装完 JDK 之后，我最先建议做两件事：一是在终端确认java -version和echo $JAVA_HOME的结果一致；二是在后续导入 IDEA 时，把 Settings 里的 Gradle JVM 明确指定为同一个 JDK，不要让它自动选择。如果你机器上装了多个 JDK，在 macOS/Linux 上可以用版本管理工具切换，Windows 上就手动修改系统环境变量，改完记得新开一个终端让环境变量生效。

2.3 Gradle 不需要手动安装，但要理解 wrapper 机制

很多新手会犯一个错误：先去官网下载一个 Gradle，然后配置全局环境变量。其实 Kafka 仓库根本不需要你手动装 Gradle，项目根目录下的gradlew脚本（以及对应的gradlew.bat）会自动下载并使用仓库锁定版本的 Gradle。

这个锁定版本写在gradle/wrapper/gradle-wrapper.properties里，核心内容就是一行distributionUrl。打开这个文件，你会看到类似这样的配置：

distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists distributionUrl=https\://services.gradle.org/distributions/gradle-8.x-bin.zip networkTimeout=10000 validateDistributionUrl=true

第一次执行./gradlew时，它会把这个版本的 Gradle 发行包下载到本地的 Gradle 用户目录里，之后所有构建都复用这个缓存。这带来的好处是：所有协作者、所有 CI 机器，用的都是完全相同的 Gradle 版本，不会因为各自环境不同导致构建行为不一致。

实际遇到的问题是下载慢。如果你所在的网络环境访问 Gradle 官方下载地址不顺畅，可以直接把distributionUrl替换成公司内网或国内云厂商的镜像地址，也可以先把发行包下载好，放到本地路径后用file://指向它。这不影响最终构建结果，纯粹是传输层面的优化。

2.4 Scala 插件：3.x 分支绕不开，4.0 之后基本清空

Kafka 的历史代码里，服务端的一部分核心模块，比如kafka.server、kafka.log、kafka.controller，是用 Scala 写的。所以在 3.x 分支下，你导入工程时如果没有装 Scala 插件，IntelliJ 对.scala文件基本就是"能显示但没法正常编译解析"的状态。

我的建议是：用 IntelliJ 时直接装好 Scala 插件（Community 版也支持），等导入 Gradle 工程后让 IDE 自动下载对应的 Scala SDK。如果你选的是 4.0 分支，这个问题会小很多，因为主线已经基本清空了 Scala 代码，几乎可以当作纯 Java 工程来看。

这里顺带解释一个概念：你看到的.scala文件并不是孤立的，它们和 Java 代码在同一个模块里编译，Java 可以调 Scala 的类，Scala 也可以调 Java 的类。构建时 Gradle 会先编译一部分 Java，再调用 Scala 编译器，最后统一打包。这正是 Kafka 早期技术栈留下的印记，读源码时心里有这个概念，就不会觉得"为什么这个项目里混着两种语言"很别扭了。

2.5 KRaft 还是 ZooKeeper：我推荐直接上 KRaft

老版本 Kafka 依赖 ZooKeeper 做元数据管理，所以源码里有一大套和 ZooKeeper 相关的代码，比如kafka.zk、KafkaZkClient、各种 watcher。如果你用 3.x 分支跑 ZooKeeper 模式，除了要额外启动一个 ZooKeeper 进程，还要面对"元数据到底存在哪"这个双重复杂度。

KRaft 模式下，控制器和 Broker 可以在同一个进程中（combined 模式），元数据通过内部日志机制管理，不需要外部依赖。我强烈建议源码阅读环境直接用 KRaft 模式。原因很直接：既然你要把注意力集中在消息链路、存储机制、副本协议这些核心逻辑上，就没必要为了兼容老架构多引入一个外部组件。等到后面真正分析元数据管理时，再单独研究 KRaft 的实现也不迟。

3. 拉代码、导 IDEA、跑构建：一份可直接照抄的操作清单

3.1 分支与浅克隆：省时间的关键一步

选好分支之后，执行下面的命令把源码拉到本地：

git clone --depth 1 --branch 3.7 https://github.com/apache/kafka.git kafka-source cd kafka-source

这里用了--depth 1做浅克隆，只拉取指定分支的最新代码，不拉历史提交。对源码阅读来说，历史提交不是必须的，浅克隆能省下不少时间和磁盘空间。如果你后面确实想查某个类或某个配置的演进历史，再单独git fetch --unshallow补全历史即可，不影响当前使用。

拉完之后，先看一下目录结构。你会看到这些核心目录：core（服务端主要实现）、clients（客户端和协议定义）、metadata（KRaft 元数据相关）、raft（KRaft 日志复制实现）、storage（存储层）、tools（命令行工具）、connect和streams（连接器和流处理）。

此时先不要急着打开 IDEA，我建议你直接在终端跑一次构建，确保依赖能拉下来、代码能编译，再进 IDE。这样能把"环境问题"和"IDE 问题"分开排查。

3.2 第一次构建：把整条编译链路跑通

在源码根目录执行：

./gradlew clean build -x test

这条命令的意思很明确：清理历史产物，编译所有模块，跳过单元测试。第一次跑的时候会拉取大量依赖，耗时较长，耐心等它完成。

如果你只关心某个模块，也可以精确指定，比如：

./gradlew :core:jar -x test

它会自动把core依赖的其他模块（比如clients、metadata）一起编译出来。跑完以后，检查一下core/build/libs目录下是否生成了kafka_2.13-3.7.x.jar这类产物，看到 jar 文件基本就说明编译链路通了。

这里提醒一点：build任务默认会跑代码检查，比如 spotbugs、checkstyle 这类静态检查任务，会比较耗时。你可以在命令后面继续追加排除项，例如-x spotbugsMain -x spotbugsTest -x checkstyleMain -x checkstyleTest，从而跳过这些与阅读源码无关的检查。跳过测试和检查并不会影响我们后面启动 Broker，只会让构建更快。

3.3 导入 IntelliJ：用 Gradle 方式，而不是直接 Open 目录

构建通过之后，打开 IntelliJ，选择导入工程。注意，不要用 "Open" 直接打开文件夹，那样会丢失 Gradle 工程信息；应该选择从 Gradle 工程导入，或者直接双击根目录的build.gradle文件让 IDEA 识别。

导入设置里有几个关键点：

• 在 Gradle 设置里，选择 "Use Gradle from: gradle-wrapper.properties file"，确保 IDE 用的是仓库自带那个版本；
• Gradle JVM 选择我们刚才确认过的 JDK 11；
• 勾选自动导入（Auto-import），让依赖变化时 IDE 自动同步。

导入过程会做一次 Gradle 同步，耗时取决于机器性能。同步完成后，左侧项目树会按 Gradle 模块展示，每个子模块对应一个core、clients这类节点。

如果在core/src/main/scala/kafka下看到大量红色波浪线，先别急着怀疑环境坏了。很可能是生成代码还没编出来、IDE 还没识别到构建产物目录。处理方法我们在下一节专门讲，这里继续往下走。

3.4 认识模块分工：后面读源码时不迷路

趁导入的空档，把几个核心模块的分工提前梳理一下：

• clients：既包含客户端（org.apache.kafka.clients），也包含所有请求/响应数据类的定义。读生产消费链路时，一半时间都泡在这个模块里。
• core：服务端主战场，kafka.server、kafka.log、kafka.controller都在这里。后面分析 Broker 内部逻辑时，主要在这个模块打转。
• metadata：KRaft 模式下的元数据模型和元数据 API。想搞清楚 Topic 配置、分区分配怎么被管理，看这里。
• raft：KRaft 的共识层实现。这是新版本较难啃的部分，建议放到中后期再细读。
• storage：日志段、索引、日志清理等存储实现。读"消息到底怎么落盘"时必看。

不要试图一次性把五个模块全读完，按下面这个顺序推进会更顺：先clients摸清请求响应结构，再进core跟着一个请求的处理链路走，中间遇到元数据和存储问题时，再分别进metadata和storage查找答案。

4. 构建里最容易被忽略的部分：自动生成的协议代码

4.1 你看到的很多类，根本不是手写的

第一次在clients模块里翻源码时，我一度怀疑自己眼睛花了——像FetchRequestData、MetadataResponseData、ProduceRequestData这种巨大的数据类，动辄几千行，字段多得吓人，而且风格高度统一。后来才发现，这些类全部是构建时自动生成的。

Kafka 的协议定义遵循一个原则：用一个 JSON 文件描述消息的字段结构，构建时通过代码生成器把它变成 Java 类。这些 JSON 文件放在clients/src/main/resources/common/message/下面，比如FetchRequest.json、FetchResponse.json这样。打开一个 JSON，你会看到类似这样的结构：

{ "apiKey": 1, "type": "request", "name": "FetchRequest", "validVersions": "0-15", "fields": [ { "name": "ReplicaId", "type": "int32", "versions": "0+", "default": "-1" } ] }

构建时，generateMessages这个任务会读取这批 JSON，按照模板生成对应的 Java 类。因此你看到的FetchRequestData类，无论是字段顺序、JavaDoc 还是版本判断逻辑，都是统一生成的产物。

4.2 为什么 Kafka 要这么设计

直接回答一个很多人会问的问题：为什么不手写这些类？

因为 Kafka 的协议非常讲究版本兼容。同一个请求在不同版本里字段可能不一样，有的字段只在 0 到 5 版本存在，有的字段从 3 版本开始新增。如果手写每个版本的数据类，维护成本会失控，而且极易漏掉版本边界判断。

用 JSON 描述协议，再自动生成代码，好处是"协议单源"：你改一处 JSON，所有语言的实现（Java 客户端、服务端、甚至其他生态语言的客户端）都能基于它重新生成，不会出现各写各的、版本对不上的问题。所有协议变更首先提交 JSON，再生成代码，这已经成为 Kafka 社区约定俗成的开发流程。

4.3 IDEA 里生成代码红线的正确处理方法

回到 3.3 节提到的红色波浪线问题。它的根因通常是：你先把工程导入 IDE，但此时build/generated目录下的生成类还不存在，IDE 自然找不到FetchRequestData这类符号。

处理方法有两个层次：

第一，先在终端把生成代码跑出来：

./gradlew :clients:generateMessages :core:generateMessages

跑完以后回到 IDEA，右键工程根目录选择 "Reload Gradle Project"，让 IDE 重新同步源目录。

第二，如果同步之后仍然识别不到，手动检查clients/build/generated和core/build/generated目录是否被 IDE 标记为生成源目录。正常情况下 Gradle 导入会自动处理，但偶尔会有同步不到位的情况，手动把目录标记为 Sources Root 或 Generated Sources Root 即可。

还有一个次常见原因：你先跑了clean，把build目录删了，但 IDE 还开着索引。这时候在 IDEA 里执行一次 Build -> Rebuild Project，让它基于现有生成代码重新编译，基本都能解决。

4.4 阅读策略：JSON 是源头，生成类是结果

既然生成代码是自动产物，阅读时就要有正确的策略。我的建议是：不要逐行读生成类，那既枯燥又没收益。需要了解某个请求的结构时，直接看对应的 JSON 文件，字段、版本、默认值一目了然。只有在需要确认某个字段在特定版本下是否有效、或者想看清楚序列化逻辑时，再进生成的 Java 类里查。

后面分析生产消费链路时会频繁用到这个技巧。比如读ProduceRequestData，你只需要知道"它由哪些字段组成、各字段的版本范围是什么"，这些信息 JSON 里全都有。生成类只是它的 Java 化呈现，理解它存在的原理就足够了。

5. 用源码启动一个本地 Broker：KRaft 单节点全流程

5.1 为什么现在可以直接跳过 ZooKeeper

前面提到了 KRaft 模式。具体来说，在config/kraft/server.properties这个配置文件里，process.roles=broker,controller这行配置表示当前节点同时扮演 Broker 和控制器两种角色，也就是常说的 combined 模式。对于单机调试，这是最省事的方式，不需要再单独启动任何外部组件。

要注意，"KRaft 模式不需要 ZooKeeper"不等于"没有元数据存储"。KRaft 的元数据存放在一个内部的元数据日志里，节点启动前必须先用工具生成一个集群 ID 并格式化元数据存储目录，这一步对应旧架构里"初始化 ZooKeeper"的工作。

5.2 格式化存储：随机 UUID 到底在干嘛

启动 Broker 之前，先执行下面两条命令：

CLUSTER_ID=$(bin/kafka-storage.sh random-uuid) bin/kafka-storage.sh format -t "$CLUSTER_ID" -c config/kraft/server.properties

第一条命令生成一个随机的集群 ID。为什么需要集群 ID？因为 KRaft 的元数据日志要标识自己属于哪个集群，所有节点必须共享同一个 ID 才能正常通信。单节点调试时，这个 ID 是随机生成的；真实多节点部署时，则会用同一个 ID 初始化所有节点。

第二条命令把集群 ID 写入元数据存储目录，相当于给这块磁盘"格式化"成属于该集群的元数据存储。如果存储目录已经格式化过，命令会提示已存在；想重新初始化，可以删掉log.dirs指向的目录，或者加上--ignore-formatted强制覆盖。

这里有个小坑：不同版本对 format 的参数要求略有差异。有些较新分支会要求你额外指定--standalone之类的参数，如果命令报了未知参数或缺失参数，按提示补上即可，逻辑没变化。

5.3 启动服务并验证生产消费链路

格式完成后，启动服务：

bin/kafka-server-start.sh config/kraft/server.properties

这个脚本会从各模块的build目录拼接 classpath，也就是说它会用到我们前面用 Gradle 编译出来的产物。如果没编译过就直接启动，会报类找不到的错误，所以顺序很重要：先构建，后启动。

启动日志里出现类似Kafka Server started的信息，说明 Broker 已经就绪。接下来用三个命令做完整验证。先创建 Topic：

bin/kafka-topics.sh --bootstrap-server localhost:9092 --create --topic demo-source --partitions 3 --replication-factor 1

再开一个终端跑生产者，输入几条消息：

bin/kafka-console-producer.sh --bootstrap-server localhost:9092 --topic demo-source

最后开第三个终端跑消费者：

bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic demo-source --from-beginning --group demo-cg

如果消费者能收到生产者输入的消息，说明整条链路已经通了：客户端连上了 Broker，Topic 元数据正常，分区写入和拉取都工作正常。

更进一步，可以用下面的命令查看消费者组的位移提交情况：

bin/kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group demo-cg

这条命令会显示消费者组当前提交的 offset、lag 等指标。能看到它，意味着__consumer_offsets内部主题也在正常工作。

5.4 在 IDEA 里直接跑 Broker 主类

命令行方式适合验证环境，但调试源码时，我更推荐直接在 IDEA 里跑 Broker 主类。这样打断点不需要额外附加远程调试，日志输出直接落在 IDEA 的控制台里，排查起来最顺手。

具体做法：新建一个 Application 运行配置，主类填kafka.Kafka，程序参数填config/kraft/server.properties，工作目录设为源码根目录。注意，在 3.x 分支里这是 Scala 写的入口类，你可以在core/src/main/scala/kafka/Kafka.scala里找到它；如果用的更新分支，类名可能已经变化，直接搜索def main定位即可。

IDEA 里跑还有一个好处：你可以直接在kafka.Kafka.main()里打断点，观察启动过程每个组件的初始化顺序，这对理解"一个 Broker 是怎么从零到一启动起来的"非常有帮助。

如果坚持用命令行方式调试，也可以用远程调试参数，启动前设置环境变量KAFKA_DEBUG=y，并在启动脚本里传入调试端口，然后在 IDEA 里创建 Remote JVM Debug 配置去 attach。但单机调试没必要绕这一圈，IDEA 直跑更直接。

5.5 给调试加一点侦察能力：日志级别与端口调整

源码调试时，光打断点还不够，经常需要开日志观察运行过程。Kafka 的日志配置文件在config/log4j.properties，启动时由脚本加载。默认情况下log4j.logger.kafka=INFO，很多内部细节被吞掉了。

如果只想观察某个类的行为，可以针对性调高，比如：

log4j.logger.kafka.server.KafkaApis=DEBUG log4j.logger.kafka.log.Log=DEBUG

这样既能拿到足够信息，又不会被全局 DEBUG 刷屏。注意每次改完日志配置要重启 Broker 才生效。

端口冲突是另一个常见问题。配置文件里默认的listeners=PLAINTEXT://:9092，如果 9092 被别的进程占了，启动会报Address already in use。这时候改配置文件里的端口即可，比如改成 9192，后面所有客户端命令的--bootstrap-server也要跟着改。

还有一个经验：KRaft 模式的元数据日志和消息日志都放在log.dirs指向的目录里（默认类似/tmp/kraft-combined-logs）。如果你改了配置想把环境重置干净，删这个目录比手动逐个清理更彻底，但记得格式化存储那步也要重做。

6. 高频报错处置思路：按症状定位，按根因下药

6.1 我实际遇到过的七类问题与解法

这里把我搭建过程中的高频报错整理成一张表，每一类都给出症状、根因和处置方案，建议收藏备查：

这七类问题里，最容易被低估的是第三类。很多人都栽在"明明编译通过了，但 IDEA 里全红"这个矛盾体验上。本质原因就是 IDE 的索引和 Gradle 的生成目录没有同步，只要记住了"先构建生成代码，再同步 IDE"这个顺序，问题就解决了一大半。

6.2 判断"环境真正搭好"的验收清单

为了不把"表面能用"当成"真的搭好"，我每次在新机器上搭完环境都会按这个清单过一遍：

• [ ] 在终端执行java -version，版本与所选分支要求一致；
• [ ] 在源码根目录执行./gradlew projects能列出所有模块；
• [ ]./gradlew :core:jar -x test成功生成 jar 产物；
• [ ] IDEA 中core/src/main/scala/kafka与clients/src/main/java/org/apache/kafka下无大面积红色报错；
• [ ]bin/kafka-storage.sh format执行成功；
• [ ]bin/kafka-server-start.sh config/kraft/server.properties启动后日志出现Kafka Server started；
• [ ] 控制台生产者写入的消息能被消费者正常读取。

这个清单不追求覆盖所有异常场景，但它能保证你后续读源码时的最低体验要求。如果哪一项过不去，停下来排查它，不要带着隐患继续往下走。

6.3 给后续阅读的三点忠告

环境搭好之后，真正读源码之前，还有三句话我想提前说。

第一，不要轻易升级或改动构建依赖。源码阅读环境下，Gradle wrapper 锁定的版本、依赖的版本，都是经过社区验证的。你为了"尝鲜"升级某个依赖，很可能引入一堆莫名其妙的编译错误，而且这些错误和你要学的 Kafka 逻辑毫无关系。

第二，调试比搜索更有价值。遇到一个不明白的类，与其全局搜索看它被谁引用，不如在调用链的关键位置打断点，实际跑一次看它接收了什么、返回了什么。你会发现很多看代码怎么也想不通的行为，一旦看到运行时数据，立刻就理解了。

第三，保持仓库干净，单独建分支做实验。哪怕只是改一行日志级别，我也建议先git switch -c my-notes建一个自己的分支。这样后面代码看乱了，随时能回到原始状态，不至于把自己改到无法继续。

这套环境我在自己常用的几台机器上都完整搭过一遍，最顺的一次全程不到一小时，最折腾的一次是因为 IDEA 的 Gradle JVM 选错，白白浪费了两个下午。希望这篇能把最容易被忽视的版本配对和生成代码两个问题讲透，让你少走这些弯路。下一篇开始，我们就带着断点进KafkaApis，从第一次 Fetch 请求的真实路径入手，拆一拆服务端处理请求的完整骨架。