# 只会 Python，照样读懂客户的陌生代码库

> 别按字母顺序翻文件，先看清单、入口和一个 API 处理函数，再顺着请求追到数据库，Go、Java、Node.js 皆然。

原文: https://fdetimes.net/zh/guides/read-java-go-node-codebase-python-developer/

驻场第二天，你刚拿到代码仓库的权限。你的团队用 Python，但你的智能体要调用的订单服务是用 Go 写的，支付网关跑在 Java 上，移动端 App 的 API 层是 Node.js。集成评审就在今天下午。

对前线部署工程师（FDE）来说，这再正常不过。客户不会为了迁就你去重写自己的系统。

好消息是，下午之前你不需要精通任何语法。你需要的是一张地图：先打开哪些文件，哪些可以跳过，以及如何回答客户唯一关心的问题——他们的数据流向了哪里。

## 不管什么语言，后端都走同一条流程

所有后端都是这样运作的：服务器接收请求，进行处理，有时查询数据库或调用第三方服务，然后返回响应。API 是前端和后端之间的桥梁。所以面对陌生代码库时，API 路由或处理函数是最好的切入点。

语法各不相同，流程处处一样。所以读代码时带着三个问题，一次只问一个。项目依赖什么？这是清单文件（manifest）回答的。程序从哪里开始运行？这是入口。某个具体请求经过了哪些地方？先是处理函数，然后是数据库或外部服务。

新手常犯一个错误：打开目录，从按字母排序的第一个文件开始读。这样做，还没弄清系统在干什么，就已经淹没在工具代码里了。

## 三种语言把这些东西放在三个不同的地方

下表把每种语言和你在 Python 里熟悉的对应物放在一起：

| 问题 | Python | Go | Node.js | Java（Maven） |
|---|---|---|---|---|
| 依赖什么？ | requirements.txt、pyproject.toml | go.mod | package.json | 根目录下的 pom.xml |
| 入口在哪？ | 主脚本 | package main 里的 main 函数 | "main" 字段；若有 "exports"，则看 "exports" | 在 src/main/java 下找 main 方法 |
| 主代码和测试在哪？ | 因项目而异 | 在各个包目录里 | 因项目而异 | src/main/java 和 src/test/java |
| 什么是包？ | 一个 .py 文件就是一个模块 | 一整个目录 | 带 package.json 的目录 | 包树中的一个分支 |

Node 还有一处表格放不下的细节：一个 .js 文件按 CommonJS 还是 ES 模块处理，取决于离它最近的 package.json 里的 "type" 字段。表格最后一行和这个细节，正是 Python 习惯最容易让人走偏的地方。

## 示例：在 Go 服务里追踪一个订单

设想客户有个 `order-service` 仓库。第一步，打开 go.mod。根据 Go 官方文档，这个文件定义了模块，并记录代码所用包来自哪些模块。光看依赖列表，就能猜出他们用了哪些库来处理 HTTP 和数据库。

第二步，找到程序从哪里开始。在 Go 里，运行 `main` 包时会执行 `main` 函数，所以你只需要找到这两样东西：

```bash
cat go.mod
grep -rln "package main" --include=*.go .
grep -rn "func main()" --include=*.go .
```

从 `main` 出发，你能看到服务器在哪里初始化、路由在哪里注册。假设你发现 `POST /orders` 指向 `api` 目录下的 `CreateOrder` 函数。打开这个函数，你看到一处调用：`store.SaveOrder(...)`。

这时 Python 的本能会让你去找一个叫 `store.go` 的文件。别这么做。Go 的包由同一目录下的所有文件组成，`SaveOrder` 可能在 `store` 目录的任何一个文件里。与其猜文件名，不如直接在这个目录里 grep `func SaveOrder`。

一上午的产出应该是一份五行的链路记录。`POST /orders` 进入 `CreateOrder`（api 目录），再到 `SaveOrder`（store 目录），写入 orders 表，然后调用支付服务。带着它去评审，你已经可以问出具体的问题：支付调用会不会重试？智能体应该从哪一层接入？

**要点:** 不要试图读懂整个仓库。把一个请求从头追到尾，然后写下它走过的路径。

## 在 Node 里，第一个导入错误通常出在 package.json

