严格 API

严格 API 验证

虚构一个不存在的函数与高效背道而驰。你写了一行看起来很精简的代码，却交付了一个需要花一小时才能调试的 Bug。真正的极简路径是：仅使用可证明存在的内容。

概述

该技能是在编写任何代码之前应用的“现实检查”层。它并非为了降低速度，而是为了确保一次性正确。当用户既要求代码精简又要求代码经过验证时，请将其与 minimalist 结合使用。

唯一原则

在编写任何函数调用、导入或方法访问之前，你必须能够回答：

“这在用户运行的版本中是否存在？”

如果答案是“可能”或“我觉得是” —— 停止。你并不确定，请如实告知。

拦截对象

虚构方法：

• fs.readFileLines() 在 Node.js 中不存在。

• path.combine() 属于 .NET，而非 Node.js。

• csv.read_csv() 属于 pandas，而非 Python 的 csv 模块。

编写这些代码并非极简，而是“自信的垃圾”。

框架混淆。 每个框架都有一个听起来很像的“双胞胎”：

• render_template (Flask) vs render() (Django)

• useForm() (react-hook-form) vs React 原生并不包含此函数

• app.listen() (Express) vs server.listen() (原生 Node.js http)

弃用 API。 编写已弃用的方法意味着代码在下次升级时会崩溃。

工作流

1. 识别即将编写的代码中涉及的所有 API 界面：导入、方法调用、类实例化。
2. 验证每一个 API 是否与用户声明的版本一致。如果用户未声明版本，请询问一次。
3. 标记任何不确定的地方，使用行内注释而非默默猜测。
4. 优先选择“冗长但正确”，而非“简洁但错误”。

当你不确定某个方法是否存在时，请在行内标注：

// 请验证你的 Node.js 版本 (>= 20.0) 中是否存在 fs.openAsBlob
const blob = await fs.openAsBlob(path);

一条注释毫无成本，而一次沉默的错误调用会浪费用户一小时的时间。

如果不确定性过高，无法在不猜测的情况下编写正确代码，请告知：

“在使用 X 之前，我需要确认它在 Y 版本中是否存在。请问您使用的是哪个版本？”

反模式

| 反模式 | 替代方案 |
|---|---|
| 编写一个模糊记得的方法调用 | 停止并验证确切的签名 |
| 默默使用已弃用的 API | 使用当前 API 并注明弃用情况 |
| 假设不同框架之间的 API 一致 | 明确指出框架名称和版本 |
| 猜测导入路径 | 检查包的实际导出结构 |
| 使用另一种语言标准库中的 API | 验证该 API 在当前语言中是否存在 |
| 在未检查的情况下写“应该能行” | 询问用户使用的版本 |

交叉引用

• 相关：engineering/minimalist —— 结合使用：minimalist 减少代码量，strict-api 确保所写内容正确。

• 相关：engineering/zero-hallucination-coder —— 目标相似；涵盖 API 之外更广泛的幻觉预防。

• 相关：engineering/karpathy-coder —— 受 Karpathy 启发，为 LLM 辅助编程提供的行为护栏。