火山引擎结构化JSON输出默认不保证字段顺序，需用@JsonPropertyOrder注解、ObjectMapper配置或模板硬编码显式控制。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
火山引擎在处理结构化数据输出时，默认不保证 JSON 字段顺序与 Java 对象字段声明顺序或序列化时传入顺序一致，这会导致下游解析依赖字段位置的逻辑失败。必须显式干预才能稳定控制输出字段排列。
使用 Jackson 的 @JsonPropertyOrder 注解固定顺序
这是最直接、最可控的方式，适用于自定义 Java Bean 作为响应体或任务参数对象的场景。
第一步：在目标类顶部添加 【@JsonPropertyOrder({"id", "name", "status", "created_at"})】，括号内字符串数组按你期望的 JSON 键名顺序严格排列。
第二步：确保每个字段都有对应的 getter 方法，Jackson 默认只序列化 public getter 或 public 字段；若字段为 private 且无 getter，需额外加 @JsonProperty("field_name") 才能被识别并按序输出。
第三步：用 ObjectMapper 序列化该对象——此时生成的 JSON 字符串中，键的出现顺序将完全匹配注解中指定的数组顺序，不受字段在类中物理定义位置影响。
通过 ObjectMapper 配置全局字段排序策略
当无法修改实体类（如调用第三方 SDK 返回的对象），或需统一约束整个服务的输出风格时，可启用 ObjectMapper 的默认排序机制。
方法一：启用 ALPHABETICAL 排序
在初始化 ObjectMapper 实例后，执行 objectMapper.configure(SerializationFeature.ORDER_MAP_ENTRIES_BY_KEYS, true)。此后所有 Map 类型和未加 @JsonPropertyOrder 的 POJO 输出，字段都会按字母升序排列，比如 created_at 会排在 id 前面。
方法二：禁用默认排序以保留写入顺序
调用 objectMapper.setDefaultPropertyInclusion(JsonInclude.Include.NON_NULL) 后，再设置 objectMapper.configure(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY, false)。这能让 LinkedHashMap 等保持插入顺序的容器，在序列化时原样输出字段顺序——但前提是你的数据源本身是按需构造的 LinkedHashMap，而非普通 HashMap。
【注意：此方式对普通 Java Bean 无效，仅对 Map 及其子类生效】
在火山引擎自定义模板中硬编码字段顺序
当你使用 JSON 格式的自定义模板（如 AI MediaKit 任务配置）提交请求时，JSON 文本本身的书写顺序即为最终 API 解析顺序。火山引擎服务端在反序列化时采用 Jackson，默认开启 MapperFeature.ACCEPT_CASE_INSENSITIVE_ENUMS，但 【不重排原始 JSON 键顺序】。
因此，直接手写模板 JSON 时，把 required 字段放在前面，optional 字段靠后，就能控制输出结构的视觉与逻辑层次。例如：
{ "FormatVersion": "0.2", "Description": "智能剪辑主流程", "Parameters": {}, "Tasks": [], "Outputs": {} }
只要这个 JSON 文件里 "FormatVersion" 写在第一行，它在最终下发到执行节点的 payload 中就一定是第一个字段。
