下面以账号表为例，介绍相关api命名、参数、返回值等编写规范。
1、账号详情
接口名称： get
功能说明： 获取某个账号详情
请求参数：
| 参数名称: | 参数类型: | 是否必须: | 参数说明: |
|---|---|---|---|
| _id | ObjectId | Y | 账号ID |
api result schema：account_detail
account_detail:
strict_mode: true
model_name: account
meta: object_result
data:
_id:
type: 'object_id'
example: '5da57976ce6d2a647d539af0'
note: 'id'
name:
type: 'string'
example: '张三'
note: '用户名称'
group_info:
type: 'object_ref'
schema: group_brief
返回结果：
{
"_id":"5a72897dce6d2a27056b219f",
"name":"憨憨",
"group_info": {
"_id": "5a72897dce6d2a27056b219g",
"name": "后端组"
},
}
代码示例：
@api_result('account_detail')
def get(self, params, **kwargs):
_id = param_convert.object_id_param('_id', params)
record = api_model_loader.load_account_info(_id)
return record
2、账号列表
接口名称： find
功能说明： 根据筛选及分页条件获取账号列表
注意事项： 需要考虑根据查询条件构建合适的索引
请求参数：
| 参数名称: | 参数类型: | 是否必须: | 参数说明: |
|---|---|---|---|
| _meta | dict | N | 分页参数 |
| name | string | N | 名称 |
| state | int | N | 状态 |
请求示例：
{
"_meta": {
"limit": 30,
"page": 1
},
"state": 100
}
api result schema：account_list_item
account_list_item:
strict_mode: true
model_name: account
meta: object_result
data:
_id:
type: 'object_id'
example: '5da57976ce6d2a647d539af0'
note: 'id'
name:
type: 'string'
example: '张三'
note: '用户名称'
返回结果：
{
"_meta": {
"has_more": true,
"page": 1,
"page_size": 30,
"result_count": 1148
},
"data": [
{
"_id": "5a72897dce6d2a27056b219f",
"name": "憨憨1"
},
{
"_id": "5a72897dce6d2a27056b219e",
"name": "憨憨2"
}
]
}
代码示例：
@api_result_set_with_meta('account_list_item')
def find(self, params, **kwargs):
spec = apply_dict_by_rules(params, {
'name': (
param_convert.str_param_opt,
),
'state': (
param_convert.int_param_opt,
),
})
default_sort = [('_id', -1)]
return build_result_set_meta(db.Account.find, spec=spec, default_sort=default_sort, params=params)
3、账号创建
接口名称： create
功能说明： 添加新账号
请求参数：
| 参数名称: | 参数类型: | 是否必须: | 参数说明: |
|---|---|---|---|
| name | string | Y | 名称 |
| phone | string | Y | 手机号 |
| state | int | Y | 状态 |
| group_id | object_id | N | 所属组ID |
api result schema：generic_summary
generic_summary:
strict_mode: true
meta: object_result
data:
_id:
type: object_id
example: '5a72897dce6d2a27056b219f'
note: 对象ID
返回结果：
{
"_id":"5a72897dce6d2a27056b219f"
}
代码示例：
@api_result('generic_summary')
def create(self, params, **kwargs):
doc = apply_dict_by_rules(params, {
'name': (
param_convert.str_param_opt,
),
'phone': (
param_convert.str_param_opt,
),
'state': (
param_convert.int_param_opt,
),
'group_id': (
param_convert.object_id_param_opt,
),
})
try:
biz = AccountBiz.instance()
record = biz.create_record(doc)
except RpcRuntimeError as e:
raise errors.ApiError(zh_message=e.zh_message)
return record
4、账号编辑
接口名称： update
功能说明： 编辑账号信息
请求参数：
| 参数名称: | 参数类型: | 是否必须: | 参数说明: |
|---|---|---|---|
| _id | object_id | Y | 名称 |
| name | string | N | 名称 |
| phone | string | N | 手机号 |
| state | int | N | 状态 |
| group_id | object_id | N | 所属组ID |
api result schema：generic_summary
返回结果：
{
"_id":"5a72897dce6d2a27056b219f"
}
代码示例：
@api_result('generic_summary')
def update(self, params, **kwargs):
record_id = param_convert.object_id_param('_id', params)
record = api_model_loader.load_account_info(record_id)
doc = apply_dict_by_rules(params, {
'name': (
param_convert.str_param_opt,
),
'phone': (
param_convert.str_param_opt,
),
'state': (
param_convert.int_param_opt,
),
'group_id': (
param_convert.object_id_param_opt,
),
})
try:
biz = AccountBiz.instance()
record = biz.update_record(record, doc)
except RpcRuntimeError as e:
raise errors.ApiError(zh_message=e.zh_message)
return record
5、获取记录详情
接口名称： find_one
功能说明： 获取指定条件的记录详情
场景说明： 通常用于要根据不同纬度来获取一条记录详情，例如通过身份证号或者手机号来定位用户
请求参数：
| 参数名称: | 参数类型: | 是否必须: | 参数说明: |
|---|---|---|---|
| phone | string | N | 手机号 |
| identity_card_id | string | N | 身份证号 |
返回结果：
{
"_id":"5a72897dce6d2a27056b219f",
"name":"憨憨",
"group_info": {
"_id": "5a72897dce6d2a27056b219g",
"name": "后端组"
},
}
6、获取全量数据
接口名称： select
功能说明： 不带分页获取所有数据
场景说明： 获取下拉框可选项
注意事项： 只返回需要用到的_id和name字段
请求参数： 无
返回结果：
{
"data": [
{
"_id": "5a72897dce6d2a27056b219g",
"name": "后端组"
},
{
"_id": "5a72897dce6d2a27056b219e",
"name": "产品组"
}
]
}
7、操作类
接口名称： mark_*
功能说明： 操作类标记相关状态
举例说明：
- 标记完成：mark_done
- 标记进行中：mark_doing
- 标记删除：mark_delete
- 标记取消：mark_cancel
- 标记关闭：mark_close
- 打标签：mark_label
- 标记异常：mark_abnormal
请求参数：
| 参数名称: | 参数类型: | 是否必须: | 参数说明: |
|---|---|---|---|
| _id | object_id | Y | 主键ID |
返回结果：
{
"ok": true
}
8、批量处理类
接口名称： batch_*
功能说明： 批量操作类
举例说明：
- 批量添加：batch_add_xxx
- 批量删除：batch_delete_xxx
请求参数：
| 参数名称: | 参数类型: | 是否必须: | 参数说明: |
|---|---|---|---|
| _ids | list | Y | 主键ids |
返回结果：
{
"ok": true
}
9、批量操作文档类
接口名称： batch_*
功能说明： 批量添加/编辑
举例说明：
- 批量创建：batch_create
- 批量删除：batch_update
- 批量提交：batch_submit
请求参数：
| 参数名称: | 参数类型: | 是否必须: | 参数说明: |
|---|---|---|---|
| docs | list | Y | 文档信息列表 |
请求示例：
{
"docs": [
{
"name": "后端组"
},
{
"name": "产品组"
}
]
}
返回结果：
{
"ok": true
}
10、支付类
功能说明： 涉及到金额类的操作
举例说明： 充值、提现、转账、收款
特别注意：
- 接口幂等性
- 通过一定的策略确保同一单据提供给三方交易系统的单号唯一
- 通过创建唯一索引来防止重复打款
- 对于调用第三方交易系统，做成定时任务并使用单进程去执行处理
- 操作钱包中金额字段时要使用mongodb中原子性的相关操作，例如：
pull、$push等
下面以给钱包账号充值为例，我们可以在model中增加如下方法：
def pre_recharge_money(self, money, trans_id):
"""开始充值金额"""
spec = {
'_id': self['_id'],
'pending_transactions': {'$ne': trans_id},
}
doc = {
'$inc': {
'balance_money': money,
'frozen_money': money,
},
'$push': {
'pending_transactions': trans_id
}
}
return self.update_doc(spec, doc, check_updated_state=True)
def rollback_recharge_money(self, money, trans_id):
"""回滚充值金额"""
spec = {
'_id': self['_id'],
'pending_transactions': trans_id,
}
doc = {
'$inc': {
'balance_money': -money,
'frozen_money': -money,
},
'$pull': {
'pending_transactions': trans_id
}
}
return self.update_doc(spec, doc, check_updated_state=True)
def commit_recharge_money(self, money, trans_id):
"""提交充值金额"""
spec = {
'_id': self['_id'],
'pending_transactions': trans_id,
}
doc = {
'$inc': {
'frozen_money': -money,
},
'$pull': {
'pending_transactions': trans_id
}
}
return self.update_doc(spec, doc, check_updated_state=True)
注意：针对有些场景api没有定义规范的，需要一起制定完此类情况的开放流程规范后在进行开发。
