DDL、DML和DCL的解

一、DDL

上个月写了一个集体受到的 BaaS API 的设计规范,给大家分享下:

 1、DDL的概述

目录

      DDL(Data Definition Language
数据定义语言)用于操作对象以及目的的性质,这种对象包括数据库本身,以及数据库对象,像:表、视图等等,DDL对那多少个目的与属性的军事管制暨概念具体表现在Create、Drop和Alter上。特别注意:DDL操作的“对象”的定义,”对象“包括对象和对象的性,而且对象极其小吗相比记录非凡只层次。以表明举例:Create创制数据表,Alter能够转该表的字段,Drop可以去除这些表,从此处我们可看,DDL所立的冲天,他非会合指向现实的数开展操作。

  1. 引言… 4

 

1.1. 概要… 4

2、DDL的重大谈(操作)

1.2. 参考资料… 4

      Create语句:可以创设数据库和数据库的一对对象。

1.3. 观看对象… 4

     
Drop语句:可以去除数据表、索引、触发程序、条件约束与数据表的权杖等。

1.4. 术语解释… 4

      Alter语句:修改数据表定义及性能。

  1. API 设计规范… 5

 

2.1. 地址格式… 5

3、 DDL的操作对象(表)

2.2. 输入与输出… 6

      1)、表的定义

2.2.1. 通用输入数据… 6

           
表的创设就是用来存放数据用的,由于大家存放的数码的例外,所以我们需要定义来数据类型,以方便管理。

2.2.2. 主体输入… 6

      2)、表底性

2.2.3. 通用输出数据… 6

           
主键属性:主键就是主键约束,只不过由底名不同了,主键的起名偏向于虚的(就是讲述描述这起事),主键约束起名偏向吃实得(就是讲述操作的履行),描述的且是同项事,主键约束就是表中的一个性;在一个发明中可是多好出一个主键;一个主键可以定义在一个如故六个字段;主键使一个依然多单字段的价必须唯一且非也空,这样做足由此该字段或欠组字段受到的价唯一的代表同样长长的记下。

2.2.4. 状态码… 7

           
唯一属性:一个表中只好发出一个主键属性,为了方表用户,提议唯一约束;唯一约束好定义在一个要么四个字段上;唯一约束而该字段或欠组字段被之值唯一,可以呢空,但是,不可能重复。

2.2.5. 分外处理… 7

           
外键属性:又给外键,又给外键约束,跟主键和主键约束之关联是相同的;外键约束针对的点滴个表达,假如表A的主关键字是表B中的字段,则该字段称为表B的外键,表A称为主表,表B称为从表,但倘使顾,必须要总结机要明了你是这种涉及。
            核查、Null和缺省性:核查属性又给核查约束,Null属性又给Null约束,缺省属性又叫缺省约束;这一个号是叙一桩事,描述一种情形,这件事要及时张情形大家自然可以人工的那么特意做(输入数据是注意就执行),不过,他们之本心是促成自动化,也便是叫电脑做就件事。

2.2.6. 其它… 8

 

2.3. API操作设计… 8

二、DML

2.3.1. 资源型操作… 8

1、DML的概述

2.3.2. 业务型操作… 12

     DML(Data Manipulation Language
数据操控语言)用于操作数据库对象吃富含的数目,也就是说操作的单位是记录。

  1. API 匡助文档规范… 12

 

3.1. 扶植文档内容规范… 12

2、DML的根本谈(操作)

3.2. 文档编写方法… 13

     Insert语词:向数表张插入一长记下。

3.3. 相助文档XML模板… 13

   
 Delete语词:删除数据表中的均等条或多长时间记下,也足以去除数据表中的拥有记录,然则,它的操作对象仍是记录。

     Update语句:用于修改就存在表中的笔录之情节。

1. 引言

 

1.1. 概要

BAAS 阳台及之具备 API,必须严峻服从仍标准。

透过本文档规范 BAAS 平台具有为他提供
API,呈现技术的统一性、规范性。并令所有 API
尽量靠近业界规范之而,提升API的易用性、可读性、兼容性等,并有益于平台的使用者更快地觉察、熟谙所有API以供应开发。

