查询接口

QRY接口标准

GET:http://api.xdua.com/resource?

查询语句不维护任何绝对查询参数

QRY参数

在地球号设计里QRY接口是个特别的接口,其接口是固定的，针对任何资源都是一样的。

字段名 位置 类型 说明 描述 可选
where query String 查询条件 查询条件,这是一个json字符串做了urlencode后的结果，如果不填，不说明，那么会被后台给默认没有查询条件。因为where语句是可选项，所以就没有where
fields query String 查询字段 查询字段 两种表达方式,@变量。
filter query String 过滤类别 查询条件 这是一个json字符串做了urlencode后的结果
offset query int 搜索开始的偏移条件 获取授权的开始个数，若不设置默认为0 可选
limit query int 搜索数量 获取授权的数量，若不设置默认为20 可选
page query int 搜索页号 如果page>0的话,就可以忽略offset的效果，和limit一起使用。使用page搜索 可选
sort query String 顺序 必须按照"字段:ASC/DESC"方式书写，如 name:DESC，默认的order是inc:DESC 可选
format query String 格式 格式,默认是"raw" 可选
schema query String 查询结构 描述where条件json结构的格式,默认是*,如果是*表示where条件随便写。 可选

[!note|label:offset分页和page分页两种机制?] 两种机制在后端都要生成它的对应参数，如果offset机制，要生成page.

[!note|label:排序字段为什么要用sort而不用order?] 因为只有mysql用order这个字眼，很多地方都用sort。

[!note|label:fields字段设计的技巧?] 我们在网关配置了有效的fields字段的技巧，网关会配置各个查询和详情接口的有效fields,这样保证少动函数计算代码。fields是个以半角逗号分隔开的字符串，其中有的是实际的字段名，有的是以@开头的标志名，所以一个有效的fields表达可以是name,avatar,brief,@all,ctime这样的混合表达。

目前查询有个致命的问题，就是where字段的组成，当想表达OR,AND,或者嵌套的复杂查询的时候,where语句虽然可以自由安排，因为它是json,

但是服务端却不方便检查查询字段的格式，大小，因为服务器端不知道where语句的参数组织格式。 这个时候我们需要一个字段来说明where字段是什么格式。schema？因为阿里云的请求参数格式字段确实是schema。

[!note|label:为什么要设计schema字段?] 目前查询有个致命的问题，就是where字段的组成，当想表达OR,AND,或者嵌套的复杂查询的时候,where语句虽然可以自由安排，因为它是json, 但是服务端却不方便检查查询字段的格式，大小，因为服务器端不知道where语句的参数组织格式。 这个时候我们需要一个字段来说明where字段是什么格式。schema？因为阿里云的请求参数格式字段确实是schema。

[!note|label:为什么要设计fields字段?] 对于有些关系数据库表，有些字段很长，但我们不是总需要所有字段，很多场合我们只需要字段的一部分来避免网络流量。这个时候我们就可以用fields字段来指定。 注意，这里面有个问题，所有字段对一个接口是完全开放的。客户端有权获取所有字段。那怎么根据权限来决定，哪些角色可以看到哪些字段，这个可以在网关设置，不同的Rule或者Role都可以在网关用常量来配置它的fields，也就是我们有设计空间。

[!note|style:flat|label:为什么where不用base64编码？|iconVisibility:hidden] Base64可以将二进制转码成可见字符方便进行http传输，但是base64转码时会生成“+”，“/”，“=”这些被URL进行转码的特殊字符，导致两方面数据不一致。客户端向服务器传递参数时，参数中的“+”全部变成了空格，原因是URL中默认的将“+”号转义了。所以要用urlencode

[!TIP|style:flat|label:查询返回|iconVisibility:hidden] 查询返回，查询资源的结果,因为历史原因，查询结果有的用的是"list"。这些都必须纠正过来。

[!note|style:flat|label:为什么查询返回里要有where字段？|iconVisibility:hidden] where字段必须是字典,返回where是为了让客户端更好的调试。

字段名 位置 类型 说明
where result String 查询条件
list result String 过滤类别
total result int 搜索开始
count result int 搜索数量
sort result int 排序方法
pages result int 总共有多少页
page result int 当前是第几页
format result String 当前格式,默认是"raw" 
{
    "where":{
        #查询结果        
    },
    "format":"raw",
    "list":[
        item1,
        item2,
        item3,
    ],
    "total":190,
    "count":20,
    "sort":"ctime:ASC",
    "pages":23,
    "page":3
}

使用电话号码搜索 : http://api.xdua.com/user?tel=1581041***2

使用户名进行搜索 : http://api.xdua.com/user?name=我的昵称

查询第8页,每页40条: http://api.xdua.com/user?page=8&limit=40

查询第300条后 20条: http://api.xdua.com/user?offset=300&limit=20

查询以用户名进行递增排序: http://api.xdua.com/user?order="name:ASC"

page查询优先于offset: http://api.xdua.com/user?page=10&offset=300&limit=20 结果相当于第10页,每页20

results matching ""

    No results matching ""