Flowable入门系列文章92 - 一般可流动的REST原则 03

1、请求参数

1.1、网址片段

在段包含特殊字符的情况下，作为url一部分的参数（例如deploymentId参数中的http://host/flowablerest/service/repository/deployments/{deploymentId}）需要正确转义（请参阅URL编码或百分比编码）。大多数框架都内置了这个功
能，但应该考虑到这一点。特别是对于可能包含正斜杠（例如部署资源）的段，这是必需的。

1.2、剩余的URL查询参数

在URL中作为查询字符串添加的参数（例如，所使用的名称参数http://host/flowable-rest/service/deployments?name=Deployment）可
以具有以下类型，并在相应的REST-API文档中提及：
表1. URL查询参数类型

类型	格式
串	纯文本参数。可以包含URL中允许的任何有效字符。如果是XXXLike参数，字符串应该包含通配符%（正确的url编码）。这允许指定类似搜索的意图。例如Tas%匹配从Tas开始的所有值。
整数	代表整数值的参数。只能包含数字非十进制值，介于-2.147.483.648和2.147.483.647之间。
长	代表长值的参数。只能包含-9.223.372.036.854.775.808和9.223.372.036.854.775.807之间的数字非十进制值。
布尔	表示布尔值的参数。可以是true或者false。除了这两个值以外的所有其他值都会引起405 - Bad request响应。
日期	代表日期值的参数。使用时间和日期组件（例如），使用ISO-8601日期格式（参见维基百科上的ISO-86012013-04-03T23:45Z）。

1.3、JSON 参数

表2. JSON参数类型

类型	格式
串	纯文本参数。如果是XXXLike参数，字符串应该包含通配符%。这允许指定类似搜索的意图。例如Tas%匹配从Tas开始的所有值。
整数	表示整数值的参数，使用JSON号码。只能包含数字非十进制值，介于-2.147.483.648和2.147.483.647之间。
长	表示长整型值的参数，使用JSON号码。只能包含-9.223.372.036.854.775.808和9.223.372.036.854.775.807之间的数字非十进制值。
日期	表示日期值的参数，使用JSON文本。使用时间和日期组件（例如），使用ISO-601日期格式（参见维基百科上的ISO-86012013-04-03T23:45Z）。

1.4、分页和排序

分页和订单参数可以作为查询字符串添加到URL中（例如，使用的名称参数http://host/flowable-rest/service/deployments?sort=name）。

参数	默认值	描述
分类	每个查询实现不同	每个查询实现的默认值和允许值不同的排序键的名称。
订购	ASC	排序顺序可以是asc或desc。
开始	0	允许分页结果的参数。默认情况下，结果将从0开始。
尺寸	10	允许分页结果的参数。默认情况下，大小将是10。

1.5、JSON查询变量格式

{
"name" : "variableName",
"value" : "variableValue",
"operation" : "equals",
"type" : "string"
}

表3.变量查询JSON参数

参数	需要	描述
名称	没有	要包含在查询中的变量的名称。如果equals在某些查询中使用，则可以为空，以查询具有给定值的任何变量名称的资源。
值	是	包含在查询中的变量的值应该包含给定类型的正确格式。
操作者	是	在查询中使用的运算符可以具有以下值：equals, notEquals, equalsIgnoreCase,notEqualsIgnoreCase, lessThan,greaterThan, lessThanOrEquals,greaterThanOrEquals和like。
类型	没有	要使用的变量的类型。省略时，类型将从value参数中扣除。任何JSON文本值将被视为类型string，类型的JSON布尔值，类型的booleanJSON数字long或integer取决于数字的大小。如有疑问，建议使用明确的类型。下面列出了开箱即用的支持类型。

表4.默认查询JSON类型

类型名称	描述
串	值是通过线程转换为java.lang.String。
短	值是通过线程转换为java.lang.Integer。
整数	值是通过线程转换为java.lang.Integer。
长	值是通过线程转换为java.lang.Long。
双	值是通过线程转换为java.lang.Double。
布尔	值是通过线程转换为java.lang.Boolean。
日期	价值被视为并转换为一个java.util.Date。JSON字符串将使用ISO-8601日期格式进行转换。

1.6、变量表示

当使用变量（执行/进程和任务）时，REST-api使用一些常见的原则和JSON格式来读写。变量的JSON表示如下所示：

{
"name" : "variableName",
"value" : "variableValue",
"valueUrl" : "http://...",
"scope" : "local",
"type" : "string"
}

表5.变量JSON属性

参数	需要	描述
名称	是	变量的名称。
值	没有	变量的值。当写入一个变量并被value省略时，null将被用作值。
valueUrl	没有	当读取类型的变量binary或serializable，该属性将指向其中原始二进制数据可以从获取的URL。
范围	没有	变量的范围。如果local该变量在请求的资源上明确定义。何时global，该变量是在其所请求的资源的父级（或父级树中的任何父级）上定义的。当写一个变量，并且范围被省略时，global被假定。
类型	没有	变量的类型。有关类型的更多信息，请参阅下表。当写一个变量，该值被省略，则类型从原始JSON属性请求类型中扣除并仅限于任一string，double，integer和boolean。建议总是包括一个类型，以确保没有错误的类型可以做的假设。

表6.变量类型

类型名称	描述
串	价值是作为一个线程java.lang.String。编写变量时使用原始的JSON文本值。
整数	价值是作为一个线程java.lang.Integer。在编写时，JSON数值被用作转换的基础，回退到JSON文本。
短	价值是作为一个线程java.lang.Short。在编写时，JSON数值被用作转换的基础，回退到JSON文本。
长	价值是作为一个线程java.lang.Long。在编写时，JSON数值被用作转换的基础，回退到JSON文本。
双	价值是作为一个线程java.lang.Double。在编写时，JSON数值被用作转换的基础，回退到JSON文本。
布尔	价值是作为一个线程java.lang.Boolean。编写时，使用JSON布尔值进行转换。
日期	价值被视为一个java.util.Date。写入时，JSON文本将使用ISO-8601日期格式进行转换。
二进制	二进制变量，视为一个字节数组。该value属性为空，valueUrl包含一个指向原始二进制流的URL。
序列化	Serializable Java对象的序列化表示。与binary类型一样，该value属性为空，valueUrl包含一个指向原始二进制流的URL。所有可序列化的变量（不是上述任何类型的变量）将作为这种类型的变量公开。

可以使用自定义JSON表示（简单值或复杂/嵌套的JSON对象）支持其他变量类型。通过扩展该initializeVariableConverters()方法org.flowable.rest.service.api.RestResponseFactory，可以添加其他org.flowable.rest.service.api.engine.variable.RestVariableConverter类来支持将POJO转换为适合通过REST传输的格式，并将REST值转换回POJO。杰克逊完成了对JSON的实际转换。

上面文章来自盘古BPM研究院：http://vue.pangubpm.com/
文章翻译提交：https://github.com/qiudaoke/flowable-userguide
了解更多文章可以关注微信公众号：