关键涵盖多个点的业内:API 本身的设计规范、API 匡助文档的编制规范。

3、DML的操作对象——记录

1.2. 参考资料

Representational State Transfer
(REST)

     1)、注意当我们对记录举行Insert、Delete和Update操作的时段,一定要顾,一定即便精通DDL对那一个的一对操作。

1.3. 看对象

· 需要把 API 公布到BAAS 平台受到的具有开发者。

· 使用 BAAS API 的开发者。

 

1.4. 术语说

Ø
BAAS:后端即服务。参见:《BaaS服务的定义、发展和将来》。

Ø REST:一种植开放的基于互联网的软件架构格局。参见:《Representational
State Transfer
(REST)
》。

三、DCL

2. API设计规范

1、DCL的概述

2.1. 地方格式

对于发布之所有 API,地址应该满足以下格式:

· 格式一,直接看资源型:

/api/v(version)/area/resources/{id}

· 格式二,资源查询型:

/api/v(version)/area/resources/param1Name/param1Value/param2Name/param2Value/?optionalParameters

· 格式三,资源操作型、跨资源业务型:

/api/v(version)/area/resources or controller/action?parameters

示例:

/api/v1.0/acs/users/ 表示访问有的用户资源。

/api/v1.0/acs/users/1 表示访问 Id 为 1 的用户。

/api/v1.0/acs/users/group/iws-tech/minAge/30 表示访问 iws-tech
组中极小年龄30春的用户。

/api/v1.0/acs/accounts/UpdateAllUserFlags 表示更新具有用户的某某标识。

别表达:

Version 代表版本号,只爆发点儿层的版本号。

不等之版本号之间,原则达成可免包 API 的匹配。

某版本要公布,在与一个版本号之内的 api 升级,必须确保兼容原来发表之
API。不可知匹配时,需要使用新的 API 地址,同时务必保留原有的 API。

Area 表示有业务模块,如 ACS、Org、OneDoc、OnePlus 等。

     DCL(Data Control Language
数据控制语句)的操作是数据库对象的权能,这多少个操作的确定要数据更是的安。

2.2. 输入与出口

 

2.2.1. 通用输入数据

对此任何BAAS中每一个 API 的调用都用交的数量,使用 Http Header
来进展传输。例如:App 授权码、用户标识 等音信。

某个 Area 中大量 API都亟待交的多寡,也相应下 Http Header
来开展付出。

2、DCL的紧要谈(操作)

2.2.2. 主旨输入

设想到接口的扩张性,所有API的输入只好承受相似的 JSON
对象作为输入参数,同时为不得不输出一个 JSON 对象。

当输入输出的值是单纯值、数组时,需要选拔一个目的对该展开打包。

富有 JSON 对象的属性名,全体运首字母小写的驼峰式语法。

   
 格兰特(Grant)语句子:允许对象的创造者给某用户要某组或享有用户(PUBLIC)某些特定的权能。

2.2.3. 通用输出数据

于 CDU 以及修改数据为主底操作型API的应,都要重临一个统一的数格式
Result,该组织定义如下:

{ success: boolean, statusCode: int, message: string, data: object }

其中:

success:表示该操作是否成功。

statusCode:该操作而发多回到的状态,使用statusCode进行区分。一般意况下,statusCode
重回1或0表示成功依旧黄。该属性用于为开发者举行次分支的逻辑判断用。

message:总是回到一个可用于客户端展现的字符串。该属性用于显示为软件使用者查看。

data是然则选属性。即如无额外的数目,可以无data属性,也得data 重临null。

     Revoke语句子:可以放任某用户或某组或享有用户访问权限

2.2.4. 状态码

状态码分为有限接近,一个凡 Http 状态码;一个是 Result 数据结构中之
StatusCode 状态码。HTTP 状态码表示该 HTTP
请求的处理状态。一个假设否成是出于 HTTP 状态码声明的. 一个 2XX
的状态码表示成功, 而一个 4XX 表示要失利.

诚如情况下,假设会运用 HTTP 状态码表示的状态,应该先使用 HTTP
状态码。其次,BAAS 内部的各样事务逻辑状态,则应当由 StatusCode 来注明。

  1. 对 HTTP 状态码而言,所有API暂时仅行使以下状态码:

