Question

Christophe是一名Python程序员，并且是WSME（Web Services Made Easy）的作者。开发人员可以使用这个框架定义Python风格的Web服务，并且支持多种丰富的API，且允许作为插件被集成到其他Web框架中。

在设计Python的API时开发人员常犯的错误是什么？

有许多我在设计Python API时试图避免的错误。

· 过于复杂。常言道：“Keep It Simple”（也有人说“Keep It Simple Stupid”，但我认为“simple”和“stupid”并不兼容）。复杂的API会很难理解也难以文档化。不过没必要让实际的库函数也太简单，但让库函数简单也是一个明智的想法。一个好的例子就是Request库（http://www.python-requests.org/），与其他标准urllib库相比，Requests的API是非常简单且自然的，但是在背后它做了很多复杂的工作。相比而言，urllib API几乎与它做的事一样复杂。

· 施展（看得见的）魔力。当你的API做一些你的文档没有阐述的事情时，终端用户会想破解你的代码，看看背后到底发生了什么。如果你已经让魔力在后台发生了还好，但终端用户永远都不应该在前台看到任何不正常的事情发生。

· 忘记用例。当写代码深入到库的内部时，很容易忘记实际上你的库应该如何被使用。想出好的用例能够让API的设计更加容易。

· 不写单元测试。测试驱动开发（TDD）是开发库时非常有效的方式，尤其是在Python中。它强迫开发人员从一开始就假设自己是终端用户并能维护版本间的兼容性。而且这是我知道的唯一能够让你完全重写一个库的方法。尽管这并不总是必需的，但有选择总是好的。

考虑到WSME可能运行在多种不同的框架之上，什么样的API是它必须支持的？

实际上并没有那么多，因为它能够运行在其上的框架很多方面是类似的。它们使用装饰器（decorator）给外面的世界暴露函数和方法，它们都是基于WSGI标准的（所以它们的请求对象看上去非常类似），而且它们多少都以彼此作为灵感来源。也就是说，我们还没有试图将其插入一个异步的Web框架中，如Twisted。

我处理过最大的不同是上下文信息的访问方式。在Web框架中，上下文主要是可以从中导出或附加（身份信息、会话数据、数据连接等）信息的请求，以及一些全局的东西，如全局配置、连接池等。大部分Web框架会假设它们运行在多线程服务器上并且将所有这些信息看作是线程独立数据（Thread-Specific Data，TSD）的。这使得它们可以通过导入来自一个模块的请求代理对象来访问当前的请求并与其一起工作。尽管它使用起来很容易，但它也暗含了一点小魔法并且使全局对象缺乏特定上下文数据。

例如，Pyramid框架的工作方式就不太一样。取而代之的是，上下文被显式地注入到使用它的代码段中。这就是为什么视图会接收一个“request”作为参数，它封装了WSGI的环境变量并提供对应用程序全局上下文的访问。

它们的优缺点各是什么？

类似Pyramid的API风格有个很大的优点，它允许一个单独的程序以非常自然的方式运行在几个完全不同的环境中。缺点就是学习曲线有点儿陡。

Python是怎样让库API的设计更简单或更难的呢？

缺乏内置的定义哪部分公共及哪部分私有的方式，这是个（小）问题也是个优点。

当开发人员对哪部分是他们的API哪部分不是的问题欠考虑的时候，它就会是问题。但是，通过一点规则、文档和（如果需要的话）类似zope.interface的工具，它就将不再是问题了。

它的优点在于能够让API的重构快速而简单，同时保持对前面版本的兼容。

对于API的演化、废弃、移除等你的经验法则是什么？

在做决定的时候我会用下面这几个标准去衡量。

· 对用户来说让库适应他们的代码有多困难？设想已经有人依赖你的API，任何你所做出的改动都必须让用户觉得为适应这种变化所付出的努力是值得的。这一规则是为了避免对被广泛使用的API部分做出不兼容的修改。也就是说，Python的优点之一就是让重构代码以适应一个API的变化相对容易。

· 这个修改会让维护变得更容易吗？简化实现，清理代码库，让API变得更容易使用，有更完整的单元测试，让API一看就很容易理解……所有这些都将让你作为维护者的生活更轻松。

· 修改之后会让我的API变得多（不）一致？如果所有的API函数都遵循一个类似的模式（如在第一个位置要求同样的参数），那么确保新函数也遵循同样的模式是很重要的。而且，一次做很多事情通常什么都做不好，让你的API专注于它要做的。

· 用户如何从这次修改中获益？最后但同样重要的是，总是从用户的角度考虑问题。

对为Python中的API建立你有什么建议吗？

文档可以让新用户更容易采用你的库。忽视文档会赶走很多潜在用户，而且还不止是初学者。但问题在于，写文档是很难的，所以它经常被忽略。

尽早写文档，并在持续集成中包含文档构建。现在我们有Read the Docs（https://readthedocs.org/），没理由在不包含文档生成和发布（至少对开源软件来说如此）。

使用docstring对API的类和函数进行文档化。遵循PEP 257规范（http://www.python.org/dev/peps/pep-0257/）1，以便开发人员不必读你的源代码就能理解你的API是做什么的。从docstring生成HTML文档，并且不要限制对API的引用。

自始至终提供实用的例子。至少包括一个“入门指南”，向新手展示如何构建一个可以运行的例子。文档的第一页应该提供一个关于API基本情况的快速概览和有代表性的用例。

在文档中一个版本接一个版本地体现API演进的细节。（只有VCS日志是不够的！）

让你的文档可访问，可能的话，让它读起来更舒服些。你的用户需要能够很容易地找到文档，并从中获取他们需要的信息而没有任何被折磨的感觉。通过PyPI发布你的文档就可以实现这一点，通过Read the Docs发布也是很不错的方法，因为用户会希望能够在那里找到你的文档。

最后，选择一个高效且吸引人的主题。我为WSME选择了“Cloud”Sphinx主题，但实际上有大量的主题可供选择。没必要为了做出好看的文档而成为Web专家。

1 Docstring Conventions, David Goodger, Guido van Rossum, 29 May 2001