查询解析器 QueryParser
校对日期:2026-11-16。适用于社区版及全部商业版。
查询解析器把一组“查询键 = 值”翻译成 SQL 的表关联、查询条件和排序,列表和分页查询因此不用为每个筛选项手写 SQL。 查询键形如 Contains_title、EQ_user-username、GE_created_,可以由后台界面、公开接口的地址参数、模板标签传入, 也可以在 Java 代码里直接写。相关的类在 ujcms-common 模块的 com. 包下。
一、一次列表查询的经过
以示例表为例(com.):
public List<Example> selectList(ExampleArgs args) {
QueryInfo queryInfo = QueryParser.parse(args.getQueryMap(), GeneratedExample.TABLE_NAME, "id_desc");
return mapper.selectAll(queryInfo);
}- 查询键和值装在一个
Map<String, Object>里,由查询参数类(ExampleArgs,继承BaseQueryArgs)持有。 它有两个来源:请求带来的(见“三个入口”一节),和代码里加的,例如ExampleArgs.里的name() queryMap.。put("Contains_ name", name) QueryParser.解析成parse(查询键, 主表名, 默认排序) QueryInfo。主表名不带ujcms_前缀,用基类的TABLE_NAME; 请求里没有排序时使用第三个参数。- Mapper 的
selectAll把QueryInfo交给公用 SQL 片段Select_All拼成语句,见实体类与 Mapper的“Mapper XML”一节。
主表在 SQL 中的别名固定为 t。解析器给主表和关联的表都加上 ujcms_ 前缀,所以自己建的表也要用这个前缀 (或者调用带第四个参数 tablePrefix 的 parse 方法,这时关联的表也使用该前缀)。
二、查询键的写法
操作符_字段 Contains_title
操作符_字段_类型 EQ_status_Short
操作符_分组_字段_类型 Like_1_title- 各部分用下划线分隔,所以字段写属性名(驼峰),不带下划线:字段
publish_date_写publishDate。 - 操作符和类型区分大小写,必须按下面两节的写法。
- 类型说明值按什么类型传给数据库,不写就是
String。数字、布尔、日期字段一般都要写。 - 查询键只能包含字母、数字、下划线、
-、@和$。 - 值为空(
null或空白字符串)的查询键被忽略,IsNull、IsNotNull除外。筛选表单里没填的项因此不会变成条件。
三、操作符
| 操作符 | SQL | 说明 |
|---|---|---|
EQ | = | |
NE | <> | |
GT、GE | >、>= | |
LT、LE | <、<= | |
Like | LIKE | 值原样使用,通配符 % 自己写 |
Contains | LIKE '%值%' | |
StartsWith | LIKE '值%' | |
EndsWith | LIKE '%值' | |
In、NotIn | IN (…)、NOT IN (…) | 值是逗号分隔的字符串或集合,按类型逐个转换:In_status_Short = 0,1 |
IsNull、IsNotNull | IS NULL、IS NOT NULL | 不看值 |
ArrayEQ、ArrayIn | 按数据库而定 | 只用于 JSON 字段中的数组,见“OR 分组与 JSON 字段”一节 |
四、类型
| 类型 | 值 |
|---|---|
String | 默认 |
Short、Int(或 Integer)、Long、Double、BigInteger、BigDecimal | 数字。主键和外键是 Long |
Boolean | true / false。数据库里的布尔字段是 char(1),解析器把它转成 '1' / '0' |
DateTime | 日期时间,按给定的时刻比较 |
Date | 日期。与 DateTime 的区别在 LT、LE:解析器把值加一天,LE_created_Date = 2026-01-31 实际按“不晚于 2 月 1 日 0 点”比较,1 月 31 日当天的数据也在内 |
日期的值可以写成 2026-01-31、2026-01-31 08: 或带时区的 ISO 格式 2026-01-31T08:;没有时区的按服务器时区理解。
五、关联其它表
字段前面可以加“关联路径”,用 - 连接,解析器据此生成 JOIN。关联靠命名约定推断:表名 ujcms_user_ext 写成 userExt,外键字段是“表名 + _id_”,主键都是 id_。 以主表为文章表(article)或用户表(user)为例:
| 关系 | 写法 | 生成的关联 |
|---|---|---|
| 多对一,外键名与表名一致 | Like_(主表 article) | JOIN ujcms_ |
多对一,外键名与表名不一致:外键@表 | Like_(主表 article) | JOIN ujcms_ |
一对一,两表主键相同:@表 | Contains_(主表 article) | JOIN ujcms_ |
一对多,子表的外键是“主表名 + _id_”:表名首字母大写 | In_ArticleTag-tagId_(主表 article) | JOIN ujcms_ |
一对多,指明子表的外键:外键@表,表名首字母大写 | EQ_descendant@ChannelTree-ancestorId_(主表 channel) | JOIN ujcms_ |
用主表的外键关联另一张表的非主键字段:主表外键@表@对方外键 | In_channel@ChannelTree@descendant-ancestorId_(主表 article) | JOIN ujcms_ |
要点:
- 表名首字母小写是“主表指向对方”(多对一),大写是“对方指向主表”(一对多),
@开头是主键相同的一对一。 - 关联可以连续写,后一段以前一段的表为起点:
Contains_先关联文章标签关系表,再关联标签表;ArticleTag-tag-name GE_modifiedUser@user-@userExt-created_先关联修改人,再关联他的用户扩展表,按注册时间筛选。DateTime - 同一个别名只关联一次,多个查询键和排序可以共用。
- 关联都是内连接(
JOIN):对方没有记录的行不会出现在结果里。 - 一对多的关联会让主表的行重复,需要时加上
Distinct(见“排序与去重”一节)。
六、OR 分组与 JSON 字段
6.1 OR 分组
没有分组的查询键之间是 AND。要表达“或”,在操作符后面加分组号:
Contains_1_username = 张
Contains_1_realName = 张同一组内的条件用 OR 连接,整组加括号后再与其它条件 AND:AND (t.。
组内还可以再分小组,写成 组-小组。同一小组内是 AND,小组之间是 OR:
EQ_1-1_status_Short = 0
EQ_1-1_siteId_Long = 1
EQ_1-2_status_Short = 1得到 AND ((t.。
组号的规定:请求传入的组号必须是从 1 开始的正整数,小组号必须是数字,否则返回 400。以 0 开头的组名留给服务端代码使用, 例如 BlockArgs 里“本站的或全局的”:
queryMap.put("EQ_0scope_siteId_Long", siteId);
queryMap.put("EQ_0scope_scope_Short", String.valueOf(EntityConstants.SCOPE_GLOBAL));这样请求无法把自己的条件并入服务端的 OR 组。自己在查询参数类里写 OR 条件时,也用 0 开头的组名。
6.2 JSON 字段
自定义字段保存在 JSON 字段里(如文章扩展表的 mains_json_)。在字段后面用 $ 接 JSON 里的键名即可查询:
EQ_@articleExt-mainsJson$price_Int = 100
Contains_mainsJson$name = 张键名只能包含字母、数字和下划线。值是数组的自定义字段(多选、复选)用 ArrayEQ(数组中包含该值)和 ArrayIn(数组中包含其中任意一个值):
ArrayIn_@articleExt-mainsJson$color = red,blue不同数据库的 JSON 语法由公用片段处理,见 SeqMapper.xml 中的 selectWhereJsonCondition。
七、排序与去重
排序的查询键是 OrderBy,值是逗号分隔的“字段路径 + _asc / _desc”:
OrderBy = publishDate_desc,id_desc
OrderBy = @articleExt-views_desc
OrderBy = mainsJson$price_Int_desc字段路径的写法与查询条件相同,可以带关联和 JSON 键名(JSON 字段可以在方向前写类型)。方向必须小写,不写就是升序。 公开接口和模板标签的 orderBy 参数用的是同一套写法,常用的排序字段见模板标签与 API 的通用参数的“排序:orderBy”一节。 请求里没有 OrderBy 时,用 QueryParser. 的第三个参数作为默认排序。
去重的查询键是 Distinct,值为 true(或留空)时生成 SELECT DISTINCT,值为 false 时不去重。
八、三个入口
查询键从哪里来,决定了它受到什么限制。请求传入的查询键都带前缀 Q_(Q_Contains_),进入查询参数类之前由下面的方法取出并去掉前缀。
8.1 后台接口
ExampleArgs args = ExampleArgs.of(QueryUtils.getQueryMap(request.getQueryString()));后台界面的筛选项直接用查询键作为名称,如 Q_Contains_、Q_In_status_Int,排序是 Q_OrderBy。 操作员可以自己拼地址参数,所以 getQueryMap 有两层限制,违反时返回 400(Query not allowed: …):
- 默认只允许主表自己的字段(含 JSON 字段)作条件和排序,任何关联都拒绝。列表确实需要按关联表筛选或排序时, 用
getQueryMap(queryString, joins)列出许可的关联路径,如评论列表的Set.、 用户列表的of("user-username") Set.。of("@userExt-*", "org-name", "group-name") @userExt-*表示该关联下的任何字段,只该用于一对一的扩展表。 - 无论是否列入许可,都不能查询或排序凭证类的字段(字段名包含
password、secret,或者是salt、token、aesKey, 或者以tokenHash结尾),也不能关联全局配置表config。
8.2 公开接口
Map<String, String> params = QueryUtils.getParams(request.getQueryString());
ExampleArgs args = ExampleArgs.of(QueryUtils.getPublicQueryMap(params));公开接口的参数来自匿名访客,getPublicQueryMap 对 Q_ 条件、Q_OrderBy 和 orderBy 参数都做检查,违反时返回 400:
- 不能关联用户、组织、角色、用户组、全局配置、登录日志、操作日志、短信这些表(表名以
user、org、role、group、config、loginLog、operationLog、shortMessage开头,不区分大小写); - 不能使用字段名包含
password、salt、secret、token的字段,以及ip、mobile、phone、email、address、contact、realName; - 不能用文章扩展表的正文类大字段(
text、markdown、clobsJson)作条件或排序。
给自己的表写公开接口时,一律用 getPublicQueryMap,不要用后台的 getQueryMap。完整的例子见 com.。
8.3 模板标签
标签的 Q_ 开头的参数同样会进入查询(Directives.):
[@ArticleList channel='news' Q_LT_publishDate_DateTime=Params.lastArticleDate! limit='10'; list]
…
[/@ArticleList]FreeMarker 的参数名里不能写 @ 和 -,分别用 $$ 和 __ 代替:Q_Contains_ 相当于 Contains_。 查询键是动态拼出来的时候,可以把它们放进一个哈希,用名为 Q_ 的参数整体传入,键名按原样写;默认主题 templates/ 按自定义字段筛选文章就是这样做的(Q_=customsQueryMap)。
模板由主题作者编写,标签的查询键不做 8.2 的检查。不要把访客的输入直接拼进查询键的名称。
九、常见问题
接口返回 400,提示 Query not allowed: …。 查询键触犯了入口的限制:后台接口关联了没有列入许可的表,公开接口用了敏感的表或字段,或者组号不符合规定。见“OR 分组与 JSON 字段”一节和“三个入口”一节。
接口返回 500,异常是 QueryException。 操作符或类型写错了,例如 Contain_name、eq_name、EQ_price_int(都区分大小写),或者查询键里有不允许的字符。
按日期筛选,结束日期当天的数据没有出来。 结束日期用了 LE_…_DateTime,值只有日期时按当天 0 点比较。改用 Date 类型,或者传入完整的时刻。
加了一对多的关联后,同一条数据出现多次。 加上 Distinct,后台界面的参数是 Q_Distinct=true。
排序写了 _DESC 没有生效。 方向必须小写。大写的后缀不被当作方向,结果按升序排。