API 演进的正确方式

2024年 7月 18日 25.4k 0

负责任的库作者与其用户的十个约定。

API 演进的正确方式-1

想象一下你是一个造物主,为一个生物设计一个身体。出于仁慈,你希望它能随着时间进化:首先,因为它必须对环境的变化作出反应;其次,因为你的智慧在增长,你对这个小东西想到了更好的设计,它不应该永远保持一个样子。

API 演进的正确方式-2

然而,这个生物可能有赖于其目前解剖学的特征。你不能无所顾忌地添加翅膀或改变它的身材比例。它需要一个有序的过程来适应新的身体。作为一个负责任的设计者,你如何才能温柔地引导这种生物走向更大的进步呢?

对于负责任的库维护者也是如此。我们向依赖我们代码的人保证我们的承诺:我们会发布 bug 修复和有用的新特性。如果对库的未来有利,我们有时会删除某些特性。我们会不断创新,但我们不会破坏使用我们库的人的代码。我们怎样才能一次实现所有这些目标呢?

添加有用的特性

你的库不应该永远保持不变:你应该添加一些特性,使你的库更适合用户。例如,如果你有一个爬行动物类,并且如果有个可以飞行的翅膀是有用的,那就去添加吧。

class Reptile:
    @property
    def teeth(self):
        return 'sharp fangs'

    # 如果 wings 是有用的,那就添加它!
    @property
    def wings(self):
        return 'majestic wings'

但要注意,特性是有风险的。考虑 Python 标准库中以下功能,看看它出了什么问题。

bool(datetime.time(9, 30)) == True
bool(datetime.time(0, 0)) == False

这很奇怪:将任何时间对象转换为布尔值都会得到 True,但午夜时间除外。(更糟糕的是,时区感知时间的规则更加奇怪。)

我已经写了十多年的 Python 了,但直到上周才发现这条规则。这种奇怪的行为会在用户代码中引起什么样的 bug?

比如说一个日历应用程序,它带有一个创建事件的函数。如果一个事件有一个结束时间,那么函数也应该要求它有一个开始时间。

def create_event(day,
                 start_time=None,
                 end_time=None):
    if end_time and not start_time:
        raise ValueError("Can't pass end_time without start_time")

    # 女巫集会从午夜一直开到凌晨 4 点
create_event(datetime.date.today(),
             datetime.time(0, 0),
             datetime.time(4, 0))

不幸的是,对于女巫来说,从午夜开始的事件无法通过校验。当然,一个了解午夜怪癖的细心程序员可以正确地编写这个函数。

def create_event(day,
                 start_time=None,
                 end_time=None):
    if end_time is not None and start_time is None:
        raise ValueError("Can't pass end_time without start_time")

但这种微妙之处令人担忧。如果一个库作者想要创建一个伤害用户的 API,那么像午夜的布尔转换这样的“特性”很有效。

API 演进的正确方式-3

但是,负责任的创建者的目标是使你的库易于正确使用。

这个功能是由 Tim Peters 在 2002 年首次编写 datetime 模块时造成的。即时是像 Tim 这样的奠基 Python 的高手也会犯错误。这个怪异之处后来被消除了,现在所有时间的布尔值都是 True。

# Python 3.5 以后

bool(datetime.time(9, 30)) == True
bool(datetime.time(0, 0)) == True

不知道午夜怪癖的古怪之处的程序员现在可以从这种晦涩的 bug 中解脱出来,但是一想到任何依赖于古怪的旧行为的代码现在没有注意变化,我就会感到紧张。如果从来没有实现这个糟糕的特性,情况会更好。这就引出了库维护者的第一个承诺:

第一个约定:避免糟糕的特性

最痛苦的变化是你必须删除一个特性。一般来说,避免糟糕特性的一种方法是少添加特性!没有充分的理由,不要使用公共方法、类、功能或属性。因此:

第二个约定:最小化特性

特性就像孩子:在充满激情的瞬间孕育,但是它们必须要支持多年(LCTT 译注:我怀疑作者在开车,可是我没有证据)。不要因为你能做傻事就去做傻事。不要画蛇添足!

API 演进的正确方式-4

但是,当然,在很多情况下,用户需要你的库中尚未提供的东西,你如何选择合适的功能给他们?以下另一个警示故事。

