Skip to content

Commit e03fa6a

Browse files
biggatesbiggates
committed
docs: 更新一些文档
1 parent 4d60416 commit e03fa6a

File tree

2 files changed

+95
-49
lines changed

2 files changed

+95
-49
lines changed

‎doc/Query.md‎

Lines changed: 45 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
# Why #
1+
# Why
22

33
I use DataTables in some projects and wrote SpringMVC server side for it. Later the frontend is rewritten and DataTables is no longer used. Now is the time to refine the protocol for general data-grid query.
44

55
* You can not assign a range via `columns[i][search][value]`, as in SQL: `BETWEEN`.
66
* You can only do regular search OR regex search via `columns[i][search][regex]`, but not `=`, `LIKE`.
77

8-
## Query ##
8+
## Query
99

1010
HTTP POST as `@RequestBody` is recommended:
1111

@@ -33,47 +33,62 @@ HTTP POST as `@RequestBody` is recommended:
3333
"_regex": "",
3434
"_like": "",
3535
"_exists": true,
36-
"_isNull": true,
37-
"_isEmpty": true,
38-
"_isvlid": true
36+
"_null": true,
37+
"_empty": true,
38+
"_isvoid": true
3939
}
4040
}
4141
}
4242
```
4343

44-
## Examples ##
44+
## Response format
4545

46-
### Basic Query ###
46+
```json
47+
{
48+
"draw": 1,
49+
"total": 0,
50+
"filtered": 0,
51+
"error": "",
52+
"data": []
53+
}
54+
```
55+
56+
## Examples
57+
58+
### Basic Query
4759

4860
None of the `draw`, `offset`, `limit`, `order_by`, `where` are required, so the basic query is:
4961

5062
```http
51-
POST /search
63+
POST /search HTTP/1.1
64+
Content-Type: application/json
5265
5366
{}
5467
```
5568

5669
e.g. NO parameters are needed.
5770

58-
### Pagination ###
71+
### Pagination
5972

6073
Paging is controlled by `offset` and `limit`, which keeps the same as `SKIP` and `LIMIT` in SQL.
6174

6275
```http
63-
POST /search
76+
POST /search HTTP/1.1
77+
Content-Type: application/json
6478
6579
{
6680
"offset": 30,
6781
"limit": 10
6882
}
6983
```
7084

71-
### Ordering ###
85+
### Ordering
7286

7387
Ordering by one column:
7488

7589
```http
76-
POST /search
90+
POST /search HTTP/1.1
91+
Content-Type: application/json
7792
7893
{
7994
"order_by": [{
@@ -86,7 +101,8 @@ POST /search
86101
Ordering by more columns:
87102

88103
```http
89-
POST /search
104+
POST /search HTTP/1.1
105+
Content-Type: application/json
90106
91107
{
92108
"order_by": [{
@@ -97,12 +113,13 @@ POST /search
97113
}
98114
```
99115

100-
### Filtering ###
116+
### Filtering
101117

102118
* Search by equality
103119

104120
```http
105-
POST /search
121+
POST /search HTTP/1.1
122+
Content-Type: application/json
106123
107124
{
108125
"where": {
@@ -116,7 +133,8 @@ POST /search
116133
* Like (`LIKE %value%`)
117134

118135
```http
119-
POST /search
136+
POST /search HTTP/1.1
137+
Content-Type: application/json
120138
121139
{
122140
"where": {
@@ -130,7 +148,8 @@ POST /search
130148
* By Numerical Range
131149

132150
```http
133-
POST /search
151+
POST /search HTTP/1.1
152+
Content-Type: application/json
134153
135154
{
136155
"where": {
@@ -146,7 +165,8 @@ POST /search
146165
* Date Range & Time Range
147166

148167
```http
149-
POST /search
168+
POST /search HTTP/1.1
169+
Content-Type: application/json
150170
151171
{
152172
"where": {
@@ -162,7 +182,8 @@ POST /search
162182
* In
163183

164184
```http
165-
POST /search
185+
POST /search HTTP/1.1
186+
Content-Type: application/json
166187
167188
{
168189
"where": {
@@ -173,12 +194,13 @@ POST /search
173194
}
174195
```
175196

176-
## Multiple Filters ##
197+
## Multiple Filters
177198

178199
Multiple filters are joined by `AND` logic.
179200

180201
```http
181-
POST /search
202+
POST /search HTTP/1.1
203+
Content-Type: application/json
182204
183205
{
184206
"where": {
@@ -197,6 +219,6 @@ POST /search
197219
198220
```
199221

200-
## References ##
222+
## References
201223

202-
* [DataTables: Server-side processing](https://datatables.net/manual/server-side)
224+
* [DataTables: Server-side processing](https://datatables.net/manual/server-side#Sent-parameters)

‎doc/Query.zh-CN.md‎

Lines changed: 50 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
# 关于查询 #
1+
# 关于查询
22

33
在实际操作中，在 DataTables 的通信协议的基础上，遇到了一些不足，主要有以下方面：
44

55
* 通过 `columns[i][search][value]` 实现的按列搜索功能，不能指定范围。比如 “指定日期范围” 或者 “大于 xx 的值” 这种场景，无法在统一的一个通信协议里传递
66
* 通过 `columns[i][search][regex]` 只能指定 `普通搜索` 和 `按正则表达式搜索` 两种场景，
77

8-
## 查询方式 ##
8+
## 查询方式
99

1010
建议在 POST 接口上通过 `@RequestBody` 方式传入较为完整的查询内容。
1111

@@ -33,47 +33,62 @@
3333
"_regex": "",
3434
"_like": "",
3535
"_exists": true,
36-
"_isNull": true,
37-
"_isEmpty": true,
36+
"_null": true,
37+
"_empty": true,
3838
"_isvoid": true
3939
}
4040
}
4141
}
4242
```
4343

44-
## 示例 ##
44+
## 响应
4545

46-
### 最简单的请求 ###
46+
```json
47+
{
48+
"draw": 1,
49+
"total": 0,
50+
"filtered": 0,
51+
"error": "",
52+
"data": []
53+
}
54+
```
55+
56+
## 示例
4757

48-
因为 `draw`, `offset`, `limit`, `order_by`, `where` 全都改为可选的，因此最简单的请求就变成了
58+
### 最简单的请求
59+
60+
因为 `draw`, `offset`, `limit`, `order_by`, `where` 全都改为可选的，因此最简单的请求就变成了：
4961

5062
```http
51-
POST /search
63+
POST /search HTTP/1.1
64+
Content-Type: application/json
5265
5366
{}
5467
```
5568

56-
即：不需要任何参数。
69+
即：不需要传任何实际的参数。
5770

58-
### 分页 ###
71+
### 分页
5972

60-
单纯分页只需要传入 `offset` 和 `limit` 。（当然如果 `limit` 和后端一致的话也可以不传了）
73+
单纯分页只需要传入 `offset` 和 `limit` （当然如果 `limit` 和后端的默认值一致的话也可以不传）。
6174

6275
```http
63-
POST /search
76+
POST /search HTTP/1.1
77+
Content-Type: application/json
6478
6579
{
6680
"offset": 30,
6781
"limit": 10
6882
}
6983
```
7084

71-
### 按某一列排序 ###
85+
### 按某一列排序
7286

7387
最简单的排序：
7488

7589
```http
76-
POST /search
90+
POST /search HTTP/1.1
91+
Content-Type: application/json
7792
7893
{
7994
"order_by": [{
@@ -85,7 +100,8 @@ POST /search
85100
稍微复杂一些的排序（请注意排序的顺序是有意义的，因此使用数组形式）：
86101

87102
```http
88-
POST /search
103+
POST /search HTTP/1.1
104+
Content-Type: application/json
89105
90106
{
91107
"order_by": [{
@@ -96,12 +112,13 @@ POST /search
96112
}
97113
```
98114

99-
### 按某一列筛选 ###
115+
### 按某一列筛选
100116

101117
* 精确查询
102118

103119
```http
104-
POST /search
120+
POST /search HTTP/1.1
121+
Content-Type: application/json
105122
106123
{
107124
"where": {
@@ -114,8 +131,11 @@ POST /search
114131

115132
* 模糊查询
116133

134+
在 MongoDB 的实现中，'_like' 会使用 `$regex`, 并且按 SQL 的写法，'%' 会被替换成 '.+'。
135+
117136
```http
118-
POST /search
137+
POST /search HTTP/1.1
138+
Content-Type: application/json
119139
120140
{
121141
"where": {
@@ -129,7 +149,8 @@ POST /search
129149
* 按数值范围
130150

131151
```http
132-
POST /search
152+
POST /search HTTP/1.1
153+
Content-Type: application/json
133154
134155
{
135156
"where": {
@@ -145,7 +166,8 @@ POST /search
145166
* 按时间范围
146167

147168
```http
148-
POST /search
169+
POST /search HTTP/1.1
170+
Content-Type: application/json
149171
150172
{
151173
"where": {
@@ -159,10 +181,11 @@ POST /search
159181
160182
```
161183

162-
* 按枚举 (及 `$in` 操作)
184+
* 按枚举 (及 `_in` 操作)
163185

164186
```http
165-
POST /search
187+
POST /search HTTP/1.1
188+
Content-Type: application/json
166189
167190
{
168191
"where": {
@@ -173,12 +196,13 @@ POST /search
173196
}
174197
```
175198

176-
## 复合查询 ##
199+
## 复合查询
177200

178201
默认多个查询的参数之间是 `AND` 关系。
179202

180203
```http
181-
POST /search
204+
POST /search HTTP/1.1
205+
Content-Type: application/json
182206
183207
{
184208
"where": {
@@ -197,6 +221,6 @@ POST /search
197221
198222
```
199223

200-
## 参考 ##
224+
## 参考
201225

202-
* [DataTables: Server-side processing](https://datatables.net/manual/server-side) 和相应的 [中文版](http://datatables.club/manual/server-side.html)
226+
* [DataTables: Server-side processing](https://datatables.net/manual/server-side#Sent-parameters) 和相应的 [中文版](http://datatables.club/manual/server-side.html)

0 commit comments

Comments
 (0)