# Python FDE 接手 TypeScript 仓库，真正的新概念只有三个

> 结构类型、Promise 和 npm 是新内容，其余都能对应到 Python，另有一项合并前必跑的类型检查。

原文: https://fdetimes.net/zh/guides/typescript-for-python-fdes/

周一上午，你拿到了客户后端仓库的访问权限。你写了五年 Python，而这个仓库是用 TypeScript 写的 Node 项目。一个发送通知邮件的接口时不时什么都不发，日志里只有一行：`undefined`。

前线部署工程师（FDE）不能回复“我们团队不做 Node”。客户需要在本周、在自己的技术栈上修好这个 bug。好消息是，你会遇到的许多概念在 Python 里都有对应。真正新的东西只有三个：结构类型、Promise 和 npm。

## 你懂的比想象中多

TypeScript 官方文档说得很明确：能正常运行的 JavaScript 代码也是 TypeScript 代码。这对 FDE 很有实际意义：你可以一次一个文件地给客户代码加类型，而不必申请重写整个模块。

语法也不陌生。类型注解写在变量名之后，和 Python 的类型提示一样：`function getUser(id: string)`。TypeScript 在很多情况下能推断类型，所以需要手写的注解比你预想的少。`any` 的作用和 Python 的 `Any` 相同：关闭检查。文档不建议使用它，因为 `any` 类型的值完全不受检查。

| Python 中 | TypeScript/Node 中 |
|---|---|
| `x: str \| None` | `x: string \| null` |
| `Any` | `any`（最好避免） |
| 协程、`await` | `Promise`、`await` |
| asyncio 事件循环 | Node 的事件循环 |
| requirements 和 dev-requirements | `dependencies` 和 `devDependencies` |
| lock 文件 | `package-lock.json` |

## 类型按形状匹配

这是思维上最大的转变。Python 默认按类名比较类型。TypeScript 采用结构类型：两个形状相同的对象就算同一类型，不管由谁声明。

所以在客户仓库里，你会看到很少的 `class` 声明，却有大量 `type User = { id: string; email: string | null }`。任何同时具备这两个字段的对象都会被当作 `User` 接受，包括刚从 API 解析出来的 JSON。

联合类型有一条值得记住的规则：只有当某个操作对联合中的每个成员都有效时，TypeScript 才允许它。对于 `string | null`，在确认值不是 `null` 之前，不能调用 `.toLowerCase()`。

开启 `strictNullChecks` 后，任何可能为 `null` 或 `undefined` 的值，在使用其属性或方法前都必须先检查，就像在 Python 里使用 `Optional` 值之前必须先检查 `None`。tsconfig 中的 `strict` 标志把这些更严格的检查打包在一起，应当开启。

## Promise 就是 Node 里的 awaitable

根据 MDN 的说法，Promise 是异步函数返回的对象，代表操作的当前状态。写过 asyncio 的话，这个模型并不陌生：Node 默认在单线程上运行 JavaScript，事件循环让它能执行非阻塞 I/O。

陷阱藏在文档里一句很短的话中：async 函数总是返回 Promise。调用时忘了 `await`，你手里拿的就是数据的承诺，而不是数据本身。阅读别人的代码时，缺失的 `await` 很难用肉眼发现。

## 一步步修复客户的 bug

回到邮件接口。假设代码如下：

```ts
type User = { id: string; email: string | null };

async function getUser(id: string): Promise<User | undefined> {
  const row = await db.findById(id);
  return row ?? undefined;
}

export async function notify(id: string) {
  const user = getUser(id);      // 缺少 await
  await sendMail(user.email);    // user 是 Promise，不是 User
}
```

这里即使不开 `strict`，tsc 也会拒绝 `user.email` 这一行，因为 Promise 没有 `email` 属性。这是简单的情况：async 函数的结果在下一行就被使用，存在一个类型错误的操作可供编译器捕获。

另外两种情况更难。如果有人为了消除报错把 `user` 强制转成 `any`，tsc 就不再做任何检查。如果像 `sendMail(...)` 这样的调用丢了 `await`，而结果又从未被使用，那么从类型上看没有任何操作出错，别指望 tsc 能发现，这些调用只能自己审查。

加上 `await` 之后，`strict` 的价值就体现出来了。开启 `strictNullChecks` 后，tsc 报出第二个错误：`user` 的类型是 `User | undefined`，所以还不能读取 `.email`。修好这一处又暴露出第三个：`email` 可能为 `null`。最终的修复在两处都收窄了类型：