一个来自 asyncio 的警示故事

你可能知道,当你调用一个协程函数,它会返回一个协程对象:

async def my_coroutine():
    pass

print(my_coroutine())

你的代码必须 “ 等待 await ” 这个对象以此来运行协程。人们很容易忘记这一点,所以 asyncio 的开发人员想要一个“调试模式”来捕捉这个错误。当协程在没有等待的情况下被销毁时,调试模式将打印一个警告,并在其创建的行上进行回溯。

当 Yury Selivanov 实现调试模式时,他添加了一个“协程装饰器”的基础特性。装饰器是一个函数,它接收一个协程并返回任何内容。Yury 使用它在每个协程上接入警告逻辑,但是其他人可以使用它将协程转换为字符串 “hi!”。

import sys

def my_wrapper(coro):
    return 'hi!'

sys.set_coroutine_wrapper(my_wrapper)

async def my_coroutine():
    pass

print(my_coroutine())
hi!

这是一个地狱般的定制。它改变了 “ 异步 async “ 的含义。调用一次 set_coroutine_wrapper 将在全局永久改变所有的协程函数。正如 Nathaniel Smith 所说:“一个有问题的 API” 很容易被误用,必须被删除。如果 asyncio 开发人员能够更好地按照其目标来设计该特性,他们就可以避免删除该特性的痛苦。负责任的创建者必须牢记这一点:

第三个约定:保持特性单一

幸运的是,Yury 有良好的判断力,他将该特性标记为临时,所以 asyncio 用户知道不能依赖它。Nathaniel 可以用更单一的功能替换 set_coroutine_wrapper,该特性只定制回溯深度。

import sys

sys.set_coroutine_origin_tracking_depth(2)

async def my_coroutine():
    pass

print(my_coroutine())


RuntimeWarning:'my_coroutine' was never awaited

Coroutine created at (most recent call last)
    File "script.py", line 8, in 
        print(my_coroutine())

这样好多了。没有可以更改协程的类型的其他全局设置,因此 asyncio 用户无需编写防御代码。造物主应该像 Yury 一样有远见。

第四个约定:标记实验特征“临时”

如果你只是预感你的生物需要犄角和四叉舌,那就引入这些特性,但将它们标记为“临时”。

API 演进的正确方式-5

你可能会发现犄角是无关紧要的,但是四叉舌是有用的。在库的下一个版本中,你可以删除前者并标记后者为正式的。

删除特性

无论我们如何明智地指导我们的生物进化,总会有一天想要删除一个正式特征。例如,你可能已经创建了一只蜥蜴,现在你选择删除它的腿。也许你想把这个笨拙的家伙变成一条时尚而现代的蟒蛇。

API 演进的正确方式-6

删除特性主要有两个原因。首先,通过用户反馈或者你自己不断增长的智慧,你可能会发现某个特性是个坏主意。午夜怪癖的古怪行为就是这种情况。或者,最初该特性可能已经很好地适应了你的库环境,但现在生态环境发生了变化,也许另一个神发明了哺乳动物,你的生物想要挤进哺乳动物的小洞穴里,吃掉里面美味的哺乳动物,所以它不得不失去双腿。

API 演进的正确方式-7

同样,Python 标准库会根据语言本身的变化删除特性。考虑 asyncio 的 Lock 功能,在把 await 作为一个关键字添加进来之前,它一直在等待:

lock = asyncio.Lock()

async def critical_section():
    await lock
    try:
        print('holding lock')
    finally:
        lock.release()

但是现在,我们可以做“异步锁”:

lock = asyncio.Lock()

async def critical_section():
    async with lock:
        print('holding lock')

新方法好多了!很短,并且在一个大函数中使用其他 try-except 块时不容易出错。因为“尽量找一种,最好是唯一一种明显的解决方案”,旧语法在 Python 3.7 中被弃用,并且很快就会被禁止。

不可避免的是,生态变化会对你的代码产生影响,因此要学会温柔地删除特性。在此之前,请考虑删除它的成本或好处。负责任的维护者不会愿意让用户更改大量代码或逻辑。(还记得 Python 3 在重新添加会 u 字符串前缀之前删除它是多么痛苦吗?)如果代码删除是机械性的动作,就像一个简单的搜索和替换,或者如果该特性是危险的,那么它可能值得删除。