接下来是移动端 API 层，设想仓库叫 `mobile-gateway`。你写了个小脚本来测试校验 token 的函数，直接导入包里的 `src/auth/token.js` 文件。脚本报错了，你的第一反应是客户的代码有问题。

先打开 package.json。假设里面有个 "exports" 字段，只声明了根路径，指向 `./src/index.js`。根据 Node.js 官方文档，存在 "exports" 时，它的优先级高于 "main"，未声明的子路径一律对外隐藏，所以 `src/auth/token.js` 无法从外部导入。

代码没坏，是你在敲一扇客户已经锁上的门。

再假设同一个 package.json 里还有 `"type": "module"`。如果最近的 package.json 没有这个字段，或者值为 "commonjs"，所有 .js 文件都会按 CommonJS 处理。这里恰好相反，所以这些文件用的是 `import` 而不是 `require`，你的测试脚本也得照此来写。

从 `src/index.js` 出发，你追踪到路由 `GET /orders/:id`，它的处理函数调用的正是你上午读过的 `order-service`。链路记录是："exports" 只暴露 `src/index.js`，路由 `GET /orders/:id` 进入处理函数，处理函数调用 `order-service`。三行字，你就知道智能体应该走公开 API，而不是去碰内部文件。

## 在 Java 里，让测试带你读懂支付网关

Java 支付网关反而更好上手，这要归功于 Maven 的约定。根目录下有一个 pom.xml，主要子目录只有两个：src 和 target。应用代码在 src/main/java，测试在 src/test/java，两者下面都是包树。

面对大型 Java 系统，先读测试。设想你在 src/test/java 里找到支付服务的测试类，一个用例检查金额为负的订单，另一个检查调用银行网关失败的情况。

光这两个用例，就告诉了你系统应该如何处理错误输入和外部故障。

接着沿同一个包分支到 src/main/java，打开被测试的类，再往上找到接收 `order-service` 请求的 controller。链路记录是：controller 接收支付请求，交给支付服务，服务调用银行网关，失败的处理方式和那个测试用例完全一致。

这通常比从上到下逐层翻遍每个类要快。

## 让一上午拖成三天的错误

最常见的错误，是以为必须先学完一门语言才有资格读它的代码。你只需要读到能追踪一个请求的程度。能否写出流畅的 Go 或 Java，是下周的事，前提是项目真的需要。

第二个错误，是把 Python 的模块单位带到哪里都用。在 Go 里你会去找文件，而你该看的是整个目录。在 Node 里你会忽略 "type" 和 "exports"，然后断定客户的代码坏了。

第三个错误，是读了却什么都不记。没有链路记录，第二天就得从头再来，客户那边的人也没有东西可以帮你确认或纠正。

## 求职时把这项能力变成证据

如果你是想转做 FDE 的 Python 开发者，留意岗位描述里类似“与客户现有系统集成”的说法。这意味着你要读不是你写的代码，用的是你没选的语言。

简历上别写“熟悉 Go、Java、Node.js”。写一次具体经历：你读了一个用陌生语言写的服务，追踪了它的数据流，并成功完成集成。一份五行的链路记录，正适合带去面试。

客户不会看你的 Go 写得地不地道。他们看的是，第一天下午你能不能告诉他们，数据流向了哪里。

**本周动手试试:**

- 挑一个带 HTTP 服务器的开源 Go 仓库，用 60 分钟为一个端点写出链路记录，从 go.mod 里的 module 行一直写到数据库调用。
- 打开 GitHub 上三个 Node 项目的 package.json，记下各自是否有 "type"、"main" 或 "exports" 字段，再判断它们的 .js 文件是 CommonJS 还是 ES 模块。
- 找一个用 Maven 的 Spring Boot 项目，先读 src/test/java 里的一个测试文件，再读主代码，然后检验这个测试帮你理解了多少系统行为。

## 信源

- [What is backend? A comprehensive intro to server-side development](https://alokai.com/blog/what-is-backend)

- [Tutorial: Get started with Go](https://go.dev/doc/tutorial/getting-started)

- [Node.js API: Modules: Packages](https://nodejs.org/docs/latest/api/packages.html)

- [Introduction to the Standard Directory Layout – Apache Maven](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html)
