sales_order 表已经新增字段，后台也能显示，但 /V1/orders 接口没有该值。Magento Web API 基于 Service Contract 序列化，不会自动把任意数据库列暴露；需要 Extension Attribute 或正式数据接口。

固定复现条件

确认字段存在哪张表、何时保存、单订单接口与列表接口是否都缺失。检查生成的 OrderExtension 接口和 Repository get/getList 加载路径。

grep -R --line-number 'extension_attributes.*OrderInterface|attribute code=' app/code/Vendor/Module/etc 2>/dev/null
grep -R --line-number 'OrderRepositoryInterface' app/code/Vendor/Module 2>/dev/null
mysql -e "SHOW COLUMNS FROM sales_order LIKE 'custom_field'"
php bin/magento setup:di:compile
curl -sS -H 'Authorization: Bearer REDACTED' https://shop.example.com/rest/V1/orders/123

根据证据定位

只加数据库列不会进入 API；声明 Extension Attribute 但没有 hydrator/plugin 时值仍为空；get 生效而 getList 为空，通常是批量加载路径未覆盖。保存接口也需要把输入显式写入实体。

修复与回滚

在 extension_attributes.xml 声明合适类型，通过 Repository 插件或 extension join 加载，并使用资源模型保存。字段若含敏感数据，应先确认 ACL 与是否真的需要暴露。

验收

创建、读取、列表、更新订单均验证字段；无权限 Token 不得看到敏感值，批量接口避免 N+1 查询。

生产环境操作前的检查

处理“Magento 2 订单自定义属性没有出现在 REST API”前，先记录 Magento 版本、部署模式、问题 Store View、复现时间和最近发布。所有 SQL 默认先执行 SELECT；写操作、目录清理、服务重启和配置切换必须确认范围、保留备份并准备回滚。多节点环境还要核对构建版本、app/etc/env.php 配置摘要和实际流量节点。

php bin/magento --version
php bin/magento deploy:mode:show
php bin/magento maintenance:status
php bin/magento indexer:status
php bin/magento cache:status

命令应由 Magento 文件所有者在项目根目录执行。不要在生产高峰同时运行全量索引、静态部署和数据修复；涉及客户、支付、税费、库存或订单的变更，应先在脱敏数据副本验证。

建立可比较的排查记录

每次实验只改变一个变量，记录操作前值、命令、开始与结束时间、结果和回滚方式。至少准备一个正常对象和一个异常对象；旧对象恢复而新对象仍能复现，说明根因尚未消除。

检查层证据通过标准
入口 URL、状态码、请求 ID、节点 路由与协议一致
应用 异常堆栈、模块、作用域 无新异常且可重复
数据 主键、时间、关联行数 关系完整无重复副作用
业务 正常、失败与重试路径 最终状态一致

修复后的观察窗口

上线后至少观察一轮 Cron、队列和索引周期，并在两台节点、无痕浏览器与目标 Store View 重复验证。临时调试日志必须脱敏，确认错误率、响应时间和数据量稳定后及时关闭。