响应格式自定义
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 都可以使用统一的 stat3.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 传送门
Last updated