Tencent/APIJSON · error · IllegalArgumentException

字符 ${method} 不合法！预编译模式下 @column:"column0,column1:alias;funct

Error message

字符 ${method} 不合法！预编译模式下 @column:"column0,column1:alias;function0(arg0,arg1,...);function1(...):alias..." 中 function 必须符合小写英文单词的 SQL 函数名格式！且必须是后端允许调用的 SQL 函数!

What it means

When SQL_FUNCTION_MAP IS configured, a @having function must not only look like a name — it must be a key in that map. The map is the backend's whitelist of allowed SQL functions; anything else (even valid SQL like ifnull when not whitelisted) is rejected. Note the message text mistakenly references @column but the check is in gainHavingItem.

Source

Thrown at APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java:1792

		}

		int end = expression.lastIndexOf(")");
		if (start >= end) {
			throw new IllegalArgumentException("字符 " + expression + " 不合法！"
					+ "@having:value 中 value 里的 SQL函数必须为 function(arg0,arg1,...) 这种格式！");
		}

		String method = expression.substring(0, start);
		if (method.isEmpty() == false) {
			if (SQL_FUNCTION_MAP == null || SQL_FUNCTION_MAP.isEmpty()) {
				if (StringUtil.isName(method) == false) {
					throw new IllegalArgumentException("字符 " + method + " 不合法！"
							+ "预编译模式下 @having:\"column?value;function(arg0,arg1,...)?value...\""
							+ " 中 function 必须符合小写英文单词的 SQL 函数名格式！");
				}
			}
			else if (SQL_FUNCTION_MAP.containsKey(method) == false) {
				throw new IllegalArgumentException("字符 " + method + " 不合法！"
						+ "预编译模式下 @column:\"column0,column1:alias;function0(arg0,arg1,...);function1(...):alias...\""
						+ " 中 function 必须符合小写英文单词的 SQL 函数名格式！且必须是后端允许调用的 SQL 函数!");
			}
		}

		return method + parseSQLExpression(KEY_HAVING, expression.substring(start), containRaw, false, null);
	}

	@Override
	public String getSample() {
		return sample;
	}
	public AbstractSQLConfig<T, M, L> setSample(String... conditions) {
		return setSample(StringUtil.get(conditions));
	}
	@Override
	public AbstractSQLConfig<T, M, L> setSample(String sample) {
		this.sample = sample;

View on GitHub (pinned to 5284052872)

Solutions

Switch to a function that is whitelisted in your SQL_FUNCTION_MAP
Backend: add the needed function as a key in SQL_FUNCTION_MAP (and restart/reload)
If the expression cannot be reduced to a whitelisted function, configure it in RAW_MAP and reference via @raw

Example fix

// backend: allow the function
// SQL_FUNCTION_MAP.put("stddev", "stddev");
// request stays {"@having": "stddev(amount)>1"}

Defensive patterns

Strategy: validation

Validate before calling

const ALLOWED = new Set(['count','sum','max','min','avg']); // mirror of backend SQL_FUNCTION_MAP
const fn = hv.slice(0, hv.indexOf('('));
if (fn && !ALLOWED.has(fn)) throw new Error(`function ${fn} is not in the backend SQL_FUNCTION_MAP whitelist`);

Type guard

const isWhitelistedFunction = (fn, allowed) => allowed.has(fn);

Try / catch

try { await api.get(req); } catch (e) { if (e.message.includes('必须是后端允许调用的 SQL 函数')) fallbackToWhitelistedAggregation(req); else throw e; }

Prevention

Publish the SQL_FUNCTION_MAP contents as part of the API contract
Fail CI when a PR introduces a @having function not in the shared allowlist constant

When it happens

Trigger: "@having": "stddev(amount)>1" where stddev is not a key in the deployed SQL_FUNCTION_MAP; using a database-specific function the admin never enabled.

Common situations: Code works on a dev server with a broad SQL_FUNCTION_MAP and fails on production with a narrow one; upgrading APIJSON changes the default map; DB dialect differences (function exists in MySQL but not whitelisted).

Related errors

AI-assisted analysis of Tencent/APIJSON@5284052872 (2026-08-14). Data as JSON: /api/errors/8105a02e779d091c. Report an issue: GitHub.