Tencent/APIJSON · error · IllegalArgumentException

预编译模式下 @latest:value 中 ${item} 不合法! value 里面用 , 分割的每一项必须是 co

Error message

预编译模式下 @latest:value 中 ${item} 不合法! value 里面用 , 分割的每一项必须是 column 且其中 column 必须是 英语单词！并且不要有多余的空格！

What it means

Prepared-mode validation of @latest:value: each comma-separated item must be a single word identifier (StringUtil.isName). LATEST ON columns cannot be bound parameters, so anything that is not a clean name is refused.

Source

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

				}
			}
		}

		String latest = StringUtil.trim(getLatest());

		String[] keys = StringUtil.split(latest);
		if (keys == null || keys.length <= 0) {
			return StringUtil.isEmpty(joinLatest, true) ? "" : (hasPrefix ? " LATEST ON " : "") + joinLatest;
		}

		for (int i = 0; i < keys.length; i++) {
			String item = keys[i];
			String origin = item;

			if (isPrepared()) { //不能通过 ? 来代替，SELECT 'id','name' 返回的就是 id:"id", name:"name"，而不是数据库里的值！
				//这里既不对origin trim，也不对 ASC/DESC ignoreCase，希望前端严格传没有任何空格的字符串过来，减少传输数据量，节约服务器性能
				if (StringUtil.isName(origin) == false) {
					throw new IllegalArgumentException("预编译模式下 @latest:value 中 " + item + " 不合法! value 里面用 , 分割的"
							+ "每一项必须是 column 且其中 column 必须是 英语单词！并且不要有多余的空格！");
				}
			}

			keys[i] = gainKey(origin);
		}

		return (hasPrefix ? " LATEST ON " : "") + StringUtil.concat(StringUtil.get(keys), joinLatest, ", ");
	}

	@Override
	public String getPartition() {
		return partition;
	}
	public AbstractSQLConfig<T, M, L> setPartition(String... conditions) {
		return setPartition(StringUtil.get(conditions));
	}
	@Override

View on GitHub (pinned to 5284052872)

Solutions

Use bare column names: "@latest": "createdAt"
Strip spaces/symbols when generating the list programmatically
Backend: disable ambiguity by configuring RAW_MAP for any unavoidable expression

Example fix

// before
{"@latest": "log.createdAt"}
// after
{"@latest": "createdAt"}

Defensive patterns

Strategy: validation

Validate before calling

for (const item of String(obj['@latest'] ?? '').split(',')) {
  if (item && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(item)) throw new Error(`@latest item '${item}' must be a single word`);
}

Type guard

const isSingleIdentifier = s => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s);

Try / catch

try { await api.get(req); } catch (e) { if (e.message.includes('@latest')) req['@latest'] = req['@latest'].replace(/\s/g, ''); else throw e; }

Prevention

Never send qualified names (tbl.col) in @latest; set the table object instead
Lint clause-list fields for spaces

When it happens

Trigger: "@latest": "created at" , "@latest": "t.id" (dot), "@latest": "id;--" — an item failing isName.

Common situations: Using qualified table.column names; pasting SQL; whitespace introduced by building the string with array join.

Related errors

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