流畅的 API 让开发者爱上使用你的库

让我们向最优秀的人学习。

咦？什么是 Fluent API？

可读性

解锁新方法

其他福利

应用于真实图书馆

向导式代码补全

让我们现在就开始构建一个流畅的 API 吧！

结论

如何规划你的软件开发职业生涯

由 Mux 主办的 DEV 全球展示挑战赛：展示你的项目！

你是否曾对那些本应有用、易于使用的第三方库感到失望？

你是否曾经回头查看几周前编写的某个不错的、可重用的类，却发现自己完全不知道该如何着手使用？似乎没有任何明显的切入点？

于是，你决定查阅文档，结果却花了一个小时试图弄明白如何开始使用你唯一需要这个库的功能！

我去过那里很多次了！

在我的职业生涯中，我一直在思考是否有一种方法可以构建可重复使用的组件，这些组件的使用方法百分之百简单明了，并且能够引导用户正确使用。

让我们向最优秀的人学习。

让我们向最好的学习，学习那些最易于使用的工具。以下是我个人觉得很好用的几个工具：

• Laravel（PHP框架）
• jQuery
• .NET Core
• LINQ

在我看来，这些是我职业生涯中遇到的最简单易用且功能强大的工具。

我不再使用 jQuery，以后也不会再用（这是我自己的选择）。但大家都会同意，与当时的原生工具相比，jQuery 让 DOM 操作变得轻松愉快。

那么，这些工具有什么共同点？是什么让它们如此易于使用？

它们是 Fluent API。

咦？什么是 Fluent API？

“流畅”一词带有某种暗示，即“流畅的API”与（口语）语言有关。例如，你可以精通英语。

流畅界面是一种编程风格，它注重代码的易读性和自然性——就像阅读一本书一样。

可读性

例如，在 .NET Core 中，您可能会看到类似这样的代码：

app.UseDeveloperExceptionPage()
    .UseDatabaseErrorPage();

这段文字非常容易理解和阅读。您打算使用开发者异常页面（其中包含对开发者非常有用的调试信息）。您还希望在遇到数据库错误时使用一个特殊的错误页面。

解锁新方法

我们来看另一个例子：

services
    .AddMvc()
    .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

在这个例子中，调用该AddMvc方法会解锁对其他方法的访问，而这些方法只有在该特定上下文中才有意义。

在我看来，这就是流畅界面最强大的地方——它只允许你在当前上下文中使用有意义的东西。

其他福利

如果流畅的 API 实现得当，您不应该能够：

• 方法调用顺序错误（你用过这样的代码吗？）
• 可能会对从哪里开始感到困惑（因为 IDE 的智能感知功能会告诉你有哪些方法可以“入门”）。
• 部分调用特定链中的方法。（例如：“您忘记调用某个类的“Done”方法，因此该类从未执行其逻辑。”）

如果你想继续阅读这些想法，可以阅读这篇文章，我在文中讨论了使用 Fluent API 可以获得的更多好处。

应用于真实图书馆

基于以上原因（以及我链接的文章中提到的原因），我在编写Coravel时选择了使用 Fluent API 。我认为这是人们使用它的主要原因之一——它非常易于使用。

例如，你能弄清楚这段代码的意图是什么吗？

这就是流畅型代码易于理解的原因。这段代码的功能一目了然。

向导式代码补全

以我在 Visual Studio Code 中使用 Coravel 为例：

当用户想要安排某项任务时，他们可以使用一些新的方法。这些方法仅在安排​​任务时可用。

这里不存在从其他领域借鉴方法的情况。

选择频率后，这些方法将不再适用，您将可以使用一组新的选择项：

让我们现在就开始构建一个流畅的 API 吧！

所以你很想知道——我该如何实际建造一个？

构建基本的流畅 API 其实非常简单。关键在于，类中的方法可以返回一个接口，该接口限制了调用者可以使用的方法。

以下是一个可运行的示例：

public class MyFluentClass : ICalculation, IResult
{
  private int _value;
  private int _result;

  private MyFluentClass() { }

  public static ICalculation WithValue(int value)
  {
    return new MyFluentClass
    {
      _value = value
    };
  }

  public IResult Add(int toAdd)
  {
    this._result = this._value + toAdd;
    return this;
  }

  public IResult Subtract(int toSubtract)
  {
    this._result = this._value - toSubtract;
    return this;
  }

  public int Result() => this._result;
}

public interface ICalculation
{
  IResult Add(int toAdd);
  IResult Subtract(int toSubtract);
}

public interface IResult
{
  int Result();
}

需要注意的事项：

• 使用私有构造函数，这样调用者就必须使用静态工厂方法。
• 静态工厂方法可以访问实例的私有成员
• WithValue返回接口ICalculation。这开始限制调用者可以使用的方法。
• Add并Subtract返回接口IResult。这将解锁链中的下一系列方法（恰好是Result）。

以下是它的实际运行效果：

结论

感谢您抽出时间阅读本文——希望您学到了新知识，并且喜欢这些内容！

顺便一提，这是我的系列文章“我在构建 Coravel 过程中学到的东西”的第二部分。以下是该系列的其他部分：

第一部分 - 我在构建 Coravel（开源 .NET Core 工具）过程中学到的东西

本文最初发表于builtwithdot.net 的博客。

如何规划你的软件开发职业生涯

我会通过电子邮件简讯回答订阅者的问题，并就以下主题提供建议：

✔ 软件开发人员的职业发展阶段有哪些？
✔ 我如何知道自己处于哪个阶段？如何进入下一个阶段？
✔ 什么是技术领导者？如何成为一名技术领导者？

听起来很有趣？加入我们吧！