响应格式自定义

1 背景

编写的 web 服务可能会和很多服务进行对接，交互的格式一般是约定好的，比如有如下几种方式

1.1 butterfly response 格式

butterfly response 格式

{
    "stat": "OK"                        // str , 错误是标识为 ERR_XXX (XXX 为错误简要内容）
    "data":  {name: "liming"}           // object
             {list: [{name: "liming"}, {name: "fengchengcheng"}]}
             {}                         // 如果是提交表单这类 API，没有数据需要返回的话，可以返回空的 object
}

1.2 其他 response 格式

1.2.1 amis 要求的格式

{
  "status": 0,
  "msg": "",
  "data": {
    ... 其他字段
  }
}

• status: 返回 0，表示当前接口正确返回，否则按错误请求处理；

• msg: 返回接口处理信息，主要用于表单提交或请求失败时的 toast 显示；

• data: 必须返回一个具有 key-value 结构的对象。

1.2.2 openstack neutron

安全组详情

// OK
{
    "security_group": {
        "description": "ceshi",
        "security_group_rules": [],
        "name": "ceshi",
        ...
    }
}


// Error
{
	"NeutronError": {
		"message": "Security group 80086c1e-a796-4aa6-b828-1e8c36c8c15fx does not exist",
		"type": "SecurityGroupNotFound",
		"detail": ""
	}
}

1.2.3 other

1

code: 业务返回的返回码 int
    正确：统一返回 0
    错误：
message: 人类可读的消息，即请求的结果 string
data: 可选的返回数据，与业务相关 可嵌套

2

success:
    正确：true
    错误：false
message: 人类可读的消息，即请求的结果 string
data: 可选的返回数据，与业务相关 可嵌套

2 分析

分析上面多种返回格式，可以看出 stat 字段与 code 和 message 两个字段的含义相同

如果多个服务协调工作的话，服务的返回 code 和 message 应该是多个服务保持一致的，否则同一个返回码如果是多种含义的话，则后期维护会非常不方便

2.1 AMIS 前端实现方法

配置接收适配器

如果后端返回的响应结构不符合 amis 的接口格式要求，而后端不方便调整时，可以配置 adaptor 实现接收适配器

接收适配器 是指在接口请求后，对响应进行一些自定义处理，例如修改响应的数据结构、修改响应的数据等等。

例如：接口正确返回的格式中，会返回"code": 200，而 amis 中，接口返回格式需要"status": 0，这时候就需要接收适配器进行调整结构。

3 目标

butterfly 会将 stat 字段的状态统一存放，多个 handler 都可以使用统一的 stat

3.1 如何修改返回样式

3.1.1 stat 转换为 code

stat 转换为 code（错误码）

编写 handler 时仍然使用 stat 进行标识返回正常还是异常

（1）stat 的统一管理包中增加对 code + message 的转换
     可以增加一个字典，存放 stat 标识与 code + message 对应关系
     1>每个 stat 返回码都对应一个特定的  code + message
     2>如果返回的错误 stat 标识在字典中没有找到的话，返回默认错误 code + message
（2）conf/config.py 增加返回格式开关，通过开关设置返回 stat 还是 code + message 字段

同时通过统一管理来避免 code + message 导致返回码和信息不对应问题

3.1.2 stat 转换为 success

stat 转换为 success（是否成功 bool)

编写 handler 时仍然使用 stat 进行标识返回正常还是异常

（1）stat 转换
    失败：{"success": false, "message": "ERR_xxx","data": {}}
    成功：{"success": true, "message": "OK","data":{}}
（2）conf/config.py 增加返回格式开关，通过开关设置返回 stat 还是 code + message 字段

同时通过统一管理来避免 code + message 导致返回码和信息不对应问题

4 实现

4.1 转换方式

                               +----------------+
                     +-------->| "status_name"  | (string) 状态字段
                     |         +----------------+
+----------+         |         +----------------+
|  "stat"  |---------+-------->| "status_map"   | (dict) 状态 map，默认是 default 信息，若 "stat" 在 map 中，则是对应 value 值
+----------+         |         +----------------+
                     |         +----------------+
                     +-------->| "message_name" | (string) message 信息，与 "stat" 信息一致
                               +----------------+

4.2 兼容

• 百川依赖 "stat" 状态字段

• amis 前端目前使用了 "stat" 状态字段进行转换

故改为添加 STAT_ADAPTOR 时，仅扩展状态字段信息

4.2 code

4.2.1 配置

butterfly/conf/config.py

# 默认值
STAT_ADAPTOR=None

# 要转换状态字段 {"stat":"ERR", "data":{}} --> {"stat":"ERR", "success":False, "message":"ERR", "data":{}}
STAT_ADAPTOR={"status_name":"success", "status_map":{"OK":True,"default":False}, "message_name":"message"}

4.2.2 code

5 传送门

• amis api