Python 工匠：异常处理的三个好习惯

时间 2019-11-08

原文原文链接

前言

这是 “Python 工匠”系列的第 6 篇文章。[查看系列全部文章]javascript

若是你用 Python 编程，那么你就没法避开异常，由于异常在这门语言里无处不在。打个比方，当你在脚本执行时按 ctrl+c 退出，解释器就会产生一个 KeyboardInterrupt 异常。而 KeyError、ValueError、TypeError 等更是平常编程里随处可见的老朋友。html

异常处理工做由“捕获”和“抛出”两部分组成。“捕获”指的是使用 try ... except 包裹特定语句，稳当的完成错误流程处理。而恰当的使用 raise 主动“抛出”异常，更是优雅代码里必不可少的组成部分。前端

在这篇文章里，我会分享与异常处理相关的 3 个好习惯。继续阅读前，我但愿你已经了解了下面这些知识点：java

异常的基本语法与用法*（建议阅读官方文档 “Errors and Exceptions”）*
为何要使用异常代替错误返回*（建议阅读《让函数返回结果的技巧》）*
为何在写 Python 时鼓励使用异常 （建议阅读 “Write Cleaner Python: Use Exceptions”）

三个好习惯

1. 只作最精确的异常捕获

假如你不够了解异常机制，就不免会对它有一种自然恐惧感。你可能会以为：*异常是一种很差的东西，好的程序就应该捕获全部的异常，让一切都平平稳稳的运行。*而抱着这种想法写出的代码，里面一般会出现大段含糊的异常捕获逻辑。python

让咱们用一段可执行脚本做为样例：git

# -*- coding: utf-8 -*-
import requests
import re


def save_website_title(url, filename):
    """获取某个地址的网页标题，而后将其写入到文件中 :returns: 若是成功保存，返回 True，不然打印错误，返回 False """
    try:
        resp = requests.get(url)
        obj = re.search(r'<title>(.*)</title>', resp.text)
        if not obj:
            print('save failed: title tag not found in page content')
            return False

        title = obj.grop(1)
        with open(filename, 'w') as fp:
            fp.write(title)
            return True
    except Exception:
        print(f'save failed: unable to save title of {url} to {filename}')
        return False


def main():
    save_website_title('https://www.qq.com', 'qq_title.txt')


if __name__ == '__main__':
    main()
复制代码

脚本里的 save_website_title 函数作了好几件事情。它首先经过网络获取网页内容，而后利用正则匹配出标题，最后将标题写在本地文件里。而这里有两个步骤很容易出错：网络请求 与 本地文件操做。因此在代码里，咱们用一个大大的 try ... except 语句块，将这几个步骤都包裹了起来。安全第一 ⛑。github

那么，这段看上去简洁易懂的代码，里面藏着什么问题呢？web

若是你旁边恰好有一台安装了 Python 的电脑，那么你能够试着跑一遍上面的脚本。你会发现，上面的代码是不能成功执行的。并且你还会发现，不管你如何修改网址和目标文件的值，程序仍然会报错 “save failed: unable to...”。为何呢？编程

问题就藏在这个硕大无比的 try ... except 语句块里。假如你把眼睛贴近屏幕，很是仔细的检查这段代码。你会发如今编写函数时，我犯了一个小错误，我把获取正则匹配串的方法错打成了 obj.grop(1)，少了一个 'u'（obj.group(1)）。json

但正是由于那个过于庞大、含糊的异常捕获，这个由打错方法名致使的本来该被抛出的 AttibuteError 却被吞噬了。从而给咱们的 debug 过程增长了没必要要的麻烦。

异常捕获的目的，不是去捕获尽量多的异常。假如咱们从一开始就坚持：只作最精准的异常捕获。那么这样的问题就根本不会发生，精准捕获包括：

永远只捕获那些可能会抛出异常的语句块
尽可能只捕获精确的异常类型，而不是模糊的 Exception

依照这个原则，咱们的样例应该被改为这样：

from requests.exceptions import RequestException


def save_website_title(url, filename):
    try:
        resp = requests.get(url)
    except RequestException as e:
        print(f'save failed: unable to get page content: {e}')
        return False

    # 这段正则操做自己就是不该该抛出异常的，因此咱们不必使用 try 语句块
    # 假如 group 被误打成了 grop 也不要紧，程序立刻就会经过 AttributeError 来
    # 告诉咱们。
    obj = re.search(r'<title>(.*)</title>', resp.text)
    if not obj:
        print('save failed: title tag not found in page content')
        return False
    title = obj.group(1)

    try:
        with open(filename, 'w') as fp:
            fp.write(title)
    except IOError as e:
        print(f'save failed: unable to write to file {filename}: {e}')
        return False
    else:
        return True
复制代码

2. 别让异常破坏抽象一致性