是否删除特性

API 演进的正确方式-1

反对 支持
代码必须改变 改变是机械性的
逻辑必须改变 特性是危险的

就我们饥饿的蜥蜴而言,我们决定删除它的腿,这样它就可以滑进老鼠洞里吃掉它。我们该怎么做呢?我们可以删除 walk 方法,像下面一样修改代码:

class Reptile:
    def walk(self):
        print('step step step')

变成这样:

class Reptile:
    def slither(self):
        print('slide slide slide')

这不是一个好主意,这个生物习惯于走路!或者,就库而言,你的用户拥有依赖于现有方法的代码。当他们升级到最新库版本时,他们的代码将会崩溃。

# 用户的代码,哦,不!
Reptile.walk()

因此,负责任的创建者承诺:

第五条预定:温柔地删除

温柔地删除一个特性需要几个步骤。从用腿走路的蜥蜴开始,首先添加新方法 slither。接下来,弃用旧方法。

import warnings

class Reptile:
    def walk(self):
        warnings.warn(
                "walk is deprecated, use slither",
                 DeprecationWarning, stacklevel=2)
        print('step step step')

    def slither(self):
        print('slide slide slide')

Python 的 warnings 模块非常强大。默认情况下,它会将警告输出到 stderr,每个代码位置只显示一次,但你可以禁用警告或将其转换为异常,以及其它选项。

一旦将这个警告添加到库中,PyCharm 和其他 IDE 就会使用删除线呈现这个被弃用的方法。用户马上就知道该删除这个方法。

Reptile().walk()

当他们使用升级后的库运行代码时会发生什么?

$ python3 script.py

DeprecationWarning: walk is deprecated, use slither
    script.py:14: Reptile().walk()

step step step

默认情况下,他们会在 stderr 上看到警告,但脚本会成功并打印 “step step step”。警告的回溯显示必须修复用户代码的哪一行。(这就是 stacklevel 参数的作用:它显示了用户需要更改的调用,而不是库中生成警告的行。)请注意,错误消息有指导意义,它描述了库用户迁移到新版本必须做的事情。

你的用户可能会希望测试他们的代码,并证明他们没有调用弃用的库方法。仅警告不会使单元测试失败,但异常会失败。Python 有一个命令行选项,可以将弃用警告转换为异常。

> python3 -Werror::DeprecationWarning script.py

Traceback (most recent call last):
    File "script.py", line 14, in 
        Reptile().walk()
    File "script.py", line 8, in walk
        DeprecationWarning, stacklevel=2)
DeprecationWarning: walk is deprecated, use slither

现在,“step step step” 没有输出出来,因为脚本以一个错误终止。

因此,一旦你发布了库的一个版本,该版本会警告已启用的 walk 方法,你就可以在下一个版本中安全地删除它。对吧?

考虑一下你的库用户在他们项目的 requirements 中可能有什么。

# 用户的 requirements.txt 显示 reptile 包的依赖关系
reptile

下次他们部署代码时,他们将安装最新版本的库。如果他们尚未处理所有的弃用,那么他们的代码将会崩溃,因为代码仍然依赖 walk。你需要温柔一点,你必须向用户做出三个承诺:维护更改日志,选择版本化方案和编写升级指南。

第六个约定:维护变更日志

你的库必须有更改日志,其主要目的是宣布用户所依赖的功能何时被弃用或删除。

版本 1.1 中的更改

新特性

  • 新功能 Reptile.slither()

弃用

  • Reptile.walk() 已弃用,将在 2.0 版本中删除,请使用 slither()

负责任的创建者会使用版本号来表示库发生了怎样的变化,以便用户能够对升级做出明智的决定。“版本化方案”是一种用于交流变化速度的语言。

第七个约定:选择一个版本化方案

有两种广泛使用的方案,语义版本控制和基于时间的版本控制。我推荐任何库都进行语义版本控制。Python 的风格在 PEP 440 中定义,像 pip 这样的工具可以理解语义版本号。

如果你为库选择语义版本控制,你可以使用版本号温柔地删除腿,例如:

1.0: 第一个“稳定”版,带有 walk() 1.1: 添加 slither(),废弃 walk() 2.0: 删除 walk()

你的用户依赖于你的库的版本应该有一个范围,例如:

