hs-web/hsweb-framework · error · IllegalArgumentException

查询条件错误,正确格式: $dimension $[not]

Error message

查询条件错误,正确格式:${alias}$dimension${type}$[not]

What it means

IllegalArgumentException thrown by DimensionTerm.createFragments when a dynamic-query term targeting an authorization dimension has no options. The $dimension term requires its options to carry the dimension type (and optionally 'not'), because it must build SQL fragments like alias$type$[not]; without options the term is meaningless and the query cannot be compiled. This is a caller misuse of the query DSL, not a server fault.

Solutions

  1. Include the dimension type in the term key/options, e.g. use the column alias as alias$dimension$type (type = the dimension type id such as user/role).
  2. If negation is needed, add the 'not' option: alias$dimension$type$[not].
  3. For programmatic use, set the options list on the term before createFragments is invoked.
  4. Check the incoming query-string parameter names for typos that swallow the '$dimension$type' segment.

Example fix

// before
createQuery().is("dimension$dimension", "role-id-1")
// after
createQuery().is("dimension$dimension$role", "role-id-1") // type segment present in options
Defensive patterns

Strategy: validation

Validate before calling

String key = "dimension$dimension$" + dimensionType;
if (dimensionType == null || dimensionType.isBlank()) {
    throw new IllegalArgumentException("dimension term requires a type option, e.g. dimension$dimension$user");
}

Try / catch

try {
    return service.createQuery().is(key, value).fetch();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("$dimension")) {
        throw new BadRequestException("查询条件需形如 column$dimension$type$[not]");
    }
    throw e;
}

Prevention

When it happens

Trigger: Building an authorization query with a term keyed like 'dimension' (e.g. createQuery().is("dimension$dimension", ...) or passing request parameters such as dimension$type=...) but omitting the type segment in the term options — i.e. term.getOptions() returns null or an empty list.

Common situations: Front-end query strings missing the '$dimension$type' suffix on the column name; copying a query example and dropping the [not] or type option; constructing terms programmatically with DimensionTerm but forgetting to set options.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of hs-web/hsweb-framework@b2cfc85a57 (2026-09-13). Data as JSON: /api/errors/4063dd1c6186c40d. Report an issue: GitHub.

Appendix: source

Thrown at hsweb-system/hsweb-system-authorization/hsweb-system-authorization-default/src/main/java/org/hswebframework/web/system/authorization/defaults/service/terms/DimensionTerm.java:73

        if (not) {
            joiner.add("not");
        }
        if (any) {
            joiner.add("any");
        }
        return joiner.toString();
    }

    @Override
    public SqlFragments createFragments(String columnFullName, RDBColumnMetadata column, Term term) {

        List<Object> values = convertList(column, term);
        if (values.isEmpty()) {
            return EmptySqlFragments.INSTANCE;
        }
        List<String> options = term.getOptions();
        if (CollectionUtils.isEmpty(options)) {
            throw new IllegalArgumentException("查询条件错误,正确格式:" + column.getAlias() + "$dimension${type}$[not]");
        }
        BatchSqlFragments fragments = new BatchSqlFragments(6, 2);

        if (options.contains("not")) {
            fragments.add(SqlFragments.NOT);
        }
        fragments
            .addSql("exists(select 1 from",
                    getTableName("s_dimension_user", column),
                    "d where d.dimension_type_id = ? and d.dimension_id =", columnFullName)
            .addParameter(options.get(0));

        if (!options.contains("any")) {
            fragments
                .add(USER_ID_IN)
                .add(SqlUtils.createQuestionMarks(values.size()))
                .add(SqlFragments.RIGHT_BRACKET)
                .addParameter(values);

View on GitHub (pinned to b2cfc85a57)