大约四五年前，当时的我正在开发某移动应用的后端 API 项目。若是你也有过开发后端 API 的经验，那么你必定知道，这样的系统都须要制定一套**“API 错误码规范”**，来为客户端处理调用错误时提供方便。

一个错误码返回大概长这个样子：

// HTTP Status Code: 400
// Content-Type: application/json
{
    "code": "UNABLE_TO_UPVOTE_YOUR_OWN_REPLY",
    "detail": "你不能推荐本身的回复"
}
复制代码

在制定好错误码规范后，接下来的任务就是如何实现它。当时的项目使用了 Django 框架，而 Django 的错误页面正是使用了异常机制实现的。打个比方，若是你想让一个请求返回 404 状态码，那么只要在该请求处理过程当中执行 raise Http404 便可。

因此，咱们很天然的从 Django 得到了灵感。首先，咱们在项目内定义了错误码异常类：APIErrorCode。而后依据“错误码规范”，写了不少继承该类的错误码。当须要返回错误信息给用户时，只须要作一次 raise 就能搞定。

raise error_codes.UNABLE_TO_UPVOTE
raise error_codes.USER_HAS_BEEN_BANNED
... ...
复制代码

毫无心外，全部人都很喜欢用这种方式来返回错误码。由于它用起来很是方便，不管调用栈多深，只要你想给用户返回错误码，调用 raise error_codes.ANY_THING 就好。

随着时间推移，项目也变得愈来愈庞大，抛出 APIErrorCode 的地方也愈来愈多。有一天，我正准备复用一个底层图片处理函数时，忽然碰到了一个问题。

我看到了一段让我很是纠结的代码：

# 在某个处理图像的模块内部
# <PROJECT_ROOT>/util/image/processor.py
def process_image(...):
    try:
        image = Image.open(fp)
    except Exception:
        # 说明（非项目原注释）：该异常将会被 Django 的中间件捕获，往前端返回
        # "上传的图片格式有误" 信息
        raise error_codes.INVALID_IMAGE_UPLOADED
    ... ...
复制代码

process_image 函数会尝试解析一个文件对象，若是该对象不能被做为图片正常打开，就抛出 error_codes.INVALID_IMAGE_UPLOADED （APIErrorCode 子类） 异常，从而给调用方返回错误代码 JSON。

让我给你从头理理这段代码。最初编写 process_image 时，我虽然把它放在了 util.image 模块里，但当时调这个函数的地方就只有 “处理用户上传图片的 POST 请求” 而已。为了偷懒，我让函数直接抛出 APIErrorCode 异常来完成了错误处理工做。

再来讲当时的问题。那时我须要写一个在后台运行的批处理图片脚本，而它恰好能够复用 process_image 函数所实现的功能。但这时不对劲的事情出现了，若是我想复用该函数，那么：

我必须去捕获一个名为 INVALID_IMAGE_UPLOADED 的异常
- 哪怕个人图片根本就不是来自于用户上传
我必须引入 APIErrorCode 异常类做为依赖来捕获异常
- 哪怕个人脚本和 Django API 根本没有任何关系

**这就是异常类抽象层级不一致致使的结果。**APIErrorCode 异常类的意义，在于表达一种可以直接被终端用户（人）识别并消费的“错误代码”。**它在整个项目里，属于最高层的抽象之一。**可是出于方便，咱们却在底层模块里引入并抛出了它。这打破了 image.processor 模块的抽象一致性，影响了它的可复用性和可维护性。

这类状况属于“模块抛出了高于所属抽象层级的异常”。避免这类错误须要注意如下几点：

让模块只抛出与当前抽象层级一致的异常
- 好比 image.processer 模块应该抛出本身封装的 ImageOpenError 异常
在必要的地方进行异常包装与转换
- 好比，应该在贴近高层抽象（视图 View 函数）的地方，将图像处理模块的 ImageOpenError 低级异常包装转换为 APIErrorCode 高级异常

修改后的代码：

# <PROJECT_ROOT>/util/image/processor.py
class ImageOpenError(Exception):
    pass


def process_image(...):
    try:
        image = Image.open(fp)
    except Exception as e:
        raise ImageOpenError(exc=e)
    ... ...
    
# <PROJECT_ROOT>/app/views.py
def foo_view_function(request):
    try:
        process_image(fp)
    except ImageOpenError:
        raise error_codes.INVALID_IMAGE_UPLOADED
复制代码

除了应该避免抛出高于当前抽象级别的异常外，咱们一样应该避免泄露低于当前抽象级别的异常。

若是你用过 requests 模块，你可能已经发现它请求页面出错时所抛出的异常，并非它在底层所使用的 urllib3 模块的原始异常，而是经过 requests.exceptions 包装过一次的异常。

>>> try:
...     requests.get('https://www.invalid-host-foo.com')
... except Exception as e:
...     print(type(e))
...
<class 'requests.exceptions.ConnectionError'>
复制代码