# 用户的 requirements.txt
reptile>=1,>> os.stat('file.txt').st_ctime
1540817862

有一天,核心开发人员决定在 os.stat 中使用浮点数来提供亚秒级精度。但他们担心现有的用户代码还没有做好准备更改。于是他们在 Python 2.3 中创建了一个设置 stat_float_times,默认情况下是 False 。用户可以将其设置为 True 来选择浮点时间戳。

>>> # Python 2.3.
>>> os.stat_float_times(True)
>>> os.stat('file.txt').st_ctime
1540817862.598021

从 Python 2.5 开始,浮点时间成为默认值,因此 2.5 及之后版本编写的任何新代码都可以忽略该设置并期望得到浮点数。当然,你可以将其设置为 False 以保持旧行为,或将其设置为 True 以确保所有 Python 版本都得到浮点数,并为删除 stat_float_times 的那一天准备代码。

多年过去了,在 Python 3.1 中,该设置已被弃用,以便为人们为遥远的未来做好准备,最后,经过数十年的旅程,这个设置被删除。浮点时间现在是唯一的选择。这是一个漫长的过程,但负责任的神灵是有耐心的,因为我们知道这个渐进的过程很有可能于意外的行为变化拯救用户。

第十个约定:逐渐改变行为

以下是步骤:

  • 添加一个标志来选择新行为,默认为 False,如果为 False 则发出警告
  • 将默认值更改为 True,表示完全弃用标记
  • 删除该标志

如果你遵循语义版本控制,版本可能如下:

库版本 库 API 用户代码
1.0 没有标志 预期的旧行为
1.1 添加标志,默认为 False,如果是 False,则警告 设置标志为 True,处理新行为
2.0 改变默认为 True,完全弃用标志 处理新行为
3.0 移除标志 处理新行为

你需要两个主要版本来完成该操作。如果你直接从“添加标志,默认为 False,如果是 False 则发出警告”变到“删除标志”,而没有中间版本,那么用户的代码将无法升级。为 1.1 正确编写的用户代码必须能够升级到下一个版本,除了新警告之外,没有任何不良影响,但如果在下一个版本中删除了该标志,那么该代码将崩溃。一个负责任的神明从不违反扭曲的政策:“先行者总是自由的”。

负责任的创建者

API 演进的正确方式-2

我们的 10 个约定大致可以分为三类:

谨慎发展

  • 避免不良功能
  • 最小化特性
  • 保持功能单一
  • 标记实验特征“临时”
  • 温柔删除功能
  • 严格记录历史

  • 维护更改日志
  • 选择版本方案
  • 编写升级指南
  • 缓慢而明显地改变

  • 兼容添加参数
  • 逐渐改变行为
  • 如果你对你所创造的物种保持这些约定,你将成为一个负责任的造物主。你的生物的身体可以随着时间的推移而进化,一直在改善和适应环境的变化,而不是在生物没有准备好就突然改变。如果你维护一个库,请向用户保留这些承诺,这样你就可以在不破坏依赖该库的代码的情况下对库进行更新。

    这篇文章最初是在 A. Jesse Jiryu Davis 的博客上’出现的,经允许转载。

    插图参考:

    • 《世界进步》, Delphian Society, 1913
    • 《走进蛇的历史》, Charles Owen, 1742
    • 关于哥斯达黎加的 batrachia 和爬行动物,关于尼加拉瓜和秘鲁的爬行动物和鱼类学的记录, Edward Drinker Cope, 1875
    • 《自然史》, Richard Lydekker et. al., 1897
    • Mes Prisons, Silvio Pellico, 1843
    • Tierfotoagentur / m.blue-shadow
    • 洛杉矶公共图书馆, 1930

    via: https://opensource.com/article/19/5/api-evolution-right-way

    作者:A. Jesse 选题:lujun9972 译者:MjSeven 校对:wxy

    本文由 LCTT 原创编译,Linux中国 荣誉推出

    相关文章

    Linux 命令行的聊天工具 CenterIM
    Linux 桌面年仍未到来 但 Linux 移动之年已到来
    12 个在线学习 Linux 技能网站
    Linux Mint : 会是另一个新的 Ubuntu 吗?
    W3Conf 开发者大会将于下周召开
    Ubuntu 10.04 ARM 处理器上网本版本结束服务期

    发布评论