· 200:操作成再次回到。

· 201:表示成立成功,POST 添加多少成功后必回到此状态码。

· 400:请求格式不对准。

· 401:未授权。(App、User)

· 404:请求的地点不找到。如 users/1 未找到该资源。

· 500:内部程序错误。

中,201、404眼看点儿只状态码,是用API开发者在各种一个API中,依据工作逻辑的推行结果来主动回来的。另外的状态码由框架统一举行重返。

  1. StatusCode

StatusCode将统一采纳6位编码,代表享有不同的事情逻辑分支。6各个编码中之眼前片各项表示不同的Area
(模块),由BAAS平台统一标准。后四各由模块开发者自行定义。如:01象征ACS,那么010001或者意味着ACS模块中之登录API的用户称错误、010002意味着ACS中之登录API的用户密码错误。

 

2.2.5. 杀处理

吁失利重临 4XX 后,响应的基点仍旧 Result 数据格式。其中 message
表示错误的消息。方便开展调剂。如:

HttpStatusCode:404

Response Body:{success:false, statusCode:100003,
message:’不设有拖欠用户。’}

3、DCL的操作对象(用户)

2.2.6. 其它

日的格式:API重临 值中之时空,都统一以UTC格式 时间。

API的返值备受,假如欲包含调试相关信息(如调用时间、调用次数等于),由BAAS平台框架统一处理,不独立在各API中拍卖。

     此时之用户因的凡数据库用户。

2.3. API操作设计

每个具体的
API地址,都是一个操作。操作分为两种档次:资源型操作、业务型操作。

2.3.1. 资源型操作

资源型操作是满意REST规范化设计的。在统筹API
时,应竭尽首选这种格局。即:如果 API
能抽象为资源的CRUD操作的,应该尽可能先抽象为对资源的操作。

2.3.1.1. 添加

地方:资源列表地址。如 /users/。

使 POST动作提交实体对应之JSON格式数据。

2.3.1.2. 更新

地址:具体有资源的地方。如 /users/1,表示id为1的用户。

动作:使用 PUT 动作提交。

数据格式:实体的 JSON格式数据。其中,JSON
数据被不需要列全有的习性,只待列有得更新的属性即可。

如:PUT /users/1 {username:’hqf’}。

相应的响应是:

HttpStatusCode:200

ResponseBody: { success: true, statusCode: 1, message: ‘更新成功!’}

(另:要是下 ASP.NET WebApi
框架搭建API,则这里用提供合之框架处理此类型的反种类化。)

2.3.1.3. 删除

地址:具体某个资源的地点。如 /users/1。

动作:使用DELETE动作提供请求。

如:DELETE /users/1

对应之响应是:

HttpStatusCode:200

ResponseBody: { success: true, statusCode: 1, message: ‘删除成功!’}

2.3.1.4. 批量封存

计划指出:尽量不要啊各一个资源提供批量保留之操作。只有在针对资源的操作的性能要求相比较高时,才接纳性提供。

地址:资源列表地址。如 /users/。

动作:使用 POST 动作提供数据。

数码格式:使用一个 JSON 对象提交数据,该目的被含有一个属性名为
list,属性类型为数组的特性。该数组吃之每一个对象都是假若翻新的实业对象。

对于各级一个实体对象:能够呢各一个子实体对象上加 persistenceStatus
属性,值为 Deleted、Modified、New
来代表该实体的状态:删除、更新、添加。如若非提供该属性,那么一旦实体有
Id 属性,则表示更新,否则表示添加。

例如:

{list:[

{name:’c1′, persistenceStatus:’New’},

{id:1, name:’c2′, persistenceStatus:’Modified’},

{id:2, persistenceStatus:’Deleted’}

]}

为只是略为:

{list:[

{name:’c1′},//添加

{id:1, name:’c2′},//更新

{id:2, persistenceStatus:’Deleted’}

]}

2.3.1.5. 保存聚合子

统筹提出:在待创新聚合子实体时,如若发表了聚合子资源
API,那么相应首选之资源来兑现保存。否则,才可以在改进聚合父实体时,同时革新她的聚合子实体。