这样作一样是为了保证异常类的抽象一致性。由于 urllib3 模块是 requests 模块依赖的底层实现细节，而这个细节有可能在将来版本发生变更。因此必须对它抛出的异常进行恰当的包装，避免将来的底层变动对 requests 用户端错误处理逻辑产生影响。

3. 异常处理不该该喧宾夺主

在前面咱们提到异常捕获要精准、抽象级别要一致。但在现实世界中，若是你严格遵循这些流程，那么颇有可能会碰上另一个问题：异常处理逻辑太多，以致于扰乱了代码核心逻辑。具体表现就是，代码里充斥着大量的 try、except、raise 语句，让核心逻辑变得难以辨识。

让咱们看一段例子：

def upload_avatar(request):
    """用户上传新头像"""
    try:
        avatar_file = request.FILES['avatar']
    except KeyError:
        raise error_codes.AVATAR_FILE_NOT_PROVIDED

    try:
       resized_avatar_file = resize_avatar(avatar_file)
    except FileTooLargeError as e:
        raise error_codes.AVATAR_FILE_TOO_LARGE
    except ResizeAvatarError as e:
        raise error_codes.AVATAR_FILE_INVALID

    try:
        request.user.avatar = resized_avatar_file
        request.user.save()
    except Exception:
        raise error_codes.INTERNAL_SERVER_ERROR
    return HttpResponse({})
复制代码

这是一个处理用户上传头像的视图函数。这个函数内作了三件事情，而且针对每件事都作了异常捕获。若是作某件事时发生了异常，就返回对用户友好的错误到前端。

这样的处理流程纵然合理，可是显然代码里的异常处理逻辑有点“喧宾夺主”了。一眼看过去全是代码缩进，很难提炼出代码的核心逻辑。

早在 2.5 版本时，Python 语言就已经提供了对付这类场景的工具：“上下文管理器（context manager）”。上下文管理器是一种配合 with 语句使用的特殊 Python 对象，经过它，可让异常处理工做变得更方便。

那么，如何利用上下文管理器来改善咱们的异常处理流程呢？让咱们直接看代码吧。

class raise_api_error:
    """captures specified exception and raise ApiErrorCode instead :raises: AttributeError if code_name is not valid """
    def __init__(self, captures, code_name):
        self.captures = captures
        self.code = getattr(error_codes, code_name)

    def __enter__(self):
        # 刚方法将在进入上下文时调用
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        # 该方法将在退出上下文时调用
        # exc_type, exc_val, exc_tb 分别表示该上下文内抛出的
        # 异常类型、异常值、错误栈
        if exc_type is None:
            return False

        if exc_type == self.captures:
            raise self.code from exc_val
        return False
复制代码

在上面的代码里，咱们定义了一个名为 raise_api_error 的上下文管理器，它在进入上下文时什么也不作。可是在退出上下文时，会判断当前上下文中是否抛出了类型为 self.captures 的异常，若是有，就用 APIErrorCode 异常类替代它。

使用该上下文管理器后，整个函数能够变得更清晰简洁：

def upload_avatar(request):
    """用户上传新头像"""
    with raise_api_error(KeyError, 'AVATAR_FILE_NOT_PROVIDED'):
        avatar_file = request.FILES['avatar']

    with raise_api_error(ResizeAvatarError, 'AVATAR_FILE_INVALID'),\
            raise_api_error(FileTooLargeError, 'AVATAR_FILE_TOO_LARGE'):
        resized_avatar_file = resize_avatar(avatar_file)

    with raise_api_error(Exception, 'INTERNAL_SERVER_ERROR'):
        request.user.avatar = resized_avatar_file
        request.user.save()
    return HttpResponse({})
复制代码

Hint：建议阅读 PEP 343 -- The "with" Statement | Python.org，了解与上下文管理器有关的更多知识。

模块 contextlib 也提供了很是多与编写上下文管理器相关的工具函数与样例。

总结

在这篇文章中，我分享了与异常处理相关的三个建议。最后再总结一下要点：

只捕获可能会抛出异常的语句，避免含糊的捕获逻辑
保持模块异常类的抽象一致性，必要时对底层异常类进行包装
使用“上下文管理器”能够简化重复的异常处理逻辑

看完文章的你，有没有什么想吐槽的？请留言或者在项目 Github Issues 告诉我吧。

附录

题图来源: Photo by Bernard Hermant on Unsplash
更多系列文章地址：https://github.com/piglei/one-python-craftsman

系列其余文章：

Python 工匠： 异常处理的三个好习惯

前言

三个好习惯

1. 只作最精确的异常捕获

2. 别让异常破坏抽象一致性

3. 异常处理不该该喧宾夺主

总结

附录

Python 工匠：异常处理的三个好习惯