{"record":{"id":"4367d59da558c382","repo":"Tencent/APIJSON","slug":"key-tablekey","errorCode":null,"errorMessage":"{}/{}:{} 不合法！数组 []:{} 中第一个 key:{} 必须是主表 TableKey:{} ！不能为 arrayKey[]:{} ！","messagePattern":"(.+?)/(.+?):(.+?) 不合法！数组 \\[\\]:(.+?) 中第一个 key:(.+?) 必须是主表 TableKey:(.+?) ！不能为 arrayKey\\[\\]:(.+?) ！","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"APIJSONORM/src/main/java/apijson/orm/AbstractObjectParser.java","lineNumber":604,"sourceCode":"\t/**\n\t * @param index\n\t * @param key\n\t * @param value\n\t * @param cache\n\t * @return\n\t * @throws Exception\n\t */\n\t@Override\n\tpublic Object onChildParse(int index, String key, M value, Object cache) throws Exception {\n\t\tboolean isFirst = index <= 0;\n\t\tboolean isMain = isFirst && type == TYPE_ITEM;\n\n\t\tObject child;\n\t\tboolean isEmpty;\n\n\t\tif (JSONMap.isArrayKey(key)) { // APIJSON Array\n\t\t\tif (isMain) {\n\t\t\t\tthrow new IllegalArgumentException(parentPath + \"/\" + key + \":{} 不合法！\"\n\t\t\t\t\t\t+ \"数组 []:{} 中第一个 key:{} 必须是主表 TableKey:{} ！不能为 arrayKey[]:{} ！\");\n\t\t\t}\n\n\t\t\tif (arrayConfig == null || arrayConfig.getPosition() == 0) {\n\t\t\t\tarrayCount ++;\n\t\t\t\tint maxArrayCount = parser.getMaxArrayCount();\n\t\t\t\tif (arrayCount > maxArrayCount) {\n\t\t\t\t\tthrow new IllegalArgumentException(path + \" 内截至 \" + key + \":{} 时数组对象 key[]:{} \"\n                            + \"的数量达到 \" + arrayCount + \" 已超限，必须在 0-\" + maxArrayCount + \" 内 !\");\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tString query = getString(value, KEY_QUERY);\n\t\t\tchild = parser.onArrayParse(value, path, key, isSubquery, cache instanceof List<?> ? (L) cache : null);\n\t\t\tisEmpty = child == null || ((List<?>) child).isEmpty();\n\n\t\t\tif (\"2\".equals(query) || \"ALL\".equals(query)) { // 不判断 isEmpty，因为分页数据可能只是某页没有\n\t\t\t\tString totalKey = JSONResponse.formatArrayKey(key) + \"Total\";","sourceCodeStart":586,"sourceCodeEnd":622,"githubUrl":"https://github.com/Tencent/APIJSON/blob/5284052872898eddc449a58f629e5c8d588b8e22/APIJSONORM/src/main/java/apijson/orm/AbstractObjectParser.java#L586-L622","documentation":"Inside an array request '[]':{}, the first entry (index 0, the main table position when type == TYPE_ITEM) must be a table key 'TableKey':{}, not another array 'arrayKey[]':{}. onChildParse throws this when the very first child parsed for an array item is itself an array key, because the array's item template has no main table to anchor the query.","triggerScenarios":"\"[]\": { \"list[]\": [1,2], \"User\": { ... } } — any request where the first key inside '[]' ends with '[]'. Only subsequent positions may nest arrays.","commonSituations":"Reordering keys so a nested array lands first; JSON serializers that don't preserve insertion order putting 'something[]' before the main table; building the request from a Map with non-deterministic ordering.","solutions":["Put the main table object first inside '[]': \"[]\": { \"User\": {...}, \"list[]\": [...] }.","Use an ordered map (JSONObject preserves order; avoid HashSet/unordered structures) when constructing requests programmatically.","If no main table is intended, restructure so the nested array lives inside a table object rather than at array position 0."],"exampleFix":"// before\n\"[]\": { \"Comment[]\": { \"Comment\": {} }, \"User\": { \"id\": 1 } }\n// after\n\"[]\": { \"User\": { \"id\": 1 }, \"Comment[]\": { \"Comment\": {} } }","handlingStrategy":"validation","validationCode":"// first entry inside \"[]\" must not be an array key\nString firstKey = arrayRequest.keySet().iterator().next();\nif (firstKey.endsWith(\"[]\")) throw new IllegalArgumentException(\"first key inside [] must be a TableKey\");","typeGuard":"function firstArrayChildIsTable(entries: [string, unknown][]): boolean {\n  return !(entries[0]?.[0]?.endsWith('[]') ?? true);\n}","tryCatchPattern":null,"preventionTips":["Always put the main table object first inside '[]'.","Build requests with ordered maps (JSONObject / LinkedHashMap), never unordered dicts.","Assert on the client that position 0 inside '[]' is not an array key."],"tags":["apijson","array","main-table","ordering","request-syntax"],"backgroundTag":null,"analyzedSha":"5284052872898eddc449a58f629e5c8d588b8e22","analyzedAt":"2026-08-14T15:15:29.577Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}