目录
基本架构
模拟实例
理论依据
实例
从属关系
并列关系
总结
API设计
代码与RESTful API
需求:用户组管理
创建/编辑用户组
删除用户组
列举用户组
规划数据集
把数据集划分为资源
用URI为资源命名
若待定义的数据类型可由其他数据组合而成,则直接使用allOf,如下图所示。
若数据有多重描述形式,使用多态(oneOf),如下图所示。
url是数据的地址,json是数据的描述,数据之间存在从属和并列关系
有一个文件表file
表file的从属数据是文件总数items_count,所有文件items,items的从属数据是每个文件的数据item
在url中的表现:斜杠分隔的层级关系,/file/items_count,/file/items,/file/items/item1,item2
在json中的表现:file object内包含items_count和items字段,items array内包含item1,item2元素
表file中的items_count和items,items中的各个item之间
在url中的表现:逗号分隔的并列关系,/file/items_count,items,/file/items/item_id1,item_id2
在json中的表现:file object中items_count和items字段,items array中item1,item2元素
1. 数据之间的从属与并列关系,均可以通过数据的唯一标识即预定义的名字(object中字段的key)或随机生成的id(array中元素的id),在url和json中表达,即object中字段的key和array中元素的id,均可出现在url和json中
2. 并列关系的数据,即数据的集合,可用json中的object或array表示
获取所有信息
get /file
或
get /file/items_count,items
{
"items_count": 2,
"items": [
{
"id": 1,
"parent_id": "xxxx",
"name": "item1"
},
{
"id": 2,
"parent_id": "yyyy",
"name": "item2"
}
]
}
获取文件总数
get /file/items_count
{
"items_count": 2,
}
获取所有文件
get /file/items
{
"items": [
{
"id": 1,
"parent_id": "xxxx",
"name": "item1"
},
{
"id": 2,
"parent_id": "yyyy",
"name": "item2"
}
]
}
或
[
{
"id": 1,
"parent_id": "xxxx",
"name": "item1"
},
{
"id": 2,
"parent_id": "yyyy",
"name": "item2"
}
]
获取文件1
get /file/items/1
{
"id": 1,
"parent_id": "xxxx",
"name": "item1"
}
或
认为获取单个是获取多个的特例
[
{
"id": 1,
"parent_id": "xxxx",
"name": "item1"
}
]
获取文件1,文件2
get /file/items/1,2
[
{
"id": 1,
"parent_id": "xxxx",
"name": "item1"
},
{
"id": 2,
"parent_id": "yyyy",
"name": "item2"
}
]
RESTful API的设计思路和面向对象的程序设计类似
用户组包含以下信息:
名称 |
必填 |
可编辑 |
备注 |
组名 |
Y |
Y |
用户组唯一,不能包含 空格 或 \ / : * ? " < > | 特殊字符, 长度不能超过128个字符。 |
备注 |
N |
Y |
0-255个字符,不限制字符类型。 |
如果被删除的用户组不存在,逻辑上认为删除成功,但不需要记录删除日志。
根据需求,确定服务内包含哪些数据,类似代码中定义结构体或者类
// 用户组功能有两个表
// 组相关信息
type group struct{
id string // 组ID
name string // 组名
notes string // 备注
}
// 组成员
type groupMember struct{
id string // 成员ID
group_id string // 组ID
type string // 成员类型:user、department
}
数据集划分为资源,类似代码中的实例化对象
var groups map[string]group
var groupMemebers map[string][string]groupMember
对象的名字即为URL,如果设计出来的url很复杂或者设计比较困难,那么需要考虑数据集规划是否合理
// 所有用户组
var groups map[string]group
// URL
/groups
// 某一用户组
groups[id]
// URL
/groups/{id}
// 某一用户组的特定信息:name,notes
groups[id].name
groups[id].notes
// URL
/groups/{id}/{fields} // fields可以为name或者remark或者两者组合,用逗号分隔
// 所有用户组成员
var groupMemebers map[string][string]groupMember
// URL
/group-members
// 某一用户组所有成员
groupMembers[groupID]
// URL
/group-members/{group_id}
// 某一用户组中某一成员
groupMembers[groupID][memberID]
// URL
/group-members/{group_id}/{member_id}
// 某一用户组中某些成员
groupMembers[groupID][memberID1]
groupMembers[groupID][memberID2]
// URL
/group-members/{group_id}/{member_ids} // member_ids为多个member_id的数组,用逗号分隔