应用于Restful接口的错误码设计 – ErrorCode Class(Python)

前言:
在前一家公司将工作方向切换为 Python Web 后, 基于现在流行的
Restful 接口开发方式开发, 在工作过程中, 也会遇到 http 状态码
不够表达具体 Web 业务服务层的某些错误状态, 参考新浪微博错误码的设计,
项目初期也定义了大量的常量类. 笔者在实践中, 使用 Python 实现的
常量类的方式也是随着对语言本身特性的理解而演化.

首先先理解使用错误码 class 能做什么:
1. 定义错误码数值, 并且文档化, 对应业务接口在异常发生时返回实际的值.
2. 每个错误码值是一个整型, 并且需要定义其值的描述内容, 返回错误信息时,
也同时携带其值的描述信息, 可参考新浪微博错误码.
3. 错误码定义不能重复.
4. 基于以上三点: 目的是方便客户端开发理解错误内容.

版本1

定义一个 class, class 仅作一个作用域, 作用域里每个 class 属性即常量整型(错误码),
声明每个常量变量后, 需要再将该作用域下的所有常量值整合为一个 dict 映射.

第一个版本的例子的虽然满足了需求1,2, 但随着业务需求增加,
不断添加新的错误码. 也会有如下缺陷:
* 表示一段业务错误描述时, 同时还要维护 CODE_MAP dict,
* 开发者本身也会疏忽的时候, 忘记定义声明也是不可避免的,
* 需求点 3 可能有于维护失误导致重复数值, 代码review 也不能
完全保证错误码的唯一性质. 而且因为维护 CODE_MAP,
要求写代码时需要将常量的变量输入两次.

改进代码的可选方案:
1.以配置文件为准, 推荐使用 yaml, 清晰, 相比于 json,xml 打字少.
再写脚本自动化生成代码.
2. 因为本身使用 Python, 利用其本身的语言特性支持,
原则是 write less, but expressed in abundance.

版本2

根据版本1的改进计划的第2点, 我们可以利用 metaclass,
需要了解的 Python 语言背景知识:
* metaclass
* __new__ 方法的作用
* 参考第三方ORM库的 model 与 field 实现(eg: sqlachelmy, peewee).

改进之后的优点:
1. 需求4点均能满足
2. 实际业务中只需继承 BaseErrorCode, 每个业务的错误码
只需一行既能表达整型值和对应的错误描述信息, 收拢于一处.
3. 因为 ErrorCodeField 继承int, 因此具有 int 性质本身,
json 序列化时依然正确识别为 number.

实践样例:

如果仅仅满足于 error_code 实现, 版本2即可.
但扩展为 const 常量类使用, 并且支持多类型常量,
那么需要将版本2修改为通用的实现.

版本3

笔者基于业务中对Python使用经验的积累, 实现一个通用的
const class 工具库: kkconst

使用样例:

原创文章,转载请注明: 转载自kaka_ace's blog

本文链接地址: 应用于Restful接口的错误码设计 – ErrorCode Class(Python)

2 thoughts on “应用于Restful接口的错误码设计 – ErrorCode Class(Python)

发表评论

电子邮件地址不会被公开。 必填项已用*标注