地址与动作:保存聚合子使用聚合父资源均等之地点及动作,见:更新

数据格式:聚合父对象中生出聚合子对应之属性,该属性使用批量翻新受定义之数码格式来定义需要立异的聚合子实体集合。见:批量封存。如:

{name:’parent’, children:[

{name:’c1′, persistenceStatus:’New’},

{id:1, name:’c2′, persistenceStatus:’Modified’},

{id:2, persistenceStatus:’Deleted’}

]}

呢可粗略为:

{name:’parent’, children:[

{name:’c1′},

{id:1, name:’c2′},

{id:2, persistenceStatus:’Deleted’}

]}

2.3.1.6. 查询
· 查询有资源

地点:资源列表地址。如:/users/。

动作:使用 GET 来进展呼吁。

· 询问指定id的资源

地点:资源地址+Id。如:/users/1。

动作:使用 GET 来进展呼吁。

· 此外查询

每一个特殊查询,都亟需提供相应的奇异查询地址。必须参数为URI Part
的款式被来,可摘参数则以询问字符串的款型让起。例如,使用以下格式:

/users/username/hqf/minAge/30/?optionalParam1=1

如若少单 API
使用了同之参数,则需在资源后搭一个查询的称,用以区分。如:

/users/find2/username/hqf/minAge/30/?optionalParam1=1

· OData 查询

规划指出:尽量不要提供OData查询。

如倘使提供OData查询API,必须考虑查询的权杖的界定,同时不要发表排序接口,否则性能可能会合大不同。

· 查询资源的合集

突发性,查询不是直指向有单一的资源,而是一道查询同一密密麻麻资源的合集,再次来到值的格式为跟纯粹资源格式不同。这时,需要吗是资源合集表明一个初的资源地址。例如,查询用户与角色的合集,可以下初的资源地址:/userRoles/。

2.3.2. 业务型操作

业务型操作表示可能过四个资源的逻辑操作。服务器端直接提供的劳务。

· 一般只是利用 POST 动作,偶尔用 GET 动作。不可知使用 PUT、DELETE
动作。**

· Action 不要使简便的、通用的称号。如不要动与资源操作争辩之
Get、Add、Update、Delete、Save 等称号。而使具体的逻辑名称,如
transfer、refreshTag 等……

· 推荐放到单独的服务地点(控制器)中。如:POST /{transaction}/{transfer}
{from:’a’,to:’b’,money:10}。

· 假若只是对有资源单独的操作,那么为可以在该资源地址下。如:POST
/users/refreshLogout提姆(Tim)e。;

3. API援文档规范

BAAS 平台碰到之 API 协理文档将使统一之格式编写,并因为 HTML
页面的花样发布。

拉文档使用以下地方:GET /api/v1.1/ 重返 1.1 版本 API 的相助文档首页。

3.1. 救助文档内容专业

朝外发表之每个API的协理表明,必须至少含有以下几宗:

· API 简介

· 请求

o 表明求的办法、地址。

o URI 参数:倘诺 URI
中某部分是动态的,请以大括号表明:api/values/{id}。

o URI 查询参数:如若 URI
地址有参数,描述各项参数与认证。每个参数是否可选。

o 请求标头:假如出特的请标头,需要特地逐一表达。

· 响应

o 表达响应的状态码、内容格式。

o 响应标头:假使起与众不同之呼吁标头,需要专门逐一表明。

o 响应正文:特殊字段、重点要表明含义。尽量表达响应正文的具有字段意义。

· 可选:授权、备注

· 示例请求和响应

参考示例:

· MS Azure
文档示例

3.2. 文档编写方法

API开发者需要吗夫揭穿的每一个
API建立一个XML文档用于详细描述上述的协理内容。该文档提议为与API对应之办法名起名,方便寻找。文档的内容由联合之沙盘确定。

框架组提供统一之转移工具来扭转对应的 API 网页。最后会拼以全 API
网站中。

3.3. 救助文档XML模板

拖欠模板盖附件形式被有。

 

文件下充斥地址:http://pan.baidu.com/s/1pJsswQJ

发表评论

电子邮件地址不会被公开。 必填项已用*标注

网站地图xml地图