构建Python库API有用的建议清单

构建Python库API有用的建议清单

简洁性

减少冗余的代码：数一数从第一行开始到你真正调用 API 函数的行数。例如： 与 Request 库相比，进行 HTTP 请求时 urllib2 库就很多的冗余代码。

在实践中逐步完善：实用且明智的缺省值设置

- 具有缺省设置，并根据最常用的使用情况来设置缺省值。

不要将源代码片段复制粘贴进你的 API 中。

坚持最小惊讶原则（ Principle of least astonishment）：如果一个函数特征很让人吃惊，或许就应该考虑重新设计它了。- 程序默认的行为是用户所期望的吗？- 程序默认的行为是否符合用户对于程序性能、副作用，安全性，可靠性，安全性以及限制条件的要求？

一致性

命名问题：你 API 中的命名是否和 Python 的习俗保持了一致性？ 我们命名应该与 PEP8 中所给出一致。PEP8 是 Python 官方的代码风格指南。为了保持命名与代码风格的一致性，建议使用 flake8 来规范你的 API 代码。

命名问题：API 中的命名是否一致？- 术语的顺序：string_encodeVSdecode_string- 缩写问题：activate_prevVSfetch_previous以及bin2hex VS strtolower- 是否带有下划线：gettypeVSget_class- 单复数问题：values_list VSvalue_list- 正负问题：button.enabled == TrueVSbutton.disabled == True

空值问题：在空值意义的定义是否一致？目前的是最好的选择吗？- 决定下面哪个代表了空值：None、False、[]、''、0- 小心一些出人意料的值：bool(datetime.time(0)) == False在Python3.5以前是这样

参数问题：在参数的顺序上是否具有一致性？例如：datetime.datetime(year, month, day, minute, second, microsecond)vsdatetime.timedelta(days, seconds, microseconds, milliseconds, minutes, hours, weeks)

行为问题：在相似或者不同的行为上是否具有一致性？行为的不对称应该反应在格式的不对称上。例如，numbers.sort()VSsort(numbers)

灵活性

减小整体的不连续性- 检查所有的类的功能是否单一职责？如果不是，就应该把那些类拆解开来。例如，一个从缓存中获取数据的类应该将其连接缓存服务器的步骤交给另一个类做。

- 检查函数的名称中是否包含了`and`或者是否包含多个操作。 如果确实如此，应该将这个函数拆成多个不同的函数。但是，如果这个函数经常被调用，那么可以保留一个结合了众多函数的函数。例如：print_formatted函数可以被拆解为两个函数：print和formated

- 检查是否存在用户复制粘贴代码以改变函数功能的行为。 应该提供代码重构，回调功能。

- 检查在函数内部是否使用了属性值，如果有可以使用 get_something 方法代替。例如在 Djando 的 REST 框架中， CursorPagination 这个类仅仅支持一个固定大小的属性值：page_size，其原因就是这个类没有get_page_size这个方法。 这个问题再后来就通过上述方法解决了，即添加了 get_page_size方法。

- 尽量避免隐藏可能有用的参数。例如我们的 API 中调用了另一个低级的 API 但是却没有展示这个低级 API 的参数情况

- 返回用户可能需要的一切信息

- 用户调用 API 时，要处理用户可能需要所有情况

- 在进行 API 测试的时候要测试每一个mock.pathch。 虽然在程序运行的时候有一些东西不容易修改，但我们可以通过设置参数来修改某些东西。例如，Python 的内置函数sched.scheduler接受两个参数timefunc和delayfunc。而我们没必要对time.monotonic和time.sleep两个函数进行 mock 测试，用户会根据自己的需求进行相应的改变。

建立抽象- 按照底层实现的结构，去封装我们的函数成员与对象。例如 Beautiful Soup 就为多个分析器设计了同样的 API 结构。

- 提供多级的抽象结构，从最简单到最个性化。例如， Celery 既提供了@app.task这个装饰器，又提供了个性化的 task 类，而这个类继承于celery.Task

- 提供摆脱封装的方法，让用户可以直接使用被抽象的资源和能力。例如，Django 的查询集合支持使用.extra方法将自定义的 SQL 与 ORM 进行结合来产生查询语句，同时也支持使用.raw来直接使用原生的 SQL 查询语句。

- 将底层实现中常见的错误进行封装，避免给用户直接报错。例如当 API 支持多个数据引擎的时候，出现数据库连接错误时，其显示信息应该一样。这个帮助用户找出问题所在，并且在修改数据库引擎时不会需要修改很多代码。

国际化终端用户看到的字符串。

安全性

检查文档中的用于描述函数功能的警告性字眼，例如： warning，careful，remember to, dont't forget。如果存在这些字眼，就得考虑如何更改代码使得函数更加安全稳定。

检查常见的错误，使用 Python 内置的 warning 模块来记录警告

明确不安全的行为。例如如果一些变量没有设置值，不要特意为它设置。不要到处写 fileds = None 这样的语句。

不要通过对象名称或者模块名称来隐式地链接代码，使用一个注册函数或者注册装饰器。例如 Django-admin 的注册问题不仅支持通过函数也支持装饰器。

不要依赖方法的调用顺序，尽量使用 with 语句。

快速报错： 程序出错就直接退出并不是 Python 式的思维

- 当一个库函数接受到一个无效的具有错误格式或者错误表达的参数，例如参数溢出，就产生一个 Value Error 错误。- 当一个库函数接受到一个不兼容类型的数据便产生一个 TypeError 错误，例如 duck 类型并不兼容 quack 类型。 不要在 if isinstance(duck, LibDuck) 或者 if type(duck) == LibDuck) 这样的语句中引发异常。首先尝试使用 quack，如果错误则引发 TypeError 异常，并打印明确的错误信息。

总结我的 API 旨在将简单的事情变的简洁，将复杂的事情变为现实，将错误的事情永远杜绝。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。