在flask-restplus下统一接口返回格式

背景

在使用flask+flask-restplus时，业务正常时接口函数返回一个可以json序列化的对象

@ns.route('/hello')
class Hello(Resource):
    def get(self):
        return ['hello', 'hi']

接口返回内容如下：

[
    "hello",
    "hi"
]

当业务异常（比如检测到参数错误）时，一般调用abort函数，它会抛出一个HTTPException

@ns.route('/error')
class Error(Resource):
    def get(self):
        abort(400, 'params error')

接口返回内容如下：

{
    "message": "params error"
}

由于公司规范要求，需要使用统一的http请求响应模板，如下：

{
    'code': 100000,
    'message': 'xxx'
    'data': 'hello'
}

因此，我们需要对接口返回格式进行改造。

接口返回值统一处理

为了不改变原有的编码习惯，又能够达到以上返回格式的要求，我们可以使用flask-restplus的representation装饰器来注册一个接口返回内容处理器

@api.representation('application/json')
def output_json(data, code, headers=None):
    result = {}
    if api.specs_url == request.url:
        result = data
    elif code in (200, 201, 204):
        result['code'] = 100000
        result['data'] = data
    else:
        result['code'] = data.get('code') or 200000
        result['message'] = data['message']
    response = make_response(json.dumps(result), code)
    response.headers.extend(headers or {})
    return response

现在再来请求上面的两个接口，返回格式变成了我们想要的格式

{"code": 100000, "data": ["hello", "hi"]}
{"code": 200000, "message": "params error"}

自定义异常处理

如果抛出不是HTTPException的异常，会发现并不能得到具体的异常内容，只会得到以下结果：

{"code": 200000, "message": "Internal Server Error"}

如果想要将一些指定的异常内容返回，比如我们自定义了以下的异常类：

class BaseException(Exception):
    http_code = 500
    business_code = 200000

    def __init__(self, message=None):
        if message:
            self.message = message

    def to_dict(self):
        data = {'code': self.business_code, 'message': self.message}
        return data


class InsufficientPrivilege(BaseException):
    http_code = 403
    business_code = 200001
    message = '权限不足'

那么我们可以使用flask-restplus的errorhandler装饰器来注册一个异常处理器，在这个处理器中将自定义异常转换为正常接口返回格式

@api.errorhandler(BaseException)
def handle_base_exception(error):
    return error.to_dict(), error.http_code

这样自定义异常也可以返回异常内容了

{"code": 200001, "message": "权限不足"}

当然我们也不能将异常都转为BaseException一股脑抛出，这样做的话会将因程序不健壮导致的异常也抛出，会给用户带来不好的体验。