API：如何让开发人员编写他们不会讨厌的代码

# Web 开发# 编程# Node.js# API

介绍

啊，API——开发人员之间写的情书（有时是用一种没人能理解的神秘语言写的）。无论您是编写优雅的方法交响曲，还是发布一堆难以阅读的意大利面条式代码，本指南都将帮助您设计不会让您的同事哭泣（或至少不会哭泣）的 API。让我们开始吧！

优秀 API 的特征

1. 易于学习和记忆

好的 API 应该非常简单，甚至你的祖母都可以使用它。如果你的 API 感觉像需要火箭科学博士学位，那你就做错了。假设你正在构建一个计算器 API。

**糟糕的 API 示例**：

calculate(1, "plus", 2, { round: false, mode: "basic", verbosity: "low" });

“呃，什么？我为什么需要知道基本加法的详细程度？”

**良好的 API 示例**：

calculator.add(1, 2); // Ah, so simple even my pet goldfish gets it!

2. 代码更易读

可读的 API 是那些你可以浏览而不需要质疑你的生活选择的 API。

**讽刺场景**：想象一下，凌晨 2 点，你一手拿着咖啡，一手绝望地调试代码。你更喜欢哪种代码？

**糟糕的 API 示例**：

const res = x.A(1, 2).B(3).C();  
// What is A? What is B? Are we building a spaceship or solving math?

**良好的 API 示例**：

const result = calculator.add(1, 2).multiply(3).getResult();  
// Ah, now I know what I’m doing. I'm multiplying happiness.

3. 难以滥用

容易被滥用的 API 就像一台吞食你钱财的自动售货机。让我们保护开发人员免受自身伤害。

**糟糕的 API 示例**：

calculator.add("apple", "banana"); // Hmm, should this work? It does. But why?

**良好的 API 示例**：

calculator.add(1, 2); // Only numbers allowed, sorry fruit enthusiasts.

当然，还会抛出一个尖叫的错误：

“参数类型无效：我们接受数字，而不是您的购物清单！”

设计过程

4.了解要求

在编写任何代码之前，请问自己：

  • 用户需要什么？
  • 他们真正需要什么（而不是他们声称需要什么）？

    • **示例**：如果用户需要 `Todo API`，就不要构建火箭发射器 API。保持专注。

    5. 首先编写用例

    有没有试过不借助说明书就组装宜家家具？编写没有用例的代码有点像那样，但更糟糕。

    **用例**：

    // BEFORE implementation:
todo.addTask("Write blog").completeTask(1).deleteTask(1);

    现在，构建与之匹配的 API。没有多余的内容，也没有过度设计。

    6. 准备扩展

    不要创建一个僵化的 API，因为当有人想要添加某个功能时，它就会崩溃。

    **可扩展 API 示例**：

    interface Calculator {
  add(a: number, b: number): Calculator;
  subtract(a: number, b: number): Calculator;
  withOptions(options: { precision?: number; mode?: "basic" | "scientific" }): Calculator;
}

    7. 有疑问时，就放弃吧

    开发人员喜欢添加功能，就像添加配料一样。但有时，最好的配料就是什么都没有。

    **讽刺例子**：

    // Bad API with unnecessary features:
todo.addTask("Cook dinner", { priority: "urgent", notifyVia: "pigeon", withEmojis: true });

    真的吗？表情符号和鸽子通知？冷静点。

    设计指南

    8. 选择不言自明的名称

    您的 API 应该非常清晰，甚至 5 岁的孩子都可以解释它。

    **坏例子**：

    t.api(1, "xyz"); // What is this sorcery?

    **好的例子**：

    todo.addTask("Learn TypeScript").completeTask(1);

    看到了吗？简洁明了，让你看起来很聪明。

    9.避免使用缩写

    缩写是 Twitter 的，而不是 API。

    **坏例子**：

    usrMgmt.addUsr("John");

    这是拼写错误还是代码？

    **好的例子**：

    userManagement.addUser("John");

    10. 最好的 API 就是没有 API

    有时，简单意味着根本不要编写 API。没有它你能解决问题吗？如果可以，那就这样做。

    **例子**：

    无需使用自定义的 `fetchData` API，只需使用：

    fetch("https://example.com/data").then((res) => res.json());