Tencent/APIJSON · error · IllegalArgumentException

字符 {ck} 不合法！预编译模式下 @column:"`column0`,`column1`:alias;functi

Error message

字符 {ck} 不合法！预编译模式下 @column:"`column0`,`column1`:alias;function0(arg0,arg1,...);function1(...):alias..." 中所有字符串 column 都必须必须为1个单词 ！

What it means

In parseArgsSplitWithComma, an argument wrapped in backticks is unquoted and must be a single identifier that additionally must not start with '_' (underscore-prefixed columns are reserved for APIJSON's own keys like _password). Failing StringUtil.isName or starting with '_' throws this IllegalArgumentException.

Source

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

		// 以"," 分割参数
		String quote = getQuote();
		boolean isKeyPrefix = isKeyPrefix();
		String tableAlias = quote + gainSQLAlias() + quote;
		String[] ckeys = StringUtil.split(param); // 以","分割参数
		if (ckeys != null && ckeys.length > 0) {

			for (int i = 0; i < ckeys.length; i++) {
				String ck = ckeys[i];

				String origin;
				String alias;

				// 如果参数包含 "'" ,解析字符串
				if (ck.startsWith("`") && ck.endsWith("`")) {
					origin = ck.substring(1, ck.length() - 1);
					//sql 注入判断 判断
					if (origin.startsWith("_") || StringUtil.isName(origin) == false) {
						throw new IllegalArgumentException("字符 " + ck + " 不合法！"
								+ "预编译模式下 @column:\"`column0`,`column1`:alias;function0(arg0,arg1,...);function1(...):alias...\""
								+ " 中所有字符串 column 都必须必须为1个单词 ！");
					}

					origin = gainKey(origin);
				}
				else if (ck.startsWith("'") && ck.endsWith("'")) {
					origin = ck.substring(1, ck.length() - 1);
					if (origin.contains("'")) {
						throw new IllegalArgumentException("字符串 " + ck + " 不合法！"
								+ "预编译模式下 @column:\"column0,column1:alias;function0(arg0,arg1,...);function1(...):alias...\""
								+ " 中字符串参数不合法，必须以 ' 开头, ' 结尾,字符串中不能包含 ' ");
					}

					// 1.字符串不是字段也没有别名,所以不解析别名 2. 是字符串，进行预编译，使用getValue() ,对字符串进行截取
					origin = gainValue(origin).toString();
				}
				else {

View on GitHub (pinned to 5284052872)

Solutions

Only pass plain single-word columns in backticks, or skip backticks entirely for simple names.
For columns with special names, register an alias/mapping in the backend schema config or RAW_MAP.
Do not access underscore-prefixed reserved columns; rename the physical column if you control the schema.
Rewrite the expression to reference a view or @raw entry.

Example fix

// before
{"User":{"@column":"max(`_password`)"}}
// after (assuming column renamed or mapped server-side)
{"User":{"@column":"max(password)"}}

Defensive patterns

Strategy: validation

Validate before calling

const NAME=/^[A-Za-z][A-Za-z0-9_]*$/;
for(const arg of args){ if(arg.startsWith('`')&&arg.endsWith('`')){const inner=arg.slice(1,-1); if(inner.startsWith('_')||!NAME.test(inner))throw new Error('backtick arg must be one word, not _-prefixed'); } }

Type guard

function isBacktickArg(a) { if (!a.startsWith('`') || !a.endsWith('`')) return true; const i = a.slice(1, -1); return !i.startsWith('_') && /^[A-Za-z][A-Za-z0-9_]*$/.test(i); }

Try / catch

catch IllegalArgumentException; map offending backtick arg to a backend raw alias and retry

Prevention

Only single-word columns in backticks
Never reference underscore-prefixed reserved columns
Rename odd physical columns or expose them via views

When it happens

Trigger: "@column":"concat(`user name`,'x')" (space inside backticks), "@column":"max(`_password`)" (leading underscore), "@column":"`user.id`" (dot). All are rejected in prepared mode.

Common situations: Tables with columns whose names contain spaces or hyphens; accessing APIJSON reserved underscore columns; assuming backticks allow arbitrary SQL identifiers.

Related errors

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