应采用三步渐进式兼容策略：先共存新旧字段，再通过getter封装实现旧字段fallback逻辑，最后标记弃用并设定下线窗口期；字段类型变更须做兼容封装，如字符串→对象需保留原字段并新增对象字段，数组→对象需按客户端版本分流响应；必须通过影子流量和真实老旧UA测试验证兼容性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
旧版App、小程序或第三方系统还在读取userName字段，但业务要求新增firstName和lastName并逐步淘汰旧字段——直接改接口会导致大量客户端报undefined甚至崩溃。
先共存，再迁移，最后删除
第一步：在DTO中同时保留新旧字段。例如原Java类中已有private String userName;，现在新增private String firstName;和private String lastName;，并确保序列化时两者都输出。
第二步：设置旧字段的getter为兼容模式。比如getUserName()不直接返回userName，而是返回firstName + " " + lastName（若非空），或fallback到数据库原始userName字段。这样旧调用方拿到的值不变，不会触发toUpperCase()等链式调用报错。
第三步：在API文档中标记userName为Deprecated，并明确告知下线窗口期。这一步不能跳过，否则前端团队无法排期改造。
字段类型变更必须做兼容封装
方法一：字符串→对象的平滑过渡
如果原接口返回"avatar": "https://xxx.jpg"，现需升级为"avatar": {"url": "https://xxx.jpg", "width": 120, "height": 120}，绝不能直接替换DTO字段类型。应在DTO中保留String avatar字段，并新增AvatarObject avatarObject字段；同时在序列化前拦截，当avatar非空时，自动构造avatarObject并填充url字段，其余字段设默认值。
【不这样做会触发JSON解析异常：旧Android客户端用Gson解析时遇到对象字段直接抛JsonSyntaxException】
将来自 Marvis 或微信的可信远程软件开发请求中继至用户本地的 Codex CLI，等待编码任务完成，并返回经验证的结果。当用户通过 Codex 要求 Marvis 检查、实现、修复、测试、review 或继续在明确指定的本地项目目录中开展工作时，使用此功能。
方法二：数组→对象的降级兜底
若原返回"tags": ["bug", "ui"]，新版想改为"tags": [{"name": "bug", "type": "system"}, {"name": "ui", "type": "feature"}]，可在序列化层判断：若请求头带X-Client-Version: 1.2.0及以上，返回对象数组；否则仍返回字符串数组，并忽略type字段。
验证旧客户端是否真正兼容
启动一个影子流量通道，把线上真实请求复制一份发往灰度环境，在那里运行新DTO+旧字段逻辑，同时比对响应体与原生产环境的MD5差异。只要userName、avatar等关键字段值完全一致，就说明兼容层生效。
用curl模拟最老的iOS 12 WebView发起请求：curl -H "User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 12_0 like Mac OS X)" https://api.example.com/user/123，检查返回里userName是否存在且可被.split(" ")[0]安全调用。
这一步必须做，因为部分老旧Hybrid容器会缓存JSON Schema并校验字段类型，仅靠字段存在性不够。