```ts
export async function notify(id: string) {
  const user = await getUser(id);
  if (!user) {
    logger.warn({ id }, "未找到用户");
    return;
  }
  if (user.email === null) {
    logger.warn({ id }, "用户没有邮箱");
    return;
  }
  await sendMail(user.email);    // 此处 email 一定是 string
}
```

注意你是怎样得出这个修复的：全程没有猜测。tsc 报出的每个错误都是客户数据中真实存在、却被旧代码忽略的情况；每个提前的 `return` 都会留下一行日志，告诉客户团队邮件为什么没发出去。

**要点:** 你修复的每个类型错误，都是旧代码一直忽略的一种真实数据情况。

## npm 是仓库的地图

读任何一行代码之前，先打开 `package.json`。`scripts` 字段把每个命令名映射到实际要执行的命令，所以 `npm run build` 和 `npm run test` 是构建和测试仓库的标准入口。客户用了哪些工具不用猜，全都写在这里。

接着看两组依赖。npm 文档指出，测试框架、转译器和仅用于开发的工具不应放进 `dependencies`。

它们应该放在 `devDependencies`，就像你区分生产环境依赖和 dev-requirements 一样。`package-lock.json` 锁定精确的依赖树，本就设计为提交到仓库中。

如果你的修复改动了这个文件，把它放进同一个 PR。

还有一个新陷阱。较新版本的 Node 可以直接运行 `.ts` 文件，做法是把 TypeScript 语法替换成空白，完全不做类型检查。

需要语法转换的特性（如 `enum`）会直接报错。所以“Node 能跑”证明不了类型正确。上面缺失 `await` 的代码在 Node 下照样运行，没有任何警告，只有调用 tsc 时才会暴露。

## 你离开后留下什么

本周的工作顺序见文首的示意图。最后一步值得特别强调：检查 `tsc` 是否在 CI 合并前运行的脚本里，如果没有，就提议加上。你的修复帮客户解决了本周的问题；而 CI 里的 `tsc` 会在你转去下一个客户之后，继续拦住同一类 bug。

## Python 开发者常犯的错误

最常见的是用 `any` 让编译器闭嘴，这只会抹掉你需要的信息。其次是忘了 `await`，然后去数据库层找 bug。还有一个习惯是把 Node 能运行 `.ts` 文件当成代码正确的证明。

在 npm 方面，不要把构建工具装进 `dependencies`，也不要漏提交 `package-lock.json`。这两者都会让客户的生产环境在无人察觉的情况下与你的机器不一致。

在职业发展方面，阅读 FDE 招聘信息时，留意对客户技术栈的描述：如果提到 Node 或 TypeScript，就是需要提前准备证据的技能。简历上不要只写“TypeScript”，而要写一行具体内容：你在现有代码库中开启了 `strict`、修复了多少个类型错误、把 `tsc` 加进了 CI。

招聘方读到这一行，就会知道你不仅能在自己的技术栈上交付，也能在客户的技术栈上交付。

本周练习：在你正在做的仓库里，去掉一个 async 调用的 `await`（其结果在下一行被读取），然后运行 tsc；再对一个结果被丢弃的调用重复一遍。第一次 tsc 会报错，第二次则一声不吭，而这份沉默正标出了你在下一个客户那里需要手动检查的地方。

**本周动手试试:**

- 克隆一个开源 Node 仓库，打开 package.json，在运行任何脚本之前，先写下 `scripts` 中每个脚本的作用。
- 在一个小项目的 tsconfig 中设置 `"strict": true`，运行 tsc，通过收窄类型而不是使用 `any` 修复前三个错误。
- 用 async/await 把你的一个简短 Python asyncio 脚本改写成 TypeScript，把两个版本并排对比。

## 信源

- [TypeScript for JavaScript Programmers](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html)

- [Everyday Types](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html)

- [TypeScript: TSConfig Reference - Docs on every TSConfig option](https://www.typescriptlang.org/tsconfig/#strict)

- [How to use promises](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Async_JS/Promises)

- [The Node.js Event Loop | Node.js Learn](https://nodejs.org/en/learn/asynchronous-work/event-loop-timers-and-nexttick)

- [package.json | npm Docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-json)

- [package-lock.json | npm Docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json)

- [Modules: TypeScript (Node.js v26.12.1 Documentation)](https://nodejs.org/api/typescript